# Stage 1 PoC 运行手册

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

## 1. 安全前置

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

初始化本地数据库 Secret：

```bash
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 向量和词法重排器，只验证数据治理、批处理、迁移、向量写入、权限过滤、检索、重排和幂等性，不把它当成真实模型质量。

```bash
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` 的容器。

```bash
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
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：

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

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

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

## 4. 质量门禁与排障

```bash
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 约束和事务日志 |

停止服务但保留数据：

```bash
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`。