如何给 ModelTrace 添加自定义指纹库?3 步完成模型归因扩展
如何给 ModelTrace 添加自定义指纹库?3 步完成模型归因扩展
ModelTrace 是一个本地运行的主动模型归因工具:它通过三条独立的长整数生成挑战提取输出指纹,在统一候选库中自动判断模型家族和具体版本。当你要测试的模型不在现有指纹库中时,只需新建一个自定义指纹库并完成指纹采集——3 步即可把模型归因范围扩展到任意可通过 API 访问的模型 🎯
为什么要扩展指纹库?
现有指纹库覆盖 2 个模型家族、13 个模型,分别存放在 data/gpt_bank.json 与 data/claude_bank.json。
归因本质是"闭集"判断:只对指纹库内的候选模型打分。未收录模型会被归到最相似的现有候选上,结果没有任何参考价值。因此,想测新模型,第一步永远是先为它建库采指纹。
快速启动:部署本地模型归因页面
python -m pip install -r requirements.txt
python start.py
页面地址为 http://127.0.0.1:7860/。入口是 start.py,Web 接口由 app.py 提供,所有指纹库数据都放在 data/ 目录下。
第 1 步:一键创建自定义指纹库
进入页面顶部的「指纹库管理」工作区,点击「新建指纹库」:
- 输入指纹库名称,例如
Llama; - 点击创建,系统自动把名称转成小写 id(非字母数字转为
-),并生成两个数据文件:data/{bank_id}_reference.jsonl—— 原始参考数据,保存每条挑战的 prompt 与完整回答;data/{bank_id}_bank.json—— 拟合后的统计指纹库(采集完成后自动生成)。
- 库的注册信息会持久化到
data/custom_banks.json,重启服务后依然可用。
对应接口是 app.py 中的 POST /api/banks,同名指纹库会被拒绝创建。
第 2 步:API 自动采集模型指纹
在「指纹库管理」页面选择刚建好的库,填写采集表单:
| 字段 | 说明 |
|---|---|
| Base URL | API 端点,如 https://example.com/v1 |
| API Key | 只用于当前页面发起请求,不写入磁盘 🔐 |
| 指纹名称 | 模型标识(model_label),即库中该模型的显示名 |
| 采集回答数 | 3 ~ 36,默认 36 |
点击提交后,系统会自动完成 enrollment.py 中定义的全部流程:
- 从 challenge_suite.py 的 36 题挑战套件中均匀抽样——覆盖中英文模板、JSON/纯文本风格、不同系统提示词长度等多种"环境";
- 自动探测 API 格式(OpenAI Chat Completions 与 Anthropic Messages),2 线程并发采集,失败自动重试;
- 只有解析出
max(80, 预期数量 × 0.55)个以上有效整数的回答才会通过校验,写入参考文件; - 随后 bank_builder.py 自动重新拟合指纹,并把所有库合并,重建统一的 data/unified_bank.json。
💡 如果全部回答都无效,指纹库不会被修改(
没有获得可用回答,指纹库未修改),可以放心重试。
第 3 步:验证新指纹库的归因效果
切回「模型测试」工作区,选择 API 自动测试:
- 填入待测模型的 Base URL、API Key 与模型名;
- 程序自动生成 3 条独立挑战发送给模型,收集满 3 份有效回答即停止;
- 结果表格会列出统一库内所有候选模型(包括你刚加入的)的归因概率与分布相似度。
没有 API 也可以用手动测试:复制三条挑战提示词发给待测模型,再把完整输出粘贴回页面,本地即可完成归因计算。
一分钟看懂归因算法
所有模型共享同一套全局特征空间与权重,来自 fingerprint.py:
0.75 × 去除环境方向后的 Hellinger 模型中心相似度
+ 0.25 × 有序块数字序列特征
建库时由 bank_builder.py 用共享环境的平均偏移估计并投影掉干扰方向,再通过交叉验证拟合校准温度 β;三份回答分别评分取平均,经全局 softmax 得到模型概率,家族概率为该家族下各模型概率之和。
实用技巧与常见坑
- 样本越多越稳:3 份是最低门槛,18~36 份能覆盖更多环境,指纹中心更可靠;
- 警惕系统提示词偏差:系统提示词会严重影响模型偏好,README 明确建议不要在 Claude Code 环境中测试;
- 结果仅供参考:归因工具只对库内模型判断,待测模型不在库中时"得到任何结果都有可能";
- 手动模式也可入库:
POST /api/analyze走归因,采集入库以 API 自动采集为主,手动粘贴的输出按===OUTPUT===分隔提交同样支持。
指纹库扩展常见问题 FAQ
Q:新建指纹库后能直接测试吗?
不能。空库不参与统一库(app.py 的 active_banks 会跳过无模型的库),必须先完成第 2 步采集。
Q:校准样本不够会怎样?
bank_builder.py 会回退到已有校准值(fallback),概率的可靠性下降,建议每个新家族至少采集 18 份。
Q:接口报 429 / 5xx 怎么办? 408、429、500、502、503、504 会自动重试最多 3 次,退避逻辑见 enrollment.py;被 WAF 拦截会给出明确的排错提示。
Q:文件都在哪里?
原始数据 data/{bank_id}_reference.jsonl、拟合指纹 data/{bank_id}_bank.json、统一库 data/unified_bank.json、重建脚本 rebuild_unified_bank.py,页面模板见 templates/index.html。
按照「新建库 → 自动采集 → 自动测试」这 3 步,你就不受限于内置的 13 个模型,把 ModelTrace 的模型归因能力扩展到任意 API 模型了 ✅