gqt
70 lines
2.2 KiB
Markdown
70 lines
2.2 KiB
Markdown
# 智能体知识库问答系统
|
|
|
|
本项目是本地单用户双 Agent 知识库问答系统。权威需求见
|
|
`docs/superpowers/specs/2026-07-13-kbqa-system-design.md`；原始 `architecture.md`
|
|
仅作为历史参考，不作为实现依据。
|
|
|
|
## 环境要求
|
|
|
|
- Python 3.12，由 `uv` 管理
|
|
- Node.js 与 npm
|
|
- 单进程 Uvicorn；禁止配置多个 worker
|
|
|
|
## 本地配置
|
|
|
|
`.env` 是唯一运行配置来源，所有变量均为必填项；程序不提供运行参数默认值。复制
|
|
`.env.example` 为 `.env`，阅读每项中文注释并填写真实值。必须从**项目根目录**执行下列
|
|
命令，否则相对路径和 `.env` 文件位置会改变。`.env`、`1.md`、`test.txt` 均被 Git 忽略。
|
|
LangSmith 会接收 Agent 输入、工具结果和运行轨迹。
|
|
|
|
首次运行前建立本地数据目录：
|
|
|
|
```bash
|
|
mkdir -p data/raw data/milvus
|
|
```
|
|
|
|
## 后端
|
|
|
|
```bash
|
|
cd "$(git rev-parse --show-toplevel)"
|
|
uv sync --project backend --all-groups
|
|
mkdir -p data/raw data/milvus
|
|
uv run --project backend alembic -c backend/alembic.ini upgrade head
|
|
uv run --project backend uvicorn kbqa.main:app --app-dir backend/src --host 127.0.0.1 --port 8000
|
|
```
|
|
|
|
`--port` 必须与 `web/vite.config.ts` 中 `/api` 代理目标的端口一致。仓库默认示例为
|
|
`8000`；若你本地将代理改为 `8003`，后端也必须使用 `--port 8003`。
|
|
|
|
## 前端
|
|
|
|
```bash
|
|
cd "$(git rev-parse --show-toplevel)"
|
|
npm --prefix web install
|
|
npm --prefix web run dev -- --host 127.0.0.1
|
|
```
|
|
|
|
## 普通验证
|
|
|
|
普通验证不会调用 Chat 或 Embedding 模型：
|
|
|
|
```bash
|
|
uv run --project backend ruff format --check backend/src backend/tests
|
|
uv run --project backend ruff check backend/src backend/tests
|
|
uv run --project backend pytest backend/tests/unit backend/tests/integration -v
|
|
npm --prefix web run lint
|
|
npm --prefix web run test -- --run
|
|
npm --prefix web run build
|
|
```
|
|
|
|
## 真实调用验证
|
|
|
|
只有显式设置 `KBQA_RUN_LIVE_TESTS=1` 才执行真实模型测试：
|
|
|
|
```bash
|
|
KBQA_RUN_LIVE_TESTS=1 uv run --project backend pytest backend/tests/live -v -s
|
|
```
|
|
|
|
真实测试通过 HTTP 调用实际 Uvicorn 服务，并调用真实 DashScope Chat、Embedding
|
|
和 LangSmith。不得在输出、报告或截图中记录密钥。项目验收后建议轮换本地测试密钥。
|