FAROS

环境要求

• Python 3 环境（后端使用 python3 -m venv 创建虚拟环境）
• Node.js 与 npm（前端使用 npm ci / npm run dev）
• Git（用于克隆仓库）
• 可访问的 LLM 服务端点、API Key 与模型 ID

安装与启动步骤

1. 1克隆仓库

   把 FAROS 仓库克隆到本地并进入后端目录，后续命令都在 backend 下执行。

   git clone https://github.com/OpenNSWM-Lab/FAROS.git
   cd FAROS/backend

   复制

2. 2创建并激活环境

   在 backend 目录创建 Python 虚拟环境并激活，之后安装的依赖都装在该环境中。

   python3 -m venv .venv
   source .venv/bin/activate

   复制

3. 3安装后端依赖

   先升级 pip，再按 requirements.txt 安装后端依赖，网络慢时可换国内镜像。

   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt

   复制

4. 4启动后端服务

   用 uvicorn 启动后端，监听 127.0.0.1:8005，--reload 便于开发调试。

   uvicorn app.main:app --host 127.0.0.1 --port 8005 --reload

   复制

5. 5安装前端依赖

   另开一个终端，回到仓库根目录进入 frontend，用 npm ci 按锁文件安装依赖。

   cd frontend
   npm ci

   复制

6. 6启动前端服务

   通过 VITE_API_BASE_URL 指向后端地址启动开发服务器，打开 5176 端口页面。

   VITE_API_BASE_URL=http://127.0.0.1:8005 npm run dev

   复制

7. 7配置模型服务

   在设置/LLM Providers 中选 Provider，填 API Key、Base URL 和模型名，保存后测试连接并设为当前使用项。

8. 8走通科研流程

   进入科研流程，描述研究问题，检查文献与候选选题，确认计划后生成代码、跑实验并在 ReviewX 审核。

关键配置

如何确认成功

前端打开 http://127.0.0.1:5176 可正常加载，后端 http://127.0.0.1:8005/api/docs 能打开交互式 API 文档。

常见问题

注意事项

• 前端命令要在仓库根目录下进入 frontend 后执行，后端命令在 backend 目录执行。
• source .venv/bin/activate 为 macOS/Linux 用法，Windows 需改用对应虚拟环境激活方式。
• 真实 API Key 应通过账号设置或服务器环境注入，切勿提交到 Git 仓库。
• 更完整的部署方式参考仓库中的 deploy/README.md。