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 密码，文件权限为 0600。不带 --with-bailian 时不会创建模型 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 网络，只挂载 app 数据库 Secret，不连接外网，也不挂载百炼 Key。无 Secret、无数据库凭证的 gateway 连接 internal ingress/data；React/Nginx Web 连接 edge/ingress，并且是唯一发布到本机回环地址 127.0.0.1:8000 的容器。三个运行容器均使用非 root 用户、只读根文件系统并移除 Linux capabilities。

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 依次验证：

• 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

真实模式仍只允许本仓库的虚构样例；任何真实地质报告必须等 Stage 3 的许可、涉密和 outbound manifest 审核链完成。

4. 质量门禁与排障

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

常见失败：

现象	处理
invalid_local_configuration	检查是否仍是占位 URL、两个 URL 是否同一北京工作空间、新 Key 文件是否存在
migrate 等不到 DB	检查三个数据库 Secret 是否存在且互不相同；查看 bootstrap 日志
401/403	不重试风暴；检查新 Key、工作空间和模型授权
429/5xx/timeout	适配器执行有界指数退避；持续失败时保留脱敏 request ID 后停止
seed 计数不是 20	不进入下一阶段；检查迁移、manifest 约束和事务日志

停止服务但保留数据：

docker compose down

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

5. 当前完成边界

可在没有百炼 Key 时验收：配置/Secret 安全、MockTransport 契约、离线向量/重排、Compose 渲染、空卷迁移、20 条写入和幂等。只有轮换后的新 Key 完成三模型真实 smoke 与真实 seed 后，Stage 1 才能从 IN_PROGRESS 改为 DONE。