🏠 总目录📚 本教程 16g · 模型版本清单与回滚预检 ← →

智能体工程 · 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。

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