主题: 附录 D. 阈值校准
难度等级: 中等
预计学习时间: 3-4 小时
前置要求: 熟悉 SDD(Software-Defined Diagnostics/Delivery)的基本概念
理解 MTTR、SLA、CI/CD 和事件管理指标
具备 Linux 命令行(bash)和 Python 使用经验
对变异测试和 LLM 工作原理(令牌、规范)有基本了解
学习目标: 理解并应用阈值配对校准原则,避免在仅调整单个指标时出现“回路拆解”问题。
根据 P0 漏检代价和路由图复杂度,调整变异测试阈值(第 5 章)。
考虑误升级代价和早期信号的权重,配置影子规范拍卖的权重和阈值(第 6 章)。
针对不同的负载配置和事件流,优化分层令牌预算(第 9 章)。
在配置 guard 指标时识别并防止古德哈特定律(第 10 章)的表现。
概述: 本学习指南聚焦于附录 D——AgentClinic-production 流程中的阈值校准。阈值校准不仅仅是修改配置文件中的数字,而是在风险、错误成本和可用资源之间进行精细平衡。材料中汇集了级别表(低/默认/高)、阈值偏移的实践练习以及重新评估的指示器。重点强调的是,阈值只有在配对时才有意义:更改一个参数必须伴随重新计算相关参数,否则系统将失去稳定性。
关键概念: 配对校准:阈值不能孤立修改的原则。仅偏移一个值而不重新计算相关值会破坏系统的保护机制(例如,strict_reject_rate 上升而 depth_of_diagnostics 下降——这是古德哈特的症状)。
变异测试(d.1):基于人工故障评估诊断流程质量。取决于 P0 漏检代价(关键事件被漏检的概率)和路由图复杂度。
影子规范筛选(d.2):拍卖过程,其中权重(mttr_gain、early_signal、false_escalation)决定哪些规范将变为活动状态。需要在响应速度和误报数量之间进行平衡。
分层预算(d.3):在本地(local)和外部(frontier)层级之间分配计算资源(以令牌计)。比例的变化直接影响各阶段的 SLA。
古德哈特防护(d.4):防止指标被操纵的机制,即为了数字而优化反而使实际结果恶化。通过不变量进行控制:silent_p0、manual_review_rate、audit_trace_coverage。
生产就绪度(d.5):评估制品发布准备情况(默认 23/25)。包括硬性阻塞不变量,如 audit_trace_coverage = 1.0,无法通过总分绕过。
练习题: 名称: 诊断深度校准(D.1)
问题: 您需要检查诊断深度阈值(depth_of_diagnostics_min)收紧对现有验证器的影响。要求比较默认运行与提高要求(阈值从 3 改为 5)下的运行。
解决方案: 1. 进入目录 cd book2/examples/stress-mutator。
- 创建文件夹 out 并将预期错误文件复制到其中:cp expected/expected_failures.json out/expected_failures_depth5.json。
- 替换文件中的阈值:sed -i 's/"depth_of_diagnostics_min": 3/"depth_of_diagnostics_min": 5/' out/expected_failures_depth5.json。
- 使用默认值运行计算(将成功通过,因为平均深度 4 > 3)。
- 使用新预期运行计算(将失败,因为 4 < 5)。差异将显示阈值收紧的代价。
难度: intermediate
名称: 保守配置下的影子规范拍卖(D.2)
问题: 团队决定误升级的代价过高。需要使用新的权重配置运行拍卖,其中误升级的惩罚增加到 0.8,早期信号的权重降低到 0.2。
解决方案: 1. 进入 cd book2/examples/shadow-auction。
- 使用新权重运行评分脚本:python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights "0.3,0.4,0.2,0.8" --out out/scorebook.json。
- 使用 2000 令牌预算运行决策:python3 scripts/decide.py --scorebook out/scorebook.json --budget-tokens 2000 --keep-threshold 0.70 --reject-threshold 0.40 --out-auction out/auction.json。
- 分析结果:shadow.p0.voice_handoff 应转为 disputed,因为公式现在更严格地评估风险。
难度: advanced
名称: 故障时分层预算测试(D.3)
问题: 需要模拟 5M 令牌(4.5M local / 0.5M frontier)的削减预算情况,并检查系统在 45 分钟本地层级故障期间的表现,以确保 token_health_min 不低于 0.5。
解决方案: 1. 进入 cd book2/examples/budget-keeper。
- 编译计划:python3 scripts/compile.py --budget-spec specs/budget_network_5m.yaml --out out/budget_plan_5m.json。
- 运行故障模拟:python3 scripts/simulate.py --plan out/budget_plan_5m.json --scenario scenarios/fail_local_45m.json --out out/fail_result_5m.json。
- 检查不变量:python3 scripts/inspect.py --result out/fail_result_5m.json --query "failover_to_frontier==2 && degraded_queue==18 && token_health_min>=0.5"。
- 验证在未更新阶段配额的情况下更改预算会导致错误(compile.py 失败)。
难度: intermediate
名称: 绕过古德哈特指标保护(D.4)
问题: 在实践中验证即使削弱两个独立保护(例如 manual_review_rate 和 silent_p0)如何允许“推过”本应被阻止的劣质发布。
解决方案: 1. 进入 cd book2/examples/goodhart-validator。
- 在规范本地副本中将 silent_p0 阈值从 0.05 放宽到 0.08。
- 运行验证(脚本应保持“红色”,因为 0.18 仍高于 0.08)。
- 创建“危险”配置,同时放宽两个阈值(例如,edge_drift 至 0.10,silent_p0 至 0.20)。
- 使用劣质指标(fixtures/new_metrics_bad.json)运行验证——系统将通过检查,这证明了单点校准的不可接受性。
难度: advanced
案例研究: 名称: 漏检关键事件(P0)的异常增长
场景: 在一个高风险的大型金融项目中,团队部署了自动化 SDD 流程。最初使用 AgentClinic 的默认阈值:silent_p0 ≤ 5% 且 manual_review_rate ≥ 15%。随着时间推移,开发人员开始抱怨由于人工检查导致 CI 流水线变慢。
挑战: 为加快流程,manual_review_rate 阈值被降低到 8%('低'级别),而 silent_p0 保持在 5%。这导致系统开始漏检历史数据库中未涵盖的新事件类(影子规范)。MTTR 指标在形式上有所下降,但灾难性 P0 漏检数量却增加了(古德哈特定律的症状)。
解决方案: SRE 工程师回归到配对校准原则。manual_review_rate 阈值恢复至 15%。同时,提示样本预算增加到 12 个槽位('高'级别),以补偿负载。所有变更均记录在 validation.md 中。
结果: 漏检 P0 数量恢复到可接受值(< 1-2%)。流程稳定下来,系统通过恢复自动化与人工控制之间的平衡,重新正确分类争议案例。
经验教训: 不考虑输入流量动态而降低人工检查比例会导致 P0 漏检增加。
MTTR 和 manual_review_rate 指标具有负相关性;只能成对修改。
流程加速不应以削弱 guard 指标为代价。
相关概念: 古德哈特指标保护(D.4)
阈值配对校准
P0 漏检代价
名称: 本地 LLM 层级故障时服务降级
场景: 每天处理 600 起事件的电商平台使用 10M 令牌预算,90% 分配给 local-coder,10% 分配给 frontier。这对应“默认”配置,但实际流量属于“高”级别类别。
挑战: 在季节性促销期间,本地 LLM 提供商开始定期崩溃(每周)。frontier 层级的 1M 令牌备用在几分钟内耗尽。触发的 failover 将系统切换到 degraded_queue 模式,导致关键服务恢复延迟数小时。
解决方案: 重新计算了分层预算(D.3 节)。总预算增加到 25M 令牌,比例调整为 80/20。为 local 层级添加了冗余提供商。更新了 budget_plan_phases 规范,以便 frontier 层级在主层故障时能容纳所有“争议”案例。
结果: 在本地集群的下一次故障中,系统顺利切换到 frontier。token_health_min 未低于 0.5,用户服务未中断。
经验教训: 令牌预算和 local/frontier 比例应与实际峰值事件流量匹配。
9M/1M 的划分与各阶段 SLA 紧密相关;更改比例需要更新规范。
对于每周故障的 local-coder,备用应至少占 15-20%。
相关概念: 分层预算(D.3)
CI 的 SLA 窗口
对 local-coder 故障的敏感性
学习建议: 不要在初次阅读时更改阈值:每章的学习最低要求基于默认阈值。仅当标准值不再适合您的流量时,才可开始校准。
寻找古德哈特症状:如果一个指标(例如 strict_reject_rate 或 MTTR)持续改善,而与之相关的指标(depth_of_diagnostics 或 manual_review_rate)下降——您不是在优化流程,而是在破坏保护系统。
记录每个更改:表中每一行的偏移都应伴随 validation.md 中的条目,并有明确理由(漏检代价变化、流量增长等)。
可视化依赖关系:使用 mermaid 图表(如 D.4 节所示)以理解节点(例如 audit_trace_coverage)的变化将如何影响整个指标图。
附加资源: 第 5、6、9、10、11 章(基础课程):理解附录 D 中配置阈值的流程的基本背景。
validation.md 文件:记录阈值偏移理由的模板。在将流程迁移到您自己的项目时必须使用。
book2/examples/ 仓库:包含用于执行练习的源脚本 immunity_score.py、score.py、compile.py 以及 JSON/YAML 配置文件。
摘要: 附录 D 是对 AgentClinic-production 阈值微调的深入探讨。核心要点:阈值从不在真空中存在。任何校准都是在风险之间取得平衡。您不能仅仅通过放宽人工审查阈值来加速流水线,同时不加强对 P0 漏检的防护。您不能在不考虑阶段 SLA 的情况下更改令牌预算。系统的成功运行需要持续监控指示器(例如争议审查的比例或误升级的代价)并及时进行配对配置修订。