LettuceDetect 🥬🔍

因为即使是 AI 也需要现实检验！🥬

LettuceDetect 是一款轻量且高效的工具，用于检测检索增强生成（RAG）系统中的幻觉现象。它通过将回答与提供的上下文进行对比，识别出回答中没有依据的部分。该工具基于 RAGTruth 数据集进行训练和评估，并利用 ModernBERT 处理英语，以及 EuroBERT 提供多语言支持，因此非常适合需要大上下文窗口的任务。

我们的模型灵感来源于 Luna 论文，该论文提出了一种基于编码器的模型，并采用了类似的标记级方法。

亮点

• LettuceDetect 解决了现有幻觉检测模型的两大关键限制：
  • 传统基于编码器的方法对上下文窗口的限制
  • 基于 LLM 的方法计算效率低下
• 目前，我们的模型在 RAGTruth 数据集中优于所有其他基于编码器和提示的方法，同时速度更快、体积更小。
• 检测性能甚至超过了一些微调后的 LLM，例如 RAGTruth 中提到的 LLAMA-2-13B，仅略逊于 RAG-HAT 论文中微调的 LLM。

🚀 最新动态

• 2025年8月31日 - 发布版本 0.1.8：新增 TinyLettuce Ettin 模型，涵盖 17M、32M 和 68M 参数量；引入幻觉生成流水线，并添加 RAGFactChecker 用于基于三元组的幻觉检测。
  • 更多详情请参阅 TinyLettuce 博客文章。
  • 我们的 Hugging Face 收藏：TinyLettuce
  • 文档请见：TinyLettuce 文档。
• 2025年5月18日 - 发布版本 0.1.7：借助 EuroBERT 实现多语言支持，覆盖英语、德语、法语、西班牙语、意大利语、波兰语和中文共7种语言！
• 在不同语言上，相比 GPT-4.1-mini 等基准 LLM 判别器，F1 分数提升高达 17点。
• EuroBERT 模型：我们训练了基础版/210M（速度更快）和大型版/610M（精度更高）两种变体。
• 现在您也可以使用 LLM 基准 进行幻觉检测（见下文）。

快速入门

功能特性

• ✨ 标记级精度：精准检测幻觉片段
• 🚀 推理优化：模型体积更小，推理速度更快
• 🧠 长上下文窗口支持（ModernBERT 支持4K，EuroBERT 支持8K）
• 🌍 多语言支持：覆盖7种语言
• ⚖️ MIT 许可证 的模型与代码
• 🤖 Hugging Face 集成：一行代码即可加载模型
• 📦 易用的 Python API：可通过 pip 安装，只需几行代码即可集成到您的 RAG 系统。

安装

从仓库安装：

pip install -e .

或通过 pip 安装：

pip install lettucedetect -U

快速开始

请查看我们在 Hugging Face 上发布的模型：

英语模型：

• 基础版：KRLabsOrg/lettucedect-base-modernbert-en-v1
• 大型版：KRLabsOrg/lettucedect-large-modernbert-en-v1

多语言模型： 我们训练了 EuroBERT 的 210M 和 610M 变体，请参阅我们的 Hugging Face 收藏：HF 模型

完整模型列表及小型变体请访问我们的 Hugging Face 页面。

您只需几行代码即可快速开始使用。

from lettucedetect.models.inference import HallucinationDetector

# 英语：
detector = HallucinationDetector(
    method="transformer", 
    model_path="KRLabsOrg/lettucedect-base-modernbert-en-v1",
)

# 其他语言（如德语）：
# detector = HallucinationDetector(
#     method="transformer", 
#     model_path="KRLabsOrg/lettucedect-210m-eurobert-de-v1",
#     lang="de",
#     trust_remote_code=True
# )

contexts = ["法国是欧洲的一个国家。法国的首都是巴黎。法国的人口为6700万。"]
question = "法国的首都是什么？法国的人口是多少？"
answer = "法国的首都是巴黎。法国的人口为6900万。"

# 获取跨度级别的预测结果，指示回答中哪些部分被认为是幻觉。
predictions = detector.predict(context=contexts, question=question, answer=answer, output_format="spans")
print("预测结果:", predictions)

# 预测结果：[{'start': 31, 'end': 71, 'confidence': 0.9944414496421814, 'text': '法国的人口为6900万。'}]

更多示例请参阅我们的 HF 收藏。

我们还实现了基于 LLM 的基准方法，为此请设置您的 OpenAI API 密钥：

export OPENAI_API_KEY=your_api_key

然后在代码中：

from lettucedetect.models.inference import HallucinationDetector

# 德语：
detector = HallucinationDetector(method="llm", lang="de")

# 接着以相同的方式进行预测
predictions = detector.predict(context=contexts, question=question, answer=answer, output_format="spans")

性能表现

我们已将我们的模型与基于编码器和基于 LLM 的方法进行了对比评估。主要发现包括：

• 在英语方面，我们的模型在 RAGTruth 数据集中优于所有其他基于编码器和提示的方法，且速度更快、体积更小。
• 我们的多语言模型表现优于 GPT-4.1-mini 等基准 LLM 判别器。
• 此外，我们的模型在速度和体积上也显著优于基于 LLM 的判别器。

有关详细性能指标和模型评估：

• 英语模型文档
• 多语言模型文档
• 论文
• 模型卡片

它是如何工作的？

该模型是一个基于标记的分类模型，用于预测某个标记是否为幻觉内容。模型经过训练，能够在给定上下文和问题的情况下，识别出答案中哪些标记是幻觉生成的。

flowchart LR
    subgraph Inputs
        Context["**上下文**: 法国是欧洲的一个国家。人口为6700万。"]
        Question["**问题**: 首都是什么？人口是多少？"]
        Answer["**回答**: 法国的首都是巴黎。人口为6900万。"]
    end

    Model["**LettuceDetect**: 标记分类"]
    Tokens["**标记概率**: <br> ... <br> The [0.01] <br> population [0.02] <br> is [0.01] <br> 69 [0.95] <br> million [0.95]"]

    Context --> Model
    Question --> Model
    Answer --> Model
    Model --> Tokens

模型训练

首先需要从这里下载 RAGTruth 数据集，并将其放置在 data/ragtruth 目录下。然后运行以下命令：

python lettucedetect/preprocess/preprocess_ragtruth.py --input_dir data/ragtruth --output_dir data/ragtruth

这将生成一个 data/ragtruth/ragtruth_data.json 文件，其中包含处理后的数据。

接下来，可以使用以下命令训练模型：

python scripts/train.py \
    --ragtruth-path data/ragtruth/ragtruth_data.json \
    --model-name answerdotai/ModernBERT-base \
    --output-dir output/hallucination_detector \
    --batch-size 4 \
    --epochs 6 \
    --learning-rate 1e-5 

我们使用单个 A100 GPU，在批大小为 8 的情况下训练了 6 个 epoch。

模型评估

可以在不同层级（示例、标记和跨度）以及不同数据类型上对模型进行评估。

python scripts/evaluate.py \
    --model_path outputs/hallucination_detector \
    --data_path data/ragtruth/ragtruth_data.json \
    --evaluation_type example_level

模型输出格式

模型可以以两种格式输出预测结果：

跨度格式

[{
    'text': str,        # 幻觉文本
    'start': int,       # 在回答中的起始位置
    'end': int,         # 在回答中的结束位置
    'confidence': float # 模型置信度（0-1）
}]

标记格式

[{
    'token': str,       # 标记
    'pred': int,        # 0：支持，1：幻觉
    'prob': float       # 模型置信度（0-1）
}]

Streamlit 演示

请查看 Streamlit 演示，了解模型的实际应用效果。

安装 Streamlit：

pip install streamlit

运行演示：

streamlit run demo/streamlit_demo.py

使用 Web API

LettuceDetect 自带 Web API 和 Python 客户端库。要使用它，请确保安装包含可选 API 依赖项的包：

pip install -e .[api]

或者

pip install lettucedetect[api]

使用 scripts/start_api.py 脚本启动 API 服务器：

python scripts/start_api.py dev  # 生产环境使用 "prod"

用法：

usage: start_api.py [-h] [--model MODEL] [--method {transformer}] {prod,dev}

启动 LettuceDetect Web API。

位置参数:
  {prod,dev}            选择 "dev" 进行开发，或 "prod" 进行生产环境部署。
                        服务脚本会根据模式分别使用 "fastapi dev" 或 "fastapi run" 来启动 Web 服务器。此外，在 "dev" 模式下，可以直接从仓库导入 Python 模块，而无需安装包。

选项:
  -h, --help            显示帮助信息并退出
  --model MODEL         模型路径或 Hugging Face URL。默认值为
                        "KRLabsOrg/lettucedect-base-modernbert-en-v1"。
  --method {transformer}
                        幻觉检测方法。默认值为
                        "transformer"。

使用 Python 客户端库的示例：

from lettucedetect_api.client import LettuceClient

contexts = [
    "法国是欧洲的一个国家。 "
    "法国的首都是巴黎。 "
    "法国的人口为6700万。",
]
question = "法国的首都是什么？法国的人口是多少？"
answer = "法国的首都是巴黎。法国的人口为6900万。"

client = LettuceClient("http://127.0.0.1:8000")
response = client.detect_spans(contexts, question, answer)
print(response.predictions)

# [SpanDetectionItem(start=31, end=71, text=' 法国的人口为6900万。', hallucination_score=0.989198625087738)]

更多示例请参阅 demo/detection_api.ipynb。如需异步支持，请改用 LettuceClientAsync 类。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

引用

如果您在工作中使用了 LettuceDetect，请引用以下论文：

@misc{Kovacs:2025,
      title={LettuceDetect: 一种用于 RAG 应用的幻觉检测框架}, 
      author={Ádám Kovács 和 Gábor Recski},
      year={2025},
      eprint={2502.17125},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2502.17125}, 
}

LettuceDetect 快速上手指南

LettuceDetect 是一款轻量级且高效的工具，专为检测检索增强生成（RAG）系统中的“幻觉”（即模型生成的与上下文不符的内容）而设计。它支持英语及多种语言（包括中文），能够精确识别答案中缺乏依据的片段。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.8 及以上
• 依赖项：
  • torch (PyTorch)
  • transformers (Hugging Face)
  • accelerate (可选，用于加速推理)

提示：国内开发者建议使用清华或阿里镜像源加速依赖安装。

安装步骤

方式一：通过 PyPI 安装（推荐）

pip install lettucedetect -U -i https://pypi.tuna.tsinghua.edu.cn/simple

如需使用 Web API 功能，请安装额外依赖：

pip install "lettucedetect[api]" -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

git clone https://github.com/KRLabsOrg/LettuceDetect.git
cd LettuceDetect
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下示例展示如何使用预训练模型检测答案中的幻觉内容。

1. 检测英文内容

from lettucedetect.models.inference import HallucinationDetector

# 初始化检测器（英文模型）
detector = HallucinationDetector(
    method="transformer", 
    model_path="KRLabsOrg/lettucedect-base-modernbert-en-v1",
)

contexts = ["France is a country in Europe. The capital of France is Paris. The population of France is 67 million."]
question = "What is the capital of France? What is the population of France?"
answer = "The capital of France is Paris. The population of France is 69 million."

# 获取片段级别的预测结果
predictions = detector.predict(context=contexts, question=question, answer=answer, output_format="spans")
print("Predictions:", predictions)

输出示例：

Predictions: [{'start': 31, 'end': 71, 'confidence': 0.9944414496421814, 'text': ' The population of France is 69 million.'}]

2. 检测中文或其他多语言内容

LettuceDetect 基于 EuroBERT 支持包括中文在内的 7 种语言。

from lettucedetect.models.inference import HallucinationDetector

# 初始化检测器（中文模型需指定 lang 参数）
detector = HallucinationDetector(
    method="transformer", 
    model_path="KRLabsOrg/lettucedect-210m-eurobert-zh-v1", # 假设存在中文模型路径，请根据 HF 实际地址调整
    lang="zh",
    trust_remote_code=True
)

contexts = ["中国的首都是北京。中国的人口约为 14 亿。"]
question = "中国的首都是哪里？人口是多少？"
answer = "中国的首都是北京。中国的人口约为 15 亿。"

predictions = detector.predict(context=contexts, question=question, answer=answer, output_format="spans")
print("Predictions:", predictions)

注意：具体多语言模型路径请参考 Hugging Face 模型集合。

3. 使用 LLM 作为基线检测（可选）

若需使用大语言模型（如 GPT-4）进行对比检测，需先设置 API Key：

export OPENAI_API_KEY=your_api_key

代码调用：

from lettucedetect.models.inference import HallucinationDetector

# 使用 LLM 方法检测
detector = HallucinationDetector(method="llm", lang="zh")

predictions = detector.predict(context=contexts, question=question, answer=answer, output_format="spans")
print("Predictions:", predictions)