docs: README 按最新状态更新(终态拓扑 8090-8093、统一 venv、一键打包、实际库计数)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
jerry
@@ -1,81 +1,101 @@
|
||||
# PlantAI-rag-new —— 植物基因家族文献知识工作台
|
||||
|
||||
海古纪 PlantAI 的知识问答工作台：基于文献知识库（100 篇论文 / 44,595 条关系断言 / 382 万实体）的
|
||||
基因家族问答系统。采用 `plantai-agent-ui-prototype` 的视觉设计（深色默认、青紫渐变、Agent 五相位时间线），
|
||||
支持桌面 / 平板 / 手机四档响应式。
|
||||
海古纪 PlantAI 的知识问答工作台：基于文献知识库(31,207 篇论文 / 824 万条关系断言 / 382 万 canonical 实体 / 631 万 normalized 实体)的基因家族问答系统。采用 `plantai-agent-ui-prototype` 的视觉设计(深色默认、青紫渐变、Agent 五相位时间线),支持桌面 / 平板 / 手机四档响应式。
|
||||
|
||||
**架构**：薄适配层（BFF）+ 全新前端，不重写 RAG 算法。上游为现有运行中的服务，本项目只读消费。
|
||||
**架构**：四部分结构——① UI 前端(Vue3+Vite,开源) ② SDK 中间层(BFF,Cython 编译 .so) ③ Agent 底层服务(完全编译,仅 shell 启动) ④ 独立向量知识库(加密打包)。数据后端(Qdrant/Neo4j)只读消费,本项目不重写 RAG 算法。
|
||||
|
||||
```
|
||||
浏览器 ──> BFF (FastAPI, 127.0.0.1:8090) ──> QA 7920（问答引擎）
|
||||
│ ├─> RAG 8000/7900（论文抽取）
|
||||
│ └─> Neo4j 18788（知识图谱，Bolt 直连）
|
||||
└─> SQLite（会话历史，WAL）
|
||||
浏览器 ──> BFF 8090 (FastAPI, venv py3.12.13, 静态托管 ui/dist)
|
||||
├─> QA 8091 agent/qa 编译树(45 .so,断言锚定 1.1.73)
|
||||
├─> RAG 8092 agent/methodology 编译树(28 .so,论文抽取)
|
||||
├─> legacy 8093 agent/legacy-rag 编译树(283 .so,旧路由族)
|
||||
├─> Neo4j 18788 知识图谱(Bolt 直连)
|
||||
└─> SQLite sdk/data/plantai.db(会话历史,WAL)
|
||||
```
|
||||
|
||||
## 目录
|
||||
|
||||
```
|
||||
sdk/ BFF（app/ 应用代码，mock/ 前端开发用 mock server）
|
||||
ui/ Vue 3 + Vite 前端（src/ 源码）
|
||||
agent/ 底层服务：qa / methodology / legacy-rag + vendor 共享池（编译交付）
|
||||
knowledge/ 向量知识库打包定义（数据不入 git）
|
||||
tooling/ 统一打包工具（编译/加密/组装）
|
||||
docs/ 全部文档：PRD / API / UI_SPEC / ARCHITECTURE / TEST_PLAN / TEST_CASES / DISCOVERY / 测试报告
|
||||
deploy/ 部署脚本：sync.sh（本地→远端）、bff_restart.sh、start-dev.sh、集成检查、E2E 验收
|
||||
tests/ 测试（sdk 接口、ui 单元、e2e）
|
||||
sdk/ BFF(app/ 应用代码,mock/ 前端开发用 mock server)
|
||||
ui/ Vue 3 + Vite 前端(src/ 源码,dist/ 由 BFF 静态托管)
|
||||
agent/ 底层服务:qa / methodology / legacy-rag + vendor 共享池(编译交付)
|
||||
knowledge/ 向量知识库打包定义(数据不入 git)
|
||||
tooling/ 统一打包工具(编译/审计/加密/组装,一键 build_all.sh)
|
||||
docs/ 全部文档:PRD / API / UI_SPEC / ARCHITECTURE / TEST_PLAN / TEST_CASES / DISCOVERY / 测试报告
|
||||
deploy/ 部署脚本:sync.sh(本地→远端)、bff_restart.sh、start-dev.sh、集成检查、E2E 验收
|
||||
tests/ 测试(sdk 接口、ui 单元、e2e)
|
||||
```
|
||||
|
||||
## 快速启动（远端）
|
||||
## 运行环境(2026-09-01 起:统一 venv,不再依赖 conda)
|
||||
|
||||
- **统一 venv**:`/home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv`(Python 3.12.13,130 包)
|
||||
- 依赖固化:`tooling/requirements.lock`;环境重建 = `python -m venv <路径> && pip install -r tooling/requirements.lock`
|
||||
- 运行、编译、打包全部只用 venv;历史 conda 环境(gfpy312/plantai-bff/test4py311)是其他产品线共享,未删除但本项目不再引用
|
||||
- MinerU 文档解析为外部子进程(独立 conda 环境 minerupy312,经 `MINERU_CMD` 覆盖,不进本项目环境)
|
||||
|
||||
## 快速启动(远端)
|
||||
|
||||
```bash
|
||||
# 1. 启动 BFF（自动激活 conda plantai-bff）
|
||||
ssh 100.109.52.26 'bash ~/5090/teamWorkspace/zh/PlantAI-rag-new/deploy/bff_restart.sh'
|
||||
# 1. 三个 agent 服务(编译树,终态端口;均 venv python)
|
||||
D=/home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified
|
||||
(cd $D/qa && bash scripts/start.sh 8091)
|
||||
(cd $D/methodology && bash scripts/start.sh 8092)
|
||||
(cd $D/legacy-rag && bash scripts/start.sh 8093)
|
||||
|
||||
# 2. 启动 Vite 开发服务器（开发模式）
|
||||
ssh 100.109.52.26 'cd ~/5090/teamWorkspace/zh/PlantAI-rag-new/ui && \
|
||||
VITE_BFF_TARGET=http://127.0.0.1:8090 setsid nohup npm run dev > /tmp/plantai-vite.log 2>&1 < /dev/null & disown'
|
||||
|
||||
# 3. Mac 侧访问隧道
|
||||
ssh -N -L 5180:127.0.0.1:5180 -L 8090:127.0.0.1:8090 100.109.52.26
|
||||
# 浏览器打开 http://localhost:5180
|
||||
# 2. BFF(venv,静态托管;默认绑 127.0.0.1,公网演示传 0.0.0.0)
|
||||
ssh 100.109.52.26 'bash ~/5090/teamWorkspace/zh/PlantAI-rag-new/deploy/bff_restart.sh 0.0.0.0'
|
||||
```
|
||||
|
||||
生产形态：`npm run build` 产出 `ui/dist`，BFF 启动时自动静态托管，单进程从 `:8090` 直接服务。
|
||||
生产形态:`npm run build` 产出 `ui/dist`,BFF 单进程静态托管,`http://<host>:8090` 直接服务。
|
||||
|
||||
## 一键打包
|
||||
|
||||
```bash
|
||||
cd tooling && bash build_all.sh [版本] # 四树编译 → 双审计 → 冒烟 → 组装 install/
|
||||
```
|
||||
|
||||
产物 `tooling/build/<版本>/install/`(sdk + 三 agent 编译树 + ui/dist + start_all.sh + SHA256SUMS + 泄露门禁)。
|
||||
P6 空目录安装验收(备用端口 8094/8095/8096/8097)待执行。
|
||||
|
||||
## 开发工作流
|
||||
|
||||
- **本地编辑** `/Users/jerry/haiguji/PlantAI-rag-new/`，**远端运行** `/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/`
|
||||
- 同步（PM 执行）：`bash deploy/sync.sh`（rsync，排除 node_modules/venv/data/dist）
|
||||
- 前端开发期 API 指向 mock（8099，`scenario=normal|empty|slow|error|degraded` 经 `X-Mock-Scenario` 头切换）；
|
||||
- **本地编辑** `/Users/jerry/haiguji/PlantAI-rag-new/`,**远端运行** `/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/`
|
||||
- 同步(PM 执行):`bash deploy/sync.sh`(rsync,排除 node_modules/.venv/data/dist)
|
||||
- 前端开发期 API 指向 mock(8099,`scenario=normal|empty|slow|error|degraded` 经 `X-Mock-Scenario` 头切换);
|
||||
集成期 `VITE_BFF_TARGET=http://127.0.0.1:8090` 指向真实 BFF
|
||||
- 契约文档（docs/）是开发与测试的唯一依据，变更需 PM 裁决
|
||||
- 契约文档(docs/)是开发与测试的唯一依据,变更需 PM 裁决
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
# 后端（conda plantai-bff 或本地 .venv-backend）
|
||||
cd sdk && python -m pytest . -q # 单元 + 接口
|
||||
# 后端(统一 venv)
|
||||
cd sdk && /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python -m pytest . -q
|
||||
# 前端
|
||||
cd ui && npx vitest run --config vitest.config.js # 单元 + 组件
|
||||
cd ui && npx playwright test # E2E 三档视口（mobile/tablet/desktop）
|
||||
cd ui && npx playwright test # E2E 三档视口(mobile/tablet/desktop)
|
||||
# 上游连通冒烟
|
||||
bash tests/smoke_upstreams.sh
|
||||
```
|
||||
|
||||
## 上游与端口
|
||||
## 上游与端口(终态,2026-09-01)
|
||||
|
||||
| 服务 | 端口 | 说明 |
|
||||
|---|---|---|
|
||||
| QA V1.1.73（问答引擎） | 7920 | 只读消费；LLM 依赖 DeepSeek 余额 |
|
||||
| Gene Family RAG System（抽取） | 8000 | 回落 7900 |
|
||||
| Neo4j（知识图谱） | 18788 | canonical schema，Bolt 直连 |
|
||||
| SDK 中间层(BFF) | 8090 | venv py3.12.13,静态托管 ui/dist,**唯一对外端口** |
|
||||
| QA 问答引擎(agent/qa) | 8091 | 编译树 45 .so,版本 `1.1.73-assertion-anchored`,绑 127.0.0.1 |
|
||||
| Methodology 提取(agent/methodology) | 8092 | 编译树 28 .so,绑 127.0.0.1 |
|
||||
| legacy 旧路由族(agent/legacy-rag) | 8093 | 编译树 283 .so(app 3 路由 / main 11 族),绑 127.0.0.1 |
|
||||
| Neo4j(知识图谱) | 18788 | canonical schema,Bolt 直连 |
|
||||
|
||||
- 回滚窗(停而不删,30 天):QA 容器 `qa-normalized-formal-20260828`(7920)、methodology 宿主进程(8000)、7900 protected 容器
|
||||
- 回滚方法:重启旧服务 + `sdk/.env` 加回四行覆盖(`QA_BASE_URL`/`RAG_BASE_URL`/`RAG_LEGACY_BASE_URL`/`RAG_ALT_BASE_URL`)→ `bff_restart`
|
||||
|
||||
## 已知限制
|
||||
|
||||
- 上游 QA 无 token 级流式（答案在终态一次返回），打字机为客户端揭示动画
|
||||
- 每次提问独立检索（`max_rounds:1`），无多轮上下文
|
||||
- DeepSeek 余额用尽时答案退化为证据列表（检索/图谱/来源不受影响）
|
||||
- 上游 QA 无 token 级流式(答案在终态一次返回),打字机为客户端揭示动画
|
||||
- 每次提问独立检索(`max_rounds:1`),无多轮上下文
|
||||
- DeepSeek 余额用尽时答案退化为证据列表(检索/图谱/来源不受影响)
|
||||
- KG `/overview` 慢查询(1644 万边聚合,既有问题,60s 超时返回 503 信封;`/api/kg/status` 快路径正常)
|
||||
|
||||
详细设计见 `docs/`：PRD.md（81 个功能点）、API.md（BFF 契约）、UI_SPEC.md（设计令牌）、
|
||||
ARCHITECTURE.md（分工与协作约定）、DISCOVERY.md（上游探测事实）、TEST_PLAN.md（测试纪律）。
|
||||
详细设计见 `docs/`:PRD.md(81 个功能点)、API.md(BFF 契约)、UI_SPEC.md(设计令牌)、
|
||||
ARCHITECTURE.md(分工与协作约定)、DISCOVERY.md(上游探测事实)、TEST_PLAN.md(测试纪律)。
|
||||
|
||||
Reference in New Issue
Block a user