Claude 版本号一换，同一份文档的字段从 41 个掉到 35 个｜PRIVO AI智能操作助手 三合一·网页+桌面+IDE

同一份采购合同，周一跑出 41 个字段，周三再跑只剩 35 个，中间代码一行没改。查到最后一身冷汗：不是模型抖了，是我在请求体里传的 Claude 版本别名被服务端指到了新版本上。别名的指向会变，版本号不会。这件事在单次 demo 里根本看不出来，在批处理里会直接变成脏数据。

先把链路交代清楚。PDF 转文本 → 按章节切 6 段 → 每段抽 6 类字段（甲乙方、含税金额、税率、付款节点、违约条款、签署日期），36 个槽位；再加 5 个派生字段（合同总额、账期天数、是否框架协议、币种、风险标记），合起来 41 个。所有请求的 model 参数都写成带 latest 的别名，当时的理由很充分：总是用最新的。

别名是一个指针，不是一个版本

服务端完全可以在不改你任何代码的前提下换掉指针背后的实现。它对外仍是同一个名字，对内是另一套模型、另一套后处理、另一套对齐策略。表现出来的差异通常落在这四类上：

1. 字段名变体，total_amount 变成 totalAmount；
2. 结构被拆开，原来一行的明细变成三行；
3. 空值表示变质，null 变成空字符串 ""；
4. 枚举大小写漂移，CNY 变成 Cny。

这四条都不是"模型变差了"，是契约变了。契约变了不报错，只会让下游断言全红；更糟的情况是没红——空字符串被当成合法值，悄悄写进了库。

5 轮 × 48 份的实测

测试集 48 份文档：合同 12、发票 12、报价单 12、工单 12，每份 41 个字段位，合计 1968 个字段位。两种传参各跑 5 轮，间隔 6 小时，跨过服务端可能的灰度窗口。

读这张表只需要看两个方向。固定版本这边，5 轮结果逐字节可比，回归才有意义；别名这边，第 5 轮直接少了 157 个字段位，而你的代码里没有任何一行知道这件事发生了。

代价是明确的：单份慢 0.3 秒、多 100 token，约 7% 的耗时增长换 13.5 个百分点的通过率。批处理场景里这笔账很好算。

选哪个版本：三个候选的同台对照

pin 住之后第二个问题：pin 到哪一版。同一天、同一测试集、同一 prompt，三个候选各跑一遍：

结论很直接：版本之间的差距（94.1 − 86.2 = 7.9 个百分点）远大于同一版本 5 轮内的波动（±0.6 个百分点）。所以"选一个版本跑稳"的收益，比"一直追最新"大得多。分工也很清楚：常规字段用快版，违约条款、金额歧义这类必须准确的段落单独路由到推理版。

把版本号关进一个文件

工程上的解法不是"记得改"，是让版本号只有一个出口：

# model_registry.py —— 版本号只允许出现在这个文件里
REGISTRY = {
    "extract_fast": "model-fast-2026-08",      # 快版，常规字段
    "extract_deep": "model-reason-2026-09",    # 推理版，争议条款
}

def extract(task: str, text: str) -> dict:
    model_id = REGISTRY[task]                  # 业务层只传 key，不传版本
    resp = client.messages.create(model=model_id, max_tokens=8192, input=text)
    data = resp.json()
    return validate(data)                      # 名/类型/枚举三重校验，不过即抛

配套三条纪律，都是被上面那 17 处漂移打出来的：

• 请求体里禁止出现 latest 之类的别名，CI 用正则扫全仓，命中就挂；
• 版本升级必须走 PR，PR 描述里必须贴回归报告，跑绿才准合；
• validate() 失败不重试。重试只会把契约问题变成偶发问题，正确做法是把原始响应原样落盘再修。

回归集跑成定时任务

回归这件事的价值全在频率上。手工点一次，一周做不了两回；做成定时任务，每次改 prompt、改 schema、升级版本都自动跑：

python -m eval.run --suite extract_v3 \
  --model extract_fast,extract_deep \
  --repeat 5 --diff-schema --out reports/

48 份 × 5 轮，单轮 3 分 40 秒，全量 18 分钟。挂在早上 07:00 的定时任务里，到工位先看 diff 报告，字段名、类型、枚举三列各自标红，哪一处漂了一目了然。版本升级 PR 的验证成本从"半天手工点"压缩到"一次 18 分钟的自动跑"，升级这件事才从祈祷变成流程。

多版本并存，才是这套流程的前提

真正卡人的从来不是写注册表，是能不能同时挂住多个版本。多数客户端的模型列表是"一个家族一个入口"，服务端换了你只能被动接受；要 A/B，就得自己维护两套 key、两套限流、两套计费。

换成 PRIVO 之后这块省掉了：同一家族的多个版本在模型列表里并列可选，快版和推理版能同屏做对照实验，回归报告直接跑在桌面端的定时任务上，第二天早上和看板一起出来。PPT 生成、AI 绘图、视频、文本润色、AI 音乐、翻译、写文案、写代码、写论文、数据分析、思维导图等 API 直连，集成国内外知名企业模型 30+，AI 工具 100+，全场景供应 AI 需求——对一个要长期维护抽取链路的人来说，值钱的是"旧版本还在、能随时切回去"这一条，而不是新版本本身。

适合什么场景：文档抽取、票据识别、批量结构化这类结果要进库、要能复现的活。写周报、聊需求这种一次性任务，追最新完全没问题。

模型会一直更新，能复现的那一版才叫基线。把版本号写死、把回归集做成定时任务，是这条链路上性价比最高的两件事——剩下的交给对比实验。