智能体工程 · 16g
回滚清单写好了,文件和指标也对得上吗?
读完能做的判断:核对真实字节和逐题分母,用预检证据决定是否具备回滚条件。
16g|模型版本清单与回滚预检:换版本之前,先核对什么?
⏱ 阅读约 29 分钟 · 动手实践另计
本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。
一句话:把代码、配置、题集与结果绑到同一组文件,再用同题记录决定是否进入人工复核。
你在 16:企业落地与生产化 看过服务上线需要哪些环节。本章收窄到上线之前的一步:准备两份离线版本包,核对它们的内容和评测记录,分别提出升级与回滚的人工复核建议。
练习使用原创星灯设备助手题集,真实调用已有 lab.seed 与 core.retrieve。检索方式是词项基线,模型声明固定为 teaching-fixture-no-model。没有模型权重、真实大模型回答、服务流量、别名切换或部署动作,也不会启动 MLflow、DVC。
在检查点 3 中,指出结果绑定的三个文件,再用它们核对预检流程。
走神救援:找到 case_count、gold_count、error_count 三个字段,再找 no_switch_performed。先解释这些字段,暂时不用看每个哈希字符串。
1. 一份清单需要回答哪些问题
本章的版本包由可信调用方指定目录,程序只读取固定文件名,不接收清单里的路径。每份文件非空,最多一 MiB;提示正文最多两千字符。目录与文件遇到符号链接、Windows reparse 属性、非普通文件或多个硬链接时拒绝。
| 组件 | 示例固定名称 | 保存与核对内容 |
|---|---|---|
| 提示 | prompt.txt |
原创提示原字节;仅作版本资料,不执行模型调用 |
| 检索 | retrieval.json |
lexical、固定 k=3、严格整数的字符预算 |
| 题集 | cases.json |
唯一题号、问题、参考文档编号、公开夹具身份 |
| 逐题结果 | results.json |
状态、返回文档编号、hit/recall,以及前三项和核心代码哈希 |
| 清单 | manifest.json |
schema 1、显式版本号、四组件大小与 SHA256、环境和代码哈希 |
注意结果先绑定前三个文件,再由清单绑定结果文件,这样没有循环哈希。清单没有从结果里复制一个平均分当作结论;验证时从每一条记录重新算统计。
版本号限定为一至八十个安全 ASCII 字符。环境记录 Python 与 SQLite 版本;核心代码和本练习代码分别留下 SHA256。
检查点 1|把 A 改名为 A100,质量会变好吗?
不会。名称没有评分含义。先核对原字节,再看同题结果;weights_verified 始终为 false。
2. 先运行真实检索对照
以下是原示例父项目目录内的 PowerShell 命令。输出目录的父目录需要已存在,最后一级必须是新目录。重新运行时换一个名称,防止覆盖上一次记录。
cd examples/knowledge-assistant
& ./.venv/Scripts/python.exe -X utf8 -m unittest test_release_lab -v
& ./.venv/Scripts/python.exe -X utf8 release_lab.py demo --output validation/release-my-first
该示例使用 Python 3.10+。本练习只使用标准库,已有项目可选的模型与网页依赖不参与这里的检索。
Expand-Archive -LiteralPath ./knowledge-assistant.zip -DestinationPath ./release-learning
cd ./release-learning/knowledge-assistant
python -X utf8 -m unittest test_release_lab -v
python -X utf8 release_lab.py demo
没有指定 --output 时,脚本创建 .runtime/release-UTC时间 新目录。临时 SQLite 库与工作版本包使用 TemporaryDirectory,退出时清理;输出只保存 A/B 固定组件、清单与 demo-report.json,没有数据库。
真实 A 使用六百字符预算,B 使用两千四百字符预算。两者运行相同九题,八题有参考文档,一题无参考答案。预算包含证据开销,单位是字符,不是 token。
每题使用固定公开夹具 a/alice 或 a/bob。核心检索仍检查租户与读者权限,查询文字和结果不能授权私人资料访问。
检查点 2|预算扩大四倍,是否应当宣布质量提升?
先运行。此次 A/B 的 mean_hit 与 mean_recall 都是 0.875。证据组合可能改变,评分没有提升,应保留零提升结果。
3. 为什么必须核对原文件字节
SHA256 输入是文件原始字节。JSON 只加一个空格也会改变哈希,不能先重新序列化再声称拿到了原始字节证据。
build_manifest(bundle, release_id) 在生成清单之前检查输入 schema 与结果绑定。verify_manifest(bundle, release_id) 则检查已经存在的清单和当前全部四个文件。只检查清单自身格式正确,无法发现目录里的提示或结果已经改变。
结果里的 bindings 必须恰好包含 prompt.txt、retrieval.json、cases.json 三项哈希。core_sha256 必须等于当前 core.py。因此旧结果贴到新配置、改了问题又保留旧结果、拿别版核心代码的结果来比较,都会遇到固定拒绝码。
JSON 同时拒绝未知字段、重复键、布尔值冒充整数、错误哈希长度、非法 UTF-8、NUL、NaN 和不安全字符串。案例编号唯一,结果编号集合必须精确覆盖案例;缺一条、多一条、重复一条,都不能悄悄变成统计上的零错误。
例如 context_chars=true 不能因 Python 把布尔值视作整数而通过。新增字段应修改 schema 与评审规则。
检查点 3|同时改文件、改清单哈希,就能证明来源真实吗?
不能。能改完整包的人也能重算哈希。签名与来源认证在练习之外;来源可信也仍需检查模型质量。
4. 从逐题记录重新计算分母
results.json 每题只有题号、状态、返回文档编号和两个指标。报告不复制问题、提示全文、证据或数据库;包里仍保存题集与提示供检查。
有参考文档时,集合有交集则 hit 为一,否则为零;recall 是命中的不同参考文档数除以参考文档数。重复段落不重复得分。
error、timeout、unknown 都计入 error_count。有参考文档的失败题还留在 gold_count 分母中,hit 与 recall 为零。这样不能删掉失败记录让平均分变高,也不能把一个超时问题从“测了九题”变成“只测了八题”。
无参考文档的题不参与 hit/recall 均值,指标是 null。如果检索返回了证据,单列为 no_gold_return;这表示公开题集没有给参考文档却出现证据,不能直接宣布发生了语义误答。词项基线提供资料,本章没有生成回答。
真实 A/B 均为 case_count=9、gold_count=8、error_count=0、no_gold_return=1。未命中题与无参考文档返回证据的题全部保留。
检查点 4|七道成功、一道人为 error,分母该是多少?
八题都有参考文档时分母仍是八,error 贡献零。测试的七道有参考题中人为制造三个不同失败状态后,gold_count 仍是七,error_count 为三。
5. 把核对变成一张预检流程表
compare_releases(current, target, current_id, target_id) 重验两份包,列出模型声明、提示、检索、题集、结果、环境改变。A/B 改变项是 retrieval 与 results,结果绑定各自配置。
preflight_switch 使用同样的重新验证,再决定是否满足人工复核入口。提示与检索参数可以改变;题集字节与核心代码必须一致,才有同题比较的基础。核心代码漂移时直接拒绝,不能把两个不同基线产生的成绩混成同一次比较。
| 顺序 | 核对内容 | 未满足时 |
|---|---|---|
| 1 | 两份当前包的 schema、文件与结果绑定完整 | blocked,并给固定拒绝原因 |
| 2 | 同题集字节、同核心代码 | 不可比,停止质量比较 |
| 3 | 至少一道有参考文档的案例 | no_gold_cases |
| 4 | 目标 error_count 等于零 | target_errors |
| 5 | 目标 mean_hit 不低于当前值 | hit_regression |
| 6 | 目标 no_gold_return 不高于当前值 | no_gold_return_regression |
| 7 | 全部满足 | pass_manual_review,等待人工语义与发布复核 |
mean_recall 保留供人工查看;准入只对 mean_hit 设不降低条件。没有门槛的指标不能解释成“已经验收”。
检查点 5|A→B 能进入复核,B→A 就一定也能吗?
分别运行。回滚目标也可能缺文件或退化。本次指标相同,两个方向都是 pass_manual_review;未切换生产流量。
6. 将真实实验与人工故障分开读
打开 demo-report.json 的 actual,A/B 包含真实逐题记录、统计、清单环境与哈希。A_to_B、B_to_A 是真实包的建议;故障场景只操作临时副本。
再看 scenarios。缺文件、原字节漂移、未知清单键、错误类型、重复键、空文件和目录冒充普通文件属于机械完整性场景。人为把一题改成 error 或清空命中集合,明确标成 artificial_fault_fixture,用来证明失败分母与退化阻止规则。
手改分数不改返回编号会被 metrics_mismatch 拒绝。同步改编号、分数并重建清单,仍只是人工记录,不能成为真实质量证据。
本章测试还检查硬链接拒绝、非法根目录、路径形式版本号、题号集合缺失与重复、外部 aggregate 字段和 CLI 拒绝覆盖。Windows 符号链接创建可能需要额外权限;权限不足时只跳过这一项并留下原因,不能把跳过记录写成通过。
检查点 6|人工制造的 hit 退化为什么有用?
它验证退化阻止规则与失败分母。实际零提升记录与故障副本分开放置,不能把故障验证当成模型成绩。
7. 文件边界也是实验条件
可信调用方提供根目录。程序检查目录祖先,固定文件的类型、链接数、大小与描述符身份。清单不接受路径,也不递归遍历。
这是单机教学边界。目录所有者需要保证调用期间没有并发替换;本章没有跨进程锁或生产存储隔离。不得把它直接暴露为允许任意用户选择目录的服务器接口,也不得依靠这里的离线身份字符串授予真实系统权限。
旧输出目录返回 {"status":"rejected","error":"output_exists"}、exit 2;机械场景失败 exit 1。exit 0 不表示语义与权重验收。
检查点 7|看到完整哈希和环境,还缺少什么证据?
仍缺真实权重、模型回答、盲测、上线配置与真实回滚观察。环境字符串只是留档。继续 12c:备份恢复与状态核对,再安排独立部署验收。
8. 写下你能支持的结论
写下两种预算、同题变化、两个方向的建议,再补一句:没有运行模型或切换流量,hash 只识别字节漂移。
mean_hit 相同而文档改变时,挑一个题号核对编号。出现 error 时保留失败题;案例不同则先用同一题集重跑。
需要进一步比较多个切片与成对变化时,接着读 14c:评测切片与成对比较。本章把“能重复核对的版本资料”备齐,下一步才是更充分的公开评估、人工语义复核和真实运行验收。
检查点 8|本章最稳妥的验收句子是什么?
两份离线包均保留九题原始记录,并通过同题、当前文件、结果绑定和准入规则检查;两种预算的 hit/recall 均值没有提升。升级与回滚都只进入人工复核,weights_verified=false、semantic_verification=unassessed、no_switch_performed=true。