RAG/docs/05-stage1-runbook.md

Stage 1 PoC 运行手册

本手册只运行最小后端、PostgreSQL/pgvector、三模型能力探测和 20 条虚构数据 PoC。它不代表完整 React 产品已经完成。

1. 安全前置

聊天中曾出现的旧百炼 Key 必须先在控制台重置或删除。仓库没有保存、使用或回显该值；新的 Key 也只能进入被 .gitignore 排除的 secrets/bailian_api_key。

初始化本地数据库 Secret：

make setup-hooks
make backend-sync
bash scripts/init-local-secrets.sh

脚本生成三组彼此不同的 PostgreSQL 密码，以及互不相同的 model_gateway_api_token、model_gateway_worker_token，文件权限为 0600。不带 --with-bailian 时不会创建或修改百炼 Key；若本地已存在 Key，脚本会明确提示保留原文件。

2. 离线数据库与向量 PoC

离线模式使用确定性的 1024 维 feature-hash 向量和词法重排器，只验证数据治理、批处理、迁移、向量写入、权限过滤、检索、重排和幂等性，不把它当成真实模型质量。

docker compose up -d --build web
docker compose --profile tools run --rm seed-demo-offline
docker compose --profile tools run --rm seed-demo-offline

验收输出应满足：

• 两次均为 status=ok；
• counts.chunks = counts.vectors = counts.searchable = 20；
• 第二次运行计数不增长；
• 输出只含计数、模型标识、模式和聚合指标，不含文档正文、数据库密码或 Key。

Seed 的实际流程是：

1. 只接受 source_type=synthetic 且处于 LOCAL_PARSED_PENDING_CLOUD_REVIEW 的 20 条样例；
2. 每批最多 10 条生成 1024 维向量；
3. 用 UUIDv5 生成稳定的 document/version/chunk ID；
4. 实算 cloud_text、embedding_text、profile 和 outbound manifest SHA-256；
5. 先写 manifest 成员，再绑定 CLOUD_APPROVED，最后原子激活文档版本；
6. 仅从当前 active、READY、同 access scope 的 searchable chunk 召回；
7. 对 Top K 候选重排并输出虚构问题的 Hit@3；
8. 相同输入再次执行使用相同 ID 和幂等 upsert，不增加行数。

2.1 查看后端运行效果

内部 API 只连接 internal data + model，挂载 app 数据库 Secret 和 API 内部 token，不连接公网，也不挂载百炼 Key。独立 model-gateway 只连接 internal model + egress，是唯一挂载百炼 Key 的服务；它不连接数据库、不挂载上传卷、不发布端口。真实 provider-smoke 和 seed-demo 也只通过内部 token 调用该服务，不直持 Key。无数据库/模型 Secret 的入口 gateway 连接 internal ingress/data；React/Nginx Web 连接 edge/ingress，并且是唯一发布到本机回环地址 127.0.0.1:8000 的容器。

curl http://127.0.0.1:8000/health/live
curl http://127.0.0.1:8000/health/ready
curl http://127.0.0.1:8000/api/v1/demo/status
curl -X POST http://127.0.0.1:8000/api/v1/demo/search \
  -H 'Content-Type: application/json' \
  --data '{"query":"花岗斑岩铜矿化特征","top_k":3}'

预期结果：

• readiness 返回 database=ok；
• demo status 返回 chunks/vectors/searchable = 20/20/20；
• search 只返回 synthetic-demo 数据集中的合成标题、批准后的片段、页码、分数和不透明 citation ID；
• Swagger 位于 http://127.0.0.1:8000/docs。

该接口是 Stage 1 的离线可见效果，不调用百炼，也不代表完整问答生成链或 React 前端已经完成。

3. 真实百炼能力探测

完成旧 Key 轮换后：

1. 将 .env.example 复制为未提交的 .env；
2. 把 <workspace-id> 替换为同一个北京地域 MaaS 工作空间 ID；
3. OpenAI 兼容 URL 以 /compatible-mode/v1 结尾；
4. Rerank URL 以 /compatible-api/v1 结尾；
5. 本项目不使用用户提供的 /apps/anthropic 地址；
6. 通过隐藏输入写入新 Key：

bash scripts/init-local-secrets.sh --with-bailian
docker compose --profile tools run --rm provider-smoke

provider-smoke 以 API 内部身份调用 model-gateway，再由后者依次验证：

• text-embedding-v4 返回 1 个 1024 维有限非零向量；
• qwen3-rerank 返回可映射到本地候选的下标和分数；
• deepseek-v4-flash 在 enable_thinking=false、enable_search=false 下产生 SSE 文本。

探测只输出 capability、status、模型、耗时、request ID 和脱敏错误类别。URL 必须属于同一个 *.cn-beijing.maas.aliyuncs.com 工作空间，否则在读取 Key 前拒绝运行。

三模型通过后，可让同一批虚构数据走真实 Embedding/Rerank：

docker compose --profile tools run --rm seed-demo
docker compose --profile tools run --rm seed-demo

真实模式使用 Worker 内部身份，仍只允许本仓库的虚构样例。三能力和真实 seed 均成功后，可按 文档入库运行手册 将服务端 DOCUMENT_NAMESPACE_MODE 切到 bailian，用上传/审核链验证真实向量写库。正式认证、RBAC、 资料许可、涉密和云处理审批未完成前，不得把私有或真实地质报告送入这条链路。

截至 2026-07-13，已通过独立 model-gateway 重跑三项真实调用：三项都到达供应商，但均返回安全脱敏的 authentication 类别（内部非流式调用由 Gateway 以 502 封装，Chat SSE 以终态错误事件返回；根因仍是供应商鉴权失败）。此时应核对 Key 所属工作空间、北京地域、专属端点、计费方案和模型权限，不要反复自动重试。在三项成功前不得声明百炼接入验收通过。

4. 质量门禁与排障

make verify
docker compose ps -a
docker compose logs --no-log-prefix migrate

常见失败：

现象	处理
invalid_local_configuration	检查是否仍是占位 URL、两个 URL 是否同一北京工作空间、新 Key 文件是否存在
migrate 等不到 DB	检查三个数据库 Secret 是否存在且互不相同；查看 bootstrap 日志
migrate 显示 Exited (0)	正常：它是一次性 Alembic 服务，成功升级到 head 后就应退出；只有非 0 或反复重启才是故障
401/403	不重试风暴；检查新 Key、工作空间和模型授权
429/5xx/timeout	适配器执行有界指数退避；持续失败时保留脱敏 request ID 后停止
seed 计数不是 20	不进入下一阶段；检查迁移、manifest 约束和事务日志

停止服务但保留数据：

docker compose down

不要在需要保留验证证据时执行 docker compose down -v，因为它会删除 PostgreSQL volume。

5. 当前完成边界

可在没有可用百炼权限时验收：配置/Secret 安全、内部 token 身份、MockTransport 契约、离线 向量/重排、Compose 渲染、迁移、20 条写入和幂等。后续阶段现已实现上传、本地解析、manifest 审核、向量化、正式检索、Grounded Chat、双 Worker 和 synthetic 评测；这些能力不能反向证明 真实供应商可用。只有有效 Key 完成三模型真实 smoke 与真实 seed 后，Stage 1 的真实模型子门禁 才能从 BLOCKED 改为 DONE。