如何给 ModelTrace 添加自定义指纹库?3 步完成模型归因扩展

原创2026-10-11 14:24:011,406 阅读

如何给 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 步:一键创建自定义指纹库

进入页面顶部的「指纹库管理」工作区,点击「新建指纹库」:

  1. 输入指纹库名称,例如 Llama;
  2. 点击创建,系统自动把名称转成小写 id(非字母数字转为 -),并生成两个数据文件:
    • data/{bank_id}_reference.jsonl —— 原始参考数据,保存每条挑战的 prompt 与完整回答;
    • data/{bank_id}_bank.json —— 拟合后的统计指纹库(采集完成后自动生成)。
  3. 库的注册信息会持久化到 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 自动测试:

  1. 填入待测模型的 Base URL、API Key 与模型名;
  2. 程序自动生成 3 条独立挑战发送给模型,收集满 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 模型了 ✅

登录后查看全文
ModelTrace