YoVinchen
f4ba5d5342
The Stage 1 foundation now proves provider contracts with mocks and validates PostgreSQL/pgvector ingestion, approval binding, retrieval, reranking, and idempotency using only synthetic data. Live Bailian validation remains gated on rotating the exposed key. Constraint: The key shown in chat is compromised and cannot be used or committed Rejected: Mark Stage 1 complete from mock and offline results | real three-model smoke is still required Confidence: high Scope-risk: moderate Reversibility: clean Directive: Do not enable real-data ingestion until Stage 3 cloud approval and outbound manifest controls are enforced end to end Tested: make verify; 41 pytest tests; strict mypy; Ruff; Compose config; pinned image build; empty-volume migration; role denial; two idempotent 20-vector seeds; database restart persistence Not-tested: Live Bailian calls require a newly rotated key; React product UI is not implemented
4.4 KiB
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 db migrate
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 的实际流程是：
- 只接受
source_type=synthetic且处于LOCAL_PARSED_PENDING_CLOUD_REVIEW的 20 条样例； - 每批最多 10 条生成 1024 维向量；
- 用 UUIDv5 生成稳定的 document/version/chunk ID；
- 实算
cloud_text、embedding_text、profile 和 outbound manifest SHA-256； - 先写 manifest 成员，再绑定
CLOUD_APPROVED，最后原子激活文档版本； - 仅从当前 active、READY、同 access scope 的 searchable chunk 召回；
- 对 Top K 候选重排并输出虚构问题的 Hit@3；
- 相同输入再次执行使用相同 ID 和幂等 upsert，不增加行数。
3. 真实百炼能力探测
完成旧 Key 轮换后：
- 将
.env.example复制为未提交的.env； - 把
<workspace-id>替换为同一个北京地域 MaaS 工作空间 ID； - OpenAI 兼容 URL 以
/compatible-mode/v1结尾； - Rerank URL 以
/compatible-api/v1结尾； - 本项目不使用用户提供的
/apps/anthropic地址； - 通过隐藏输入写入新 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。