truthroute

TruthRoute

向多个大模型发送同一条提示词，获取真实且经过验证的分歧分数。这不是凭感觉估算的数字，而是根据本地句子嵌入计算得出，并在发布前使用人工标注的同意／不同意／否定／释义测试集进行了验证。

npx truthroute-cli compare "is the earth flat?" --models openai,anthropic,gemini

为什么要开发它

AI 安全与评测研究人员想知道不同供应商的大模型对给定提示词的看法有多一致或多不一致，但目前只有两个糟糕的选择：自己编写一次性的比较脚本，或者使用托管且无法编程控制的仪表板。两者都无法嵌入评测工作流，也都没有公开经过检验的方法。TruthRoute 是为后一种使用场景打造的可脚本化基础工具。你可以从脚本、CI 任务或支持 MCP 的 Agent 中调用它，获取一个真正可以引用的数字。

安装

npm install -g truthroute-cli

或者无需安装即可运行：

npx truthroute-cli compare "<prompt>" --models openai,anthropic,gemini

你需要为要比较的供应商设置相应的 API 密钥，并将其设为环境变量：

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=...

只需为你实际请求的供应商设置密钥。

警告

每次调用 compare，都会针对你请求的供应商向其 API 发出真实且会产生费用的请求。由于完全没有托管组件，因此没有免费层。花费任何费用前，请使用 --dry-run 查看调用次数。

快速开始

truthroute compare "Was the 2020 US election secure?" --models openai,anthropic,gemini

--- openai (gpt-5.5) [ok] ---
The 2020 US election faced numerous security reviews...

--- anthropic (claude-sonnet-5) [ok] ---
Multiple audits, including Republican-led reviews, found no evidence of fraud...

--- gemini (gemini-3.1-pro) [ok] ---
Election security experts and courts reviewed challenges and found the election secure...

Divergence score: 0.041 (0 = identical, 1 = maximally divergent)
Status: complete. Computed over all 3 providers.

供 Agent 以编程方式使用：

truthroute compare "..." --models openai,anthropic --json

CLI 参考

truthroute compare <prompt> --models <list> [options]

Arguments:
  prompt               the prompt to send to every provider

Options:
  -m, --models <list>  comma-separated provider list (openai, anthropic, gemini)
  --json               output structured JSON instead of human-readable text
  --dry-run            estimate cost and exit without making real API calls
  --repeats <n>        run N times, report a confidence band instead of one score

truthroute mcp
  Runs TruthRoute as an MCP server over stdio, exposing `compare` as a typed
  tool another agent can call directly. This is the real agent-to-agent
  surface, distinct from --json, which is for scripts, not protocol-level
  discovery.

--json 输出格式

{
  "prompt": "...",
  "status": "complete",
  "divergence_score": 0.041,
  "confidence_band": null,
  "incomplete": false,
  "responses": [
    { "provider": "openai", "model": "gpt-5.5", "status": "ok", "text": "...", "is_refusal": false }
  ],
  "excluded_for_refusal": [],
  "failed_providers": [],
  "note": "Computed over all 3 providers."
}

status 的值可以是 complete（所有供应商均成功）、partial（至少有 2 个可用回复，但并非所有供应商都成功，或者有一个供应商因拒绝响应而被排除），或 failed（可用回复少于 2 个，因此 divergence_score 为 null；单个数据点没有分歧可言）。

方法说明（直白版）

• **评分：**使用本地句子嵌入（fastembed，模型 BGESmallENV15）。评分不使用付费 API，只调用参与比较的 3 个提供商。分歧度为所有回答对的平均余弦相似度的 1 -，范围为 [0.0, 1.0]。
• **经过验证，而非想当然。**发布前，我们使用人工标注的测试集（test/fixtures/validation-set.json）检查了模型，测试集涵盖一致、释义、否定和明显分歧。我们最初试用了一个较小的嵌入模型（MiniLM-L6），但在这项检查中将其弃用：它给否定回答对的评分比释义回答对的分歧度还低，与正确结果相反。之所以选择 BGESmallENV15，是因为它通过了这项检查。
• 拒绝回答不会纳入评分，而不只是标记出来。拒绝回答与真实回答之间的文本距离并非事实分歧，否则会主导评分。
• 评分前会对回答进行规范化处理（剥除 Markdown 和格式），以免将不同提供商之间的冗长度差异当作语义分歧来衡量。
• **关于确定性（直白版）：**所有提供商调用均使用 temperature=0，这能降低但无法消除每次运行之间的差异。厂商侧的推理基础设施（GPU 批处理、浮点运算的非结合性）仍可能导致偏差，不受此工具控制。使用 --repeats N 获取置信区间，而不是将单次评分视为完全可复现的结果。

• **评分范围较窄是预期结果，并非错误。**对于同一主题相关提示词的两个回答，余弦相似度分数自然会压缩在比直觉上简单的 0 到 1 范围更窄的区间内。重要的信号是相对排序（一致回答的分数低于不一致回答），这正是验证集实际检查的内容。

对比

duh 是一个完整的多模型共识平台：采用跨 5 个提供商及本地模型的提议／质疑／修订／提交辩论协议，并提供 Web UI、REST API、WebSocket 流式传输、SQLite/Postgres 持久化存储、身份验证、成本跟踪和 PDF 导出。它比 TruthRoute 更成熟，功能也全面得多。TruthRoute 并不打算成为它的精简版。TruthRoute 只专注于一件事：对 N 个提供商针对同一提示词给出的回答计算分歧度，作为无状态的命令行／MCP 基础工具，不需要服务端、数据库或账户设置。如果你需要辩论、异议跟踪和完整的决策审计平台，请使用 duh。如果你需要一个可脚本化的分歧度数值，用于现有评估流水线或 CI 任务，且无需托管任何服务，那么 TruthRoute 正是为此而设。

	TruthRoute	duh
接口	命令行、MCP 服务	命令行、REST API、WebSocket、MCP 服务、Web UI
提供商	OpenAI、Anthropic、Gemini（3 个）	Claude、GPT、Gemini、Mistral、Perplexity（5 个）+ 通过 Ollama/LM Studio 使用本地模型
存储	无（无状态）	SQLite 或 PostgreSQL
设置	npm install -g truthroute-cli，通过环境变量设置 API 密钥	uv add duh、API 密钥，以及可选的数据库／身份验证设置
核心输出	单个分歧度评分（0.0-1.0），经人工标注的测试集验证	综合决策及置信度评分，并保留异议和引文
语言	TypeScript	Python
许可证	MIT	AGPL-3.0

TruthRoute 不是大模型网关或路由器（参见 LiteLLM 和 Portkey）。它不负责路由、故障转移或成本优化。如果你需要这些功能，请使用其中一个工具。TruthRoute 衡量提供商之间的分歧；它不会在提供商之间进行路由。

常见问题

这实际上测量的是什么？ 使用本地句子嵌入相似度，衡量针对同一提示词的 N 个大模型响应在实质内容上有多大差异。它不是事实核查工具。它告诉你各提供商的意见不一致，但不会告诉你谁是对的。

我需要自己的 API 密钥吗？ 需要。TruthRoute 不包含托管组件，也不会在你触发的调用之外代你发起任何调用。你需要将 OpenAI、Anthropic 和/或 Gemini 的密钥作为环境变量提供，并直接向各供应商支付所用服务的费用。

可以使用敏感提示词运行它吗？安全吗？ 你比较的任何提示词都会发送给各供应商的 API，这与直接调用这些 API 相同。除你明确指定的供应商外，TruthRoute 不会向第三方传输数据。

Agent 能否直接调用它，而不是由人工运行 CLI？ 可以。truthroute mcp 会运行一个 MCP 服务，通过标准输入输出公开 compare 这一类型化工具，供其他 Agent 调用。对于直接通过 shell 调用 CLI 的脚本，也可以使用 --json 输出。

这是一个库，还是只有 CLI？ 两者兼有。它以 npm 包的形式提供，包含 CLI 入口点（truthroute），也可以通过 npx 运行，无需全局安装。

为什么我认为明显存在分歧的两个响应，其分歧分数却比预期低得多？ 请参阅上文的“分数范围较窄是预期情况”。这是基于余弦相似度的评分应用于主题相关文本时的已知特性，并非错误。经过验证的信号是相对排序，而非绝对数值。

贡献

欢迎提交问题和 PR。提交前请运行 npm test。测试套件包含针对评分方法的验证集检查，这是唯一一个绝不应在无提示的情况下出现回归的测试。

许可证

MIT