From 04bf099fafdb74c6e0f3ca414673250edd58a16a Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 12 Sep 2026 00:10:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20DEPLOY=5FFLOW=20=E5=A2=9E?= =?UTF-8?q?=E8=A1=A5=20=C2=A75e=20figures=20=E6=9C=AC=E5=9C=B0=E5=9B=BE?= =?UTF-8?q?=E7=89=87=E6=BA=90/=C2=A75f=20BFF=20=E9=87=8D=E5=90=AF=E9=99=B7?= =?UTF-8?q?=E9=98=B1/=C2=A75g=20r4=20=E9=83=A8=E7=BD=B2=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/DEPLOY_FLOW.md | 55 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/DEPLOY_FLOW.md b/docs/DEPLOY_FLOW.md index 26d7701..e9dd7d3 100644 --- a/docs/DEPLOY_FLOW.md +++ b/docs/DEPLOY_FLOW.md @@ -334,6 +334,60 @@ VSTORE_EMBED_MODEL=bge-m3:567m - 短句（12 字）单次嵌入 4.1s；780 字长文本 1.0s（2026-09-10 实测，模型常驻后）； - 单篇文档全量嵌入（多 chunk 累计）约 52s 属历史实测值——功能正常，纯性能差距，无 GPU 机器属预期。 +### 5e. 论文图片本地源部署（figures 双源，2026-09-11 起部署必做） + +> BFF 答案配图走双源：本地 MinerU 图片优先，PMC 外网兜底。本地源三个条件缺一 +> 即**静默降级**为纯 PMC（无报错、无日志，唯一症状是配图变少或全走外网）。 + +1. **env 两键**（sdk/.env，与 BFF 同 env，BFF 重启后生效）： + + ```bash + PLANTAI_FIGURES_MINERU_ROOT=/srv/plantai/data/evaluation/methodology_upload_jobs + PLANTAI_FIGURES_REGISTRY=/srv/plantai/data/knowledge_base/paper_metadata_registry_v1_20260717/paper_metadata_registry_full.jsonl + ``` + +2. **registry 文件传输**：源机 `knowledge_base/paper_metadata_registry_v1_20260717/ + paper_metadata_registry_full.jsonl`（16.9MB）经 p2p 传到目标机上述路径；该文件 + 是 pmcid→paper_id 映射，缺失时本地索引即使有图也映射不出 PMCID。 +3. **BFF 重启**：必须手动 kill 旧 BFF（见 §5f 陷阱）。 + +**验证**：用 /tmp 假任务目录受控测试——`demo_job/mineru/paper/txt/*_content_list.json` +（type=image 条目）+ `methodology_papers.csv`（paper_id 取 registry 内带 pmcid 的）， +加载 figures 模块 `_build_local_index()` 应产出 `source=local` 条目；或部署后真实上传 +一篇 registry 内论文后提问验证。 + +**已知限制（2026-09-11 实测）**：本地图片只对「paper_id 在 registry 中」的任务命中； +历史 demo_paper/e2e_check 测试任务不产生本地图片索引。 + +### 5f. 部署陷阱：BFF 重启必须手动 kill（start_all 不替换在跑进程） + +**start_all.sh 不杀已运行的 BFF**：8090 被旧进程占住时，脚本内 uvicorn 新进程因端口 +占用静默退出，自检看到的仍是旧进程（新 env 不生效）。三步： + +```bash +pgrep -f "uvicorn app.main:app" | xargs kill # 1. 杀旧 BFF +cd install/sdk && set -a && . .env && set +a # 2. source env +setsid venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8090 > /tmp/plantai-sdk.log 2>&1 < /dev/null & +tr "\0" "\n" < /proc/$(pgrep -f "port 8090" | head -1)/environ | grep FIGURES # 3. 验证新 env 注入 +``` + +### 5g. r4 部署清单（2026-09-12，六项缺陷修复轮） + +1. **QA 双域相关性阈值**（qa/env/prod.env，可选；不设则用代码默认值）： + + ```bash + QA_MIN_VECTOR_SCORE=0.45 # 检索模式向量域（Qdrant score_threshold 同源） + QA_MIN_SOURCE_SCORE=0.25 # chat 模式最终域（rerank 后过滤） + ``` + +2. **MinerU 依赖 accelerate**：目标机 mineru 环境需 `pip install accelerate`——缺失 + 症状为启动期失败「requires accelerate」（r4 的自动重试会报中文可读错误但不会自愈）。 +3. **figures 两键 + registry**：见 §5e。 +4. **vstore 内容去重**：vault.add 按 SHA256 覆盖旧 doc，无需 env；存量重复数据如需清理 + 走 rebuild-index/rebuild-chunks 端点。 +5. **r4 前端 dist**：ui/dist 重构建（含 intent 词典「总结/概括/归纳」、KgPane 空态提示、 + SourceRow 标题 fallback、DocPane 状态机修复）。 + ## 6. 部署后完整质检（agent 逐条执行并记录结果，全过才算部署成功） ```bash @@ -477,4 +531,5 @@ NEO4J_URI=bolt://127.0.0.1:19888 NEO4J_PASSWORD='<密码>' bash deploy/qa-db/cre 4. **构建机与目标机若为同一台机器**（内网 192.168.0.175 现状），部署就是替换现有 `plantai-rag-new-deploy-unified/` 部署树；执行前先备份、执行后按 §6 全量质检。 5. 本手册基于 2026-09-08 服务器实测编写；如工具链或目录结构有变，先对照仓库实际脚本修正本手册再执行。 6. **当前生产服务器（192.168.0.175）仍是 0.0.0.0:8090 直连形态，尚未执行 §5b 的 nginx 迁移**——启动脚本默认值已改为 127.0.0.1，但现网进程仍是旧绑定；迁移时按 §5b 顺序执行（先 nginx 后改绑），不要直接无参重启 bff_restart.sh 以免客户访问断档。 +8. **start_all.sh 不会替换在跑的 BFF**（2026-09-11 实测）：BFF 更新 env/代码后必须手动 kill + 重启，详见 §5f。 7. **175 上 QA 数据库 docker 容器（27333/19788）为其他项目共享服务，不随 PlantAI 部署流程管理**；PlantAI-rag-new 一律走裸进程（§5.0/5.0b）；遗留库（26333/18788）现网无引用，清理需用户单独命令。