knowledge-platform/docs/development/LIVE_ACCEPTANCE.md

2.8 KiB
Raw Blame History

ARCH-006 受控真实链路验收

本验收覆盖 OceanBase canonical relational metadata → BOS immutable source → 千帆 bge-large-zh → OceanBase Vector → 千帆 bce-reranker-base → canonical Source Result。数据集包含 32 条完全合成、脱敏 Query,不含真实客户、产品、政策或内部知识。

强制安全门禁

只有同时满足以下条件才允许执行:

  1. 数据库、BOS 和千帆凭据已经所有者明确授权;配置清单中的现有值只允许本次 test 验收临时注入,禁止保存为 .env、写入日志或用于 fat/prod,完成后仍必须轮换;
  2. OceanBase Database/Table 和 BOS Bucket/Prefix 已明确授权用于测试;
  3. APP_ENV=test;
  4. BOS_KEY_PREFIX 以 live-acceptance/ 开头,避免写入共享业务前缀;
  5. 显式设置 EKP_RUN_LIVE_TESTS=1、EKP_CREDENTIALS_AUTHORIZED=1 和 EKP_LIVE_RESOURCE_ACK=1。

任一条件不满足时,命令在创建 Provider 或外部连接前失败关闭,并且不输出 Endpoint、用户 名、SQL、响应正文、Chunk 内容或 Secret。仓库 .env.example 中三个开关固定为 0。

执行顺序

先完成 ARCH-005 切换:

uv run alembic upgrade head
uv run ekp-index-rebuild build
uv run ekp-index-rebuild verify
uv run ekp-index-rebuild activate

确认 verify 和 activate 输出的 complete 均为 true 后,再运行:

make live-acceptance

命令会使用随机运行前缀上传两份合成 Markdown,执行全部 32 条 Query,并在 finally 清理 本次运行的 OceanBase Vector 行、canonical Document/Chunk/State 以及 BOS 对象。清理失败会使验收 失败,且不会尝试删除不带本次随机文件名前缀的数据。

验收指标

默认门槛:

Recall@1       >= 0.90
Recall@5       = 1.00
MRR            >= 0.90
NDCG@5         >= 0.90
Search P95     <= 10000 ms

输出只包含 Query 数、Recall@1/3/5、MRR、NDCG@5、P50/P95 和 passed。如受控环境需要调整 门槛,只能通过 EKP_LIVE_MIN_* / EKP_LIVE_MAX_P95_MS 显式注入,并把实际门槛与结果记录 到受保护的验收日志;不要把 Endpoint、账号、凭据或原始响应提交到仓库。

验收结果(2026-09-02)

目标 test OceanBase 已完成 migration、专用向量表/HNSW、PRE-FILTER、BOS、Embedding、 Reranker 和 canonical Source Result 验收。32 条查询结果:Recall@1/3/5、MRR、NDCG@5 均为 1.0,P50 3787.61 ms,P95 4759.21 ms,passed=true。正式命令退出码为 0,数据库 复核 live- Document/Chunk/Vector 残留为 0。

首次正式运行出现过一次无细节瞬时失败;分阶段 Provider/单文档/32 查询诊断以及随后正式 运行均通过。后续稳定性任务应补充有界重试、限流指标与告警;这不阻塞本次受控验收。