ModelTrace 快速上手:5 分钟跑通本地模型归因工具的完整教程

原创2026-10-11 14:04:291,829 阅读

ModelTrace 快速上手:5 分钟跑通本地模型归因工具的完整教程

ModelTrace 是一个本地运行的模型归因工具:它通过三条独立的长整数生成挑战提取输出指纹,在统一候选库中自动判断模型家族和具体版本,帮你快速识别「这个 API 背后到底跑的是哪个模型」。本文带你在 5 分钟内完成安装、启动和第一次测试。

一、ModelTrace 能做什么?

功能 说明
🧪 手动测试 复制三条挑战问题,发给待测模型,粘贴完整输出即可获得归因概率
🤖 API 自动测试 填写 Base URL、API Key 和模型名,程序自动完成三轮问答并归因
📚 指纹库管理 可新建指纹库,或通过 API 为现有指纹库添加模型指纹
🔒 隐私友好 归因计算在本地完成,API Key 只用于当前页面请求,不写入磁盘

当前内置指纹库共收录 2 个模型家族、13 个模型(GPT 与 Claude 系列),统一库文件为 data/unified_bank.json。

二、环境准备与一键安装步骤

  1. 准备 Python 环境(建议使用 3.9+ 的虚拟环境)
  2. 获取项目源码:
git clone https://gitcode.com/gh_mirrors/mo/ModelTrace
cd ModelTrace
  1. 安装依赖,核心依赖仅 Flask、click、numpy 三项,秒装完成:
python -m pip install -r requirements.txt

三、启动 ModelTrace 服务

在项目根目录执行启动命令:

python start.py

start.py 会在 1 秒后自动打开浏览器,访问地址为 http://127.0.0.1:7860/。页面由 app.py 提供的 Web 接口渲染模板 templates/index.html 生成。

💡 不想装 Python?仓库还附带一个纯浏览器版本 static/index.html,无需后端,归因计算与指纹库读取全部在浏览器本地完成。

四、第一次测试:手动挑战模式

手动模式适合验证任意「黑盒」模型,全程只需三步:

  1. 复制三条挑战:页面默认展示三条长整数生成挑战,点击「重新生成」可换一组
  2. 发给待测模型:把三条挑战分别发送给同一个模型(可手动粘贴,也可走 API)
  3. 粘贴完整输出:将每次的完整回答粘回页面,点击「计算归因概率」

结果会给出模型家族概率与具体模型概率。评分逻辑(Hellinger 相似度 + 有序块数字序列特征,各占 0.75 / 0.25 权重)实现在 fingerprint.py 中。

五、API 自动测试:最快配置方法

如果你持有 OpenAI 兼容接口或 Claude 接口,直接使用 API 自动测试更高效:

  • Base URL:接口地址
  • API Key:密钥(仅当前页面使用,不落盘)
  • 模型名:接口中声明的模型名

程序会自动尝试 OpenAI Chat Completions 与 Anthropic Messages 两种格式,以「三份有效回答」为目标完成归因,调用逻辑见 enrollment.py。

六、扩展指纹库:添加自己的模型

想测试内置库之外的模型?可以在指纹库管理页:

  • 新建指纹库:输入名称即可创建独立的 *_bank.json 与 *_reference.jsonl
  • API 添加指纹:为现有库注册新模型,程序会自动采集样本、拟合统计指纹,并重建统一全局库(rebuild_unified_bank.py)

⚠️ 注意:指纹库只保存统计指纹和校准参数,参考数据 data/claude_reference.jsonl、data/gpt_reference.jsonl 会记录实际 prompt,请注意本地保管。

七、结果解读与常见疑问

Q:概率 100% 才可信吗? 结果属于候选库内的闭集概率——模型家族概率 = 该家族下各具体模型概率之和。概率越高说明输出指纹与库内模型越接近,但仅供参考,并非决定性证据。

Q:待测模型不在指纹库里怎么办? 未收录模型会被归到「最相似的现有候选」,任何结果都有可能,建议在结果旁标注置信度使用。

Q:为什么不建议在 Claude Code 中测试? 系统提示词会严重影响模型的输出偏好,导致指纹出现较大偏差,README 中明确建议不要在 Claude Code 环境中测试。

Q:给 Codex 任务加「防偷梁换柱」监测? 项目还附带 ModelTrace Guard 插件,可在 Codex 任务内按工具调用次数 fork 冻结快照做后台检测,发现模型不一致时自动提醒并拦截,适合对 Agent 任务安全敏感的场景。

写在最后

从 pip install 到拿到第一个归因结果,ModelTrace 全程不到 5 分钟:三条挑战、本地计算、隐私可控。无论你是想验证第三方 API 渠道的模型真实性,还是研究模型输出指纹,它都是一个轻量好用的起点。跑通之后,不妨再试试为指纹库添加一个新模型,体验完整的采集→拟合→归因闭环。

登录后查看全文
ModelTrace