🏠 总目录📚 本教程 17g · 冷启动知识覆盖与启动验收 ← →

智能体工程 · 17g

冷启动演示有答案,哪些知识缺口仍阻止上线?

读完能做的判断:提前固定受众、题目与门槛,按正确分母区分覆盖和检索缺口。

冷启动知识覆盖与启动验收:先证明种子知识能被找到

⏱ 阅读约 27 分钟 · 动手实践另计

本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。

一句话:冷启动先检查明确受众的种子知识覆盖、真实检索和未知问题,再决定是否送人工复核。

一个虚构设备助手刚建立知识库,只有两份种子文档,既缺材料,也缺使用反馈。此时“程序启动了”不能说明常见问题已经有依据。本章使用公开练习题,让同一受众在两种知识范围下真实检索,找出下一步需要复核的缺口。

先读失败样本复核与改进队列,理解反馈怎样成为待办;再用数据集泄漏检查与冻结验收约束题目版本。本章以 bootstrap_lab.py 为教学示例。实验声明 no-model,没有生成答案或实际部署。

1. 给“启动就绪”指定受众

本章可信调用方提供租户 a、用户 alice 和 knowledge:read scope。程序先检查当前 scope,再读真实可见块。缺 scope 是拒绝访问,不能算“没有知识”。身份来自教学调用方的约定;脚本没有登录服务,也不能证明某个现实用户的身份。

starter 只导入 xr200、vpn。expanded 固定增加 xr300、expense、limits、leave、refund、incident,共八份 a 租户文档。两阶段分别在新的临时 SQLite 库中运行 core.init 和 core.ingest,原始 corpus 与 manifest 只读。

不把 private、b 租户或 poison 文档纳入正式阶段。某份资料管理员可以导入,不意味着 alice 可以读取。阶段检查只描述这个受众对公开夹具的表现,不能扩展成所有租户就绪。

检查点 1:没有 knowledge:read 时,应记录知识缺口吗?

不应。先拒绝 scope,避免把权限问题当缺材料。核对要点:说出受众 a/alice。走神救援:只找两阶段的文档名单,不研究认证平台。

2. 在观察成绩之前固定题目

夹具 evaluation/bootstrap-cases.json 有 14 道原创题,其中 12 道有 gold、2 道无 gold。它覆盖八份正式文档;两道需要两份资料,两道设备题标成 critical。gold 是人工事先指定的相关文档集合,不是程序根据检索结果补写的答案。

每题恰好四个字段:case_id、query、expected_doc_ids、critical。ID 是有限长度的安全 ASCII;query 必须是非空 UTF-8,最多 2000 字符。gold 最多八个唯一 ID,critical 必须严格为布尔值,无 gold 不能标 critical。

整个列表最多 100 条,题号与原始 query 都不能重复。未知字段、重复 JSON 键、非法类型被固定错误拒绝。不要为了让检索得分漂亮,改写英文题或删除未知型号题;那会失去原来的比较对象。

检查点 2:看到英文题漏召回,可以把 gold 清空吗?

不能。题目版本必须先固定,漏召回应保留在结果里。核对要点:区分人工 gold 与自动候选。走神救援:检查 boot-11 在两阶段是否仍是同一道题。

3. 用真实检索区分两种缺口

evaluate_stage 默认调用实际 visible_chunks 和 retrieve,固定 BM25、k=3、context_chars=2400。k 限制返回块数,去重后的文档 ID 可能少于三。字符预算是上下文字符数,不能当模型 token 或语义容量。

每题保留题号、gold 数、可见 gold 数、返回文档 ID、hit、recall、status。没有 query、正文或当前不可见 ID。hit 只表示至少命中一个 gold;recall 是命中文档数除以该题 gold 数。两 gold 命中一个时,hit=1、recall=0.5。

条件 唯一状态 下一步复核
执行异常 error 先查执行边界
有 gold,但未全部可见 knowledge_gap 查材料与权限
gold 全可见,零命中 retrieval_gap 查检索与措辞
有 gold 且命中,未落前述分支 matched 人工检查语义
无 gold,有或没有候选 no_gold_evidence / no_gold_empty 查未知问题处理

知识缺口仍保留实际 hit 和 recall。关键资料在库、被检索到、语义正确是三项不同证据。

检查点 3:两份 gold 仅一份可见且被命中,是什么结果?

knowledge_gap,hit=1、recall=0.5。核对要点:不要把命中等同完整覆盖。走神救援:只看 boot-09 的三个计数字段。

4. 每个指标都带回自己的分母

summary 的六类计数之和必须等于总 n。有 gold 的均值分母是 gold_n;error 仍算在里面,hit 与 recall 按零处理。无 gold 题的两项值为 null,不给它们人为加一个满分。

可见覆盖率按 gold 引用数统计。同一文档被三道题指定,就有三次引用;它不是文档去重率。两份 gold 的题会贡献两次引用。无 gold 返回率只数无 gold 题中是否返回候选,不数候选块的数量。

字段 实际分母
mean_hit / mean_recall gold_n
visible_gold_coverage gold_reference_n
no_gold_return_rate no_gold_n
status_counts n

分母为零输出 null。空输入、全有 gold、全无 gold 都得到可解释的 blocked,不能除零,也不能因“没有失败记录”便宣称通过。错误题不被删掉,否则程序越常出错,均值反而可能越漂亮。

检查点 4:12 道有 gold 中一题异常,均值分母是多少?

仍为 12;异常题贡献零。核对要点:写下题目分母与引用分母的区别。走神救援:只核对 n=gold_n+no_gold_n。

5. 用提前固定的门槛阻止误放行

人工启动预检同时要求:至少一道有 gold、至少一道无 gold、无 error、无 knowledge_gap、无 critical_misses、mean_hit≥0.8、无 gold 返回率≤0.5。所有条件满足才叫 pass_manual_review,否则 blocked 并列出固定 reason。

critical_misses 列出关键题未命中或异常的题号。普通题的高均值不能补偿关键题漏掉。反过来,命中一份关键文档也不能证明完整答案正确;本章的关键门槛按题目 hit 定义,不检查每一句话是否被证据支持。

门槛允许一部分非关键检索漏召回,所以通过后仍要读逐题结果。0.8 与 0.5 是这份教学夹具的预先约定,不是行业标准或生产服务目标。程序不改阈值、不扩 FAQ,不执行上线;人工预检只是下一步复核的入口。

检查点 5:均值达标但关键题零命中,能够通过吗?

不能,critical_misses 独立阻断。核对要点:逐条检查门槛,不算综合分。走神救援:先找 reasons 中是否有 critical_misses。

6. 运行两个独立阶段,保留原始材料

以下是原示例父项目目录内的 PowerShell 命令。指定的新目录必须尚不存在,即使已有空目录也拒覆盖;统计上的 blocked 仍返回退出码 0。预计输入、JSON 或 IO 问题给固定 JSON 与退出码 2,机械实验失败返回 1。

& '.\examples\knowledge-assistant\.venv\Scripts\python.exe' -X utf8 examples/knowledge-assistant/bootstrap_lab.py demo

在示例 knowledge-assistant 目录内,对应命令为:

python -X utf8 bootstrap_lab.py demo

默认产物在新的 .runtime/bootstrap-UTC-唯一编号 目录。两阶段各保存 rows 与 backlog,另有 summary.json。summary 包含相同题目的前后指标、导入记录、时间、Python 与平台、代码/题目/原语料哈希。临时库在阶段结束后清理;哈希前后相等证明本次只读输入没有改变,不证明对抗并发替换安全。

检查点 6:为什么两阶段不能复用同一个逐步扩充的数据库?

新临时库排除前阶段残留,让导入范围可核对。核对要点:打开新目录的 summary.json。走神救援:先核对 readonly_inputs_unchanged,再读指标。

7. 阅读本次固定实验的真实结果

两阶段均有 14 题:12 道有 gold、2 道无 gold、14 次 gold 引用。starter 可见四次引用,expanded 可见十四次。结果来自同一份题目字节、同一 core 的真实 BM25,没有模型调用。

指标 starter expanded
matched / knowledge_gap / retrieval_gap 3 / 9 / 0 11 / 0 / 1
mean_hit 4/12≈0.3333 11/12≈0.9167
mean_recall 3.5/12≈0.2917 11/12≈0.9167
可见 gold 覆盖 4/14≈0.2857 14/14=1
无 gold 返回率 1/2=0.5 1/2=0.5
critical_misses boot-02 空
readiness blocked pass_manual_review

boot-09 在 starter 只命中一份,仍是知识缺口;扩充后两份命中。boot-11 的英文提问从知识缺口变成检索缺口:资料可见了,但 BM25 仍没有返回它。boot-13 的未知型号仍收到其他型号候选,返回率完全没有提升。保留这些结果才能看清材料增长解决了什么、留下了什么。

检查点 7:expanded 覆盖率为 1,为什么 boot-11 仍失败?

覆盖检查资料可见,检索检查实际命中,二者不同。核对要点:读 boot-11 的前后状态。走神救援:只比较无 gold 返回率,发现其改善量为零。

8. 把缺口交给复核,不自动制造答案

backlog 只有 case_id 与 reason。它保留知识缺口、检索缺口、异常和无 gold 候选,不生成补充答案。复核者先核对证据版本和权限,再判断该补材料、改检索还是处理未知问题。新增材料需要新的实验版本,不能把这轮题目改成容易得分的题。

机械检查使用真实临时库验证知识缺口、关键题阻断、无 gold 计数、空分母、异常留分母、scope 拒绝、跨租户与 reader 隔离、已有目录拒覆盖。授权测试另行导入 hidden 正负对照,不能混入正式阶段。异常注入只测试统计口径;网络 guard 明确断言连接与 urlopen 没有被调用。

涉及后续动作时,先接上意图识别与安全路由,由独立规则决定权限与审批。公开夹具不是盲测,候选命中不是生成质量,哈希也不是签名。冻结此次结果后,按待办开展新实验;如果下一轮零提升或退化,也如实保留。

检查点 8:通过人工预检后,脚本会自动扩 FAQ 或上线吗?

不会。这里只产出可核对的离线结果与复核待办。核对要点:确认待办没有 query 或答案。走神救援:返回一句话,把“检索到”与“答对了”分别说清楚。

打卡记录保存在你的浏览器里,首页能看到总进度