🏠 总目录📚 本教程 17f · 失败样本复核与改进队列 ← →

智能体工程 · 17f

用户反馈“不好用”,下一步该排哪一种问题?

读完能做的判断:把输入标签、固定优先级和双人复核分开,建立可追溯改进队列。

失败样本复核与改进队列:先让问题可核对

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

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

一句话:反馈只是线索,经过隐私、双人复核、证据和数据切分检查,才可以成为候选改进待办。

本章用标准库把公开合成标签变成离线队列,核对计数、分歧和分组。没有用户正文、情感模型、自动答案、FAQ 或训练集。

建议先读请求追踪与脱敏日志。追踪回答请求经历了哪些执行状态;本章回答人工把什么判为问题、两个人是否意见一致。一次请求执行成功,仍可能有内容问题;执行失败,也需要复核才知道改进方向。

本章以 feedback_lab.py 为教学示例。后文数字来自实际离线结果,不能证明模型变好或用户更满意。

1. 先把反馈和问题分开

signal 只有 negative、positive、unknown 三个值。它描述反馈标签,不参与自动确认。负面反馈可能误解了结果;正面反馈也可能伴随一个已复核的工具错误。脚本尊重人工标签,不用信号替代复核。

review_a 与 review_b 各有 unreviewed、confirmed、dismissed 三个值。confirmed 表示复核者确认这一条问题,dismissed 表示复核者撤销这一条问题,unreviewed 表示尚未完成。它们不是训练标签的自动通行证。

“人工”标签是手写合成数据,没有接入真实复核服务。

一个有限例子:alpha-03 是 negative,但 review_a 尚未完成,所以状态是 needs_review。alpha-13 是 positive,两人都 confirmed,证据 current,又属于 development,因此可成为候选。感受和问题标签之间没有自动等号。

检查点 1:负面反馈能直接进入改进队列吗?

不能。一个人未完成就停在 needs_review。人审确认、当前证据、明确类型和开发切分同时满足,才可能产生候选。

核对要点:只记住“signal 不替代 review”。走神救援:找到 alpha-03,不用读完所有数据,确认其中一个 review 是 unreviewed。

2. 让输入只能装标签

每条恰好十个字段:三个标识、切分、信号、类型、证据、两人人审、隐私;字段名以代码 schema 为准。没有自由正文或备注。

前三个字段是 1 到 80 个字符的 ASCII 标识,只允许英文字母、数字、下划线、连字符和点。标识在这个练习里只是合成编号,不能放真实姓名、邮箱或凭证。字符合法不意味着内容已经得到隐私授权。

其余必须是字符串枚举,合法取值见下表和夹具;非字符串或未知值均拒绝。

列表最多 1000 条。sample_id 在整个输入中全局唯一,同租户和不同租户的重复都拒绝;同一 tenant、conversation_id 下有多个不同 sample_id 则合法。布尔值、数字、空标识、超长标识、缺字段和额外字段都不能混过去。

token、reviewer_notes 或其他额外字段都返回固定 {"error":"invalid_records"},不回显字段或秘密值。跨租户无效记录也一样。

检查点 2:为什么不能默默丢掉未知字段?

严格拒绝促使调用者修正入口。枚举先检查字符串再查集合,列表或字典值也返回固定错误。

核对要点:数据合同先于分类。走神救援:只检查字段数量与 sample_id 是否重复,不要把这个练习变成用户正文清洗项目。

3. 沿固定优先级得到唯一状态

一条记录只有一个 disposition。沿表从上往下,命中就停止;下半表同时列出统计分母。

顺序或统计 条件与结果 核对口径
1 privacy=restricted → quarantined 不参与双人一致率
2 任一人 unreviewed → needs_review 负面信号也停在这里
3 两人的已完成标签不同 → disputed 保留分歧 ID,进入一致率分母
4 两人 dismissed → dismissed 不产生候选
5 两人 confirmed,public_test → evaluation_only 公开评估永不产生候选
6 两人 confirmed,证据不是 current 或类型 unknown → needs_evidence 等待补证据或明确类型
7 两人 confirmed,current、明确类型、development → improvement_candidate 还只是待办候选
原始记录 n 与 counts 本 tenant 原始条数,七类之和等于 n
会话与候选组 conversation_count 与 group_count 会话去重数;候选按会话及类型分组数
一致率 agree / n_reviewed 本 tenant、cleared、两人都完成复核的条数

公开评估的 confirmed 即使证据 missing,也归 evaluation_only;restricted 的公开评估先隔离。

反馈不能授予权限、改审批状态或执行工单。候选仍需负责人员评估、修复和验收。

检查点 3:受限记录同时有分歧,数在哪一类?

quarantined。它属于原始记录分母,但不进入双人一致率分母。

核对要点:七类 counts 相加必须等于 n。走神救援:沿表从第一行往下走,命中就停止,不要为一条记录贴多个 disposition。

4. 租户隔离与分组各解决一个问题

build_queue(records, tenant=...) 接收可信管理员提供的范围。实现先验证全部记录,再只处理指定租户。其他租户的有效记录不进入输出 ID、计数、会话数或一致率;其他租户的无效输入导致同一个固定错误。

全局无效记录会阻止运行,错误不指出租户或字段。过滤只是离线约定,不是认证;真实入口须确认管理员身份和范围。

候选分组键是 tenant、conversation_id、failure_kind。alpha-13 与 alpha-14 都是 c13 的 tool 问题,合成一个组,sample_ids 排序后是这两个编号。alpha-15 同属 c13,但属于 generation,因此保留另一个组。

alpha 有四条候选、三个候选组。全部输入是十六条、十四个会话。行数、组数都不能直接解释为独立受影响用户数。

排序固定为 tool=1、generation=2、retrieval=3、routing=4,数字小优先;同优先级按 conversation_id。这是教学排序,不是真实风险或概率。

检查点 4:同一个会话收到三条反馈,为什么可能只有两个组?

两条同类型合并,另一条不同类型保留。分组不消除分歧,也不证明反馈独立。

核对要点:分清行、会话、组。走神救援:只看 alpha 的 c13:三行、一会话、两类型、两组。

5. 双人一致率回答一个很窄的问题

一致率只纳入本 tenant、cleared、两人都已完成的记录。agree 是相同标签的条数,两人都 dismissed 也算一致;分歧 ID 保留。

本次 alpha 的分母是十二条,两条分歧,所以 agree=10,比例为 10/12,即约 83.33%。beta 的手写分布相同,结果也是 10/12。两个 restricted 与两个未完成复核各自被排除,不能偷偷留在分母中。

这不是 Cohen kappa 或标注正确率。两个人也可能一起判断错,程序没有真实答案或第三人裁决。

没有可纳入复核的记录时,agreement_rate=null、agree=0、n=0。零分母不是 0% 一致。

需要模型评测时,另读数据集泄漏检查与冻结验收和评测切片与成对比较。反馈复核的一致率不能替代模型指标,公开合成数据也不能冒充盲测。

检查点 5:10/12 是否意味着十二条里面有十条正确?

不是。十二条中十条的两个人审标签一致,正确性需要额外依据。

核对要点:空分母写 null。走神救援:回到 review_summary,只读 agree、n、agreement_rate 三个值。

6. 运行一次真实离线演示

原示例父项目目录内的主解释器命令如下,不需要安装新包:

& examples/knowledge-assistant/.venv/Scripts/python.exe -X utf8 examples/knowledge-assistant/feedback_lab.py demo

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

python -X utf8 feedback_lab.py demo

默认输出到 .runtime/feedback-UTC时间-随机编号。可加 --output NEW_DIRECTORY;已有空目录也拒绝。

输出 summary.json、scenarios.json、manifest.json。汇总含每类 ID、候选组和分母;清单含实际 Python、模块与测试哈希、夹具前后哈希。终端不打印绝对路径。

本次实际运行:两个租户各十六条,七类数量依次为 2、2、2、2、2、2、4;各十四个会话、三个候选组。一共十个机械边界场景通过,限定测试二十三项通过。夹具运行前后 SHA-256 相同,这说明输入字节未漂移,不说明数据来源可信或标签质量良好。

检查点 6:怎样确认运行读取了文件,而不是展示写死的结果?

demo 实际读取夹具,调用 build_queue,并读前后哈希。手写预期只在测试中,生产逻辑不内置“两租户各十六条”。

核对要点:先看 summary 的 n,再看 manifest 的前后哈希。走神救援:第一次省略 --output,用自动新目录,避免目录已存在影响练习。

7. 用边界场景检验停止条件

十个场景检查重复 ID、未知字段、秘密不回显、空集合、租户隔离、分歧、撤证、同会话反馈、公开评估排除与负面不自动确认。变更只在内存,无正文或数据库。

“撤除证据”场景先用 current 得到一个候选组,再把副本改为 missing,结果变成 needs_evidence,候选组归零。这证明状态随当前标签重新计算,旧候选不能在证据撤除后继续被输出。

scenarios 的 passed 是机械断言是否成立。原始夹具里存在 disputed 或 negative 是正常数据,不代表运行失败。只有程序的边界检查不符合约定才返回 exit 1;无效输入、参数、I/O 或目录冲突返回固定 JSON 错误与 exit 2。

固定错误包括 invalid_records、output_exists、invalid_arguments、io_error,不打印异常路径或正文。测试受控注入机械结果失败,验证 scenario_failed 对应 exit 1;这不是分类效果评测。

检查点 7:看见 disputed,应当把 demo 判为失败吗?

不应当。exit code 与 passed 判断机械运行;disputed_ids 用于安排裁决。

核对要点:不要为消灭分歧而改人审标签。走神救援:找到 review_disagreement 场景,它预期一条 disputed 且没有候选组。

8. 把候选交给下一次人工改进

候选只有编号、分类、固定状态与教学优先级,没有新答案或 trainable 字段。负责人员仍须核对授权证据。

公开评估不回填开发答案。调整切分须记录、冻结与验收,反馈不能绕过泄漏检查。

针对 tool 组,应先提出可复现条件,再检查修复行为。离线队列只定位讨论对象,没有证明修复。

本章参考对话日志的分析与挖掘方法的复核方向,数据与代码为原创;未采用满意度或成本数字。

检查点 8:这个队列完成了什么,还缺什么?

它完成标签验证、状态分类、范围过滤、分组、分母与导出。真实隐私审查、认证、裁决和线上效果仍需另行完成。

核对要点:候选仍须验证改进效果。任选一个 candidate,记录它的 sample_ids 和 failure_kind,保留为改进待办。

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