Verbatimeter 实战：给你的 AI Agent 装上引用真实性检测
AI Agent 越来越擅长写长回复、生成报告、引用来源。但一个问题始终悬而未决：它引用的内容真的在原文里出现过吗？
用过 RAG（检索增强生成）的朋友都遇到过模型凭空捏造引用、把上下文改写得分不清哪些是原文哪些是模型自由发挥的情况。传统方案靠一个”法官模型”（judge model）做二次评估——成本高、有偏见、不可复现。
Verbatimeter 走了另一条路：确定性字符串匹配。没有 LLM 调用、没有网络请求、不依赖任何评判模型——纯算法，每秒几十毫秒，告诉你答案中有多少字来自原文。
一句话使用
pip install verbatimeter
然后直接跑：
verbatimeter \ --source "We propose a new simple network architecture, the Transformer, based solely on attention mechanisms" \ --answer "We propose a new simple network architecture, the Transformer, based solely on attention mechanisms"
输出 matched=100% differing_tokens=0。把 solely 改成 partly，唯一不同的那个词会被标红。
三种用法，覆盖全部场景
1. CLI：一键验证
verbatimeter --source-file context.txt --answer-file answer.txt verbatimeter --source-file context.txt --answer-file - < answer.txt verbatimeter --source-file context.txt --answer-file answer.txt --quotes verbatimeter --source-file context.txt --answer-file answer.txt --quotes --fail && publish
--quotes 是 Verbatimeter 最有特色的模式。它会只检查答案中用 "..."、"..."、« ... » 或 „..." 包裹的引用段——如果任何引号内的内容与原文不匹配，模型就是在编造引用。
配合 --fail 后，可以把它放在 CI 流水线里做硬门控：
until verbatimeter --source-file ctx.txt --answer-file ans.txt --quotes --fail; do regenerate_answer > ans.txt done
直到引用通过验证，才让答案进入下一环节。
2. Python 库：与 RAG 代码集成
from verbatimeter import check, check_answer, render_result r = check(candidate_text, source_text, ngram=3) print(r.matched_ratio) # 0.79 — 79% 的词来自原文 print(r.longest_fragment) # 最长连续匹配词数 print(r.total_differing_tokens) # 不同 token 数 result = check_answer(answer, source, scope="quotes") print(render_result(result))
返回的 Result 对象包含逐词匹配标记、连续片段、匹配率、不同 token 数、ROUGE-L 分数等完整细粒度指标。
3. 装饰器：一行集成进 Agent
最优雅的用法——用 @verify 装饰器一键包装你的生成函数：
from verbatimeter import verify
@verify(source_arg="context", scope="quotes")
def generate(question, context=None):
return call_your_llm(question, context)
generate("What architecture does the paper propose?",
context=retrieved_passages)
装饰器会自动处理流式输出——如果 generate() 是流式生成器，Verbatimeter 会在每个 chunk 到达时实时着色输出（绿色 = 原文匹配，红色 = 模型发挥），并且把完整的检测结果附加为 .result 属性：
answer = generate(question, context=ctx)
if answer.result.total_differing_tokens > 5:
answer = regenerate_with_warning(question, ctx)
不需要改任何已有代码的接口——装饰器返回的仍然是 str，只是多挂了一个 .result。
两种检测模式
Verbatimeter 用同一套词级对齐算法，提供两种检测视角：
| 模式 | 匹配规则 | 验证什么 |
|---|---|---|
| 逐词匹配（默认） | 连续 ≥3 个词完全一致 | 模型有多少字是照抄原文的 |
子序列匹配（--subsequence） | 按顺序出现即可，可间隔新词 | 模型是否用自己的话重述了原文 |
逐词匹配适合检测直接引用是否准确。子序列匹配适合检测改写后的忠实度——即使用词不同，只要核心词汇来自原文且顺序一致，就算忠实。
性能：毫秒级的确定性检查
Verbatimeter 的核心是词级动态规划对齐。实测数据（随机文本，取 5 次最佳）：
| 原文词数 | 候选词数 | 逐词模式 | 子序列模式 |
|---|---|---|---|
| 500 | 100 | 2.2 ms | 8.1 ms |
| 1,000 | 400 | 14.9 ms | 65.9 ms |
| 4,000 | 400 | 53.4 ms | 263.6 ms |
对于大多数 RAG 场景（几千字的上下文、几百字的回答），每次检查在几十毫秒内完成。唯一的运行时依赖是 tiktoken（token 计数用），但也可以传入自定义计数函数，完全跳过 tiktoken。
无障碍与配色
Highlight 配色支持四种主题：
verbatimeter --palette colorblind # 蓝/橙 — 红绿色盲友好 verbatimeter --palette neon # 亮绿/品红 — 暗色终端 verbatimeter --palette mono # 粗体/反白 — 零色彩依赖
同时尊重 NO_COLOR 环境变量、自动检测终端能力，--json 输出纯机器数据。
适合谁用
- RAG 应用开发者：确保 Agent 的回答确实基于检索到的上下文
- AI 写作工具：自动标注哪些段落直接引用来源
- CI/CD 流水线：在发布前阻断含伪造引用的内容
- AI 安全研究者：确定性 metric 比 judge model 更可复现、更可审计
Verbatimeter 不做什么：不判断语义正确性、不检查"这个推理逻辑对不对"。它的职责非常狭窄——只回答一个问题："这句话里的这些词，在原文中出现过吗？"——但回答得确定、瞬间、可复现。在 AI Agent 开始引用外部来源的时代，这层确定性验证是基础的水位线。
获取
- GitHub: github.com/pierreolivierbonin/verbatimeter
- PyPI:
pip install verbatimeter - 许可证: MIT