openlit's LogoOpenLIT
Published on
2026年4月7日，星期二

How to Detect Hallucinations in Your RAG Pipeline (with Code Examples)如何检测RAG管道中的幻觉（附代码示例）

How to Detect Hallucinations in Your RAG Pipeline (with Code Examples)

TL;DR: Hallucinations are the most common production failure in RAG systems. OpenLIT's eval SDK lets you detect them programmatically — using an LLM-as-judge approach — and export results as OpenTelemetry signals alongside your existing traces. No separate eval platform needed.TL;DR：幻觉是RAG系统中最常见的生产故障。OpenLIT的评估SDK让您能够以编程方式检测它们——采用LLM作为评判者的方法——并将结果作为OpenTelemetry信号与现有追踪一起导出。无需单独的评估平台。

Why RAG Systems Hallucinate为什么RAG系统会产生幻觉

You built a RAG pipeline. Your retriever pulls relevant documents. Your LLM generates answers grounded in those documents. And yet, sometimes the output contains information that exists nowhere in the retrieved context.您构建了一个RAG管道。您的检索器拉取相关文档。您的LLM基于这些文档生成答案。然而，有时输出中包含的信息在检索到的上下文中根本不存在。

This happens for a few reasons:这有几个原因：

Retrieval gaps. The retriever returned documents that are topically related but don't actually contain the answer. The LLM fills in the blanks from its training data — or makes something up entirely.检索缺口。检索器返回的文档在主题上相关，但实际上并不包含答案。LLM从其训练数据中填补空白——或者完全编造内容。

Context window overflow. You stuffed too many documents into the context. Research shows LLMs tend to ignore information in the middle of long contexts (the "lost in the middle" problem). The model generates a plausible-sounding answer from the parts it paid attention to.上下文窗口溢出。您向上下文中塞入了太多文档。研究表明，LLM倾向于忽略长上下文中间的信息（“迷失在中间”问题）。模型根据它关注的部分生成听起来合理的答案。

Model confidence. LLMs don't say "I don't know" by default. They're trained to be helpful, which means they'll produce a fluent answer even when they shouldn't.模型自信。LLM默认不会说“我不知道”。它们被训练成乐于助人，这意味着即使不应该，它们也会生成流畅的答案。

The fix isn't to eliminate hallucinations (you can't, not completely). It's to detect them reliably and decide what to do — flag them, retry with different context, or fall back to a canned response.解决方法不是消除幻觉（您无法完全消除）。而是可靠地检测它们并决定如何处理——标记它们、用不同的上下文重试，或回退到预设响应。

Setting Up Hallucination Detection设置幻觉检测

Install the OpenLIT SDK if you haven't already:如果尚未安装，请安装OpenLIT SDK：

pip install openlit

Here's how to check an LLM response for hallucinations:以下是如何检查LLM响应是否存在幻觉：

from openlit.evals import Hallucination

detector = Hallucination(
    provider="openai",
    api_key="sk-...",       # or set OPENAI_API_KEY env var
    model="gpt-4o-mini",    # the judge model
    threshold_score=0.5,
)

result = detector.measure(
    prompt="What is the refund policy for enterprise customers?",
    contexts=[
        "Enterprise customers can request a refund within 30 days of purchase.",
        "All refunds are processed within 5-7 business days.",
    ],
    text="Enterprise customers can request a full refund within 60 days of purchase, "
         "and refunds are processed instantly.",
)

print(result)
# {
#   "score": 0.8,
#   "verdict": "yes",
#   "guard": "hallucination",
#   "classification": "factual_inconsistency",
#   "explanation": "The response states 60 days and instant processing, but the context says 30 days and 5-7 business days."
# }

The measure method sends the prompt, retrieved contexts, and the LLM's response to a judge model. The judge evaluates whether the response is faithful to the provided context.measure方法将提示、检索到的上下文和LLM的响应发送给评判模型。评判模型评估响应是否忠实于提供的上下文。

  • score — A 0-1 score. Higher means more likely to be a hallucination.score — 0-1分数。越高表示越可能是幻觉。

  • verdict — "yes" if the score exceeds threshold_score, "no" otherwise.verdict — 如果分数超过threshold_score则为“yes”，否则为“no”。

  • classification — The type of hallucination detected.classification — 检测到的幻觉类型。

  • explanation — Human-readable reasoning from the judge.explanation — 来自评判模型的人类可读推理。

Using Any LLM as Judge使用任何LLM作为评判者

You're not locked into OpenAI as the judge. Use any provider that exposes an OpenAI-compatible API:您不必局限于OpenAI作为评判者。使用任何暴露OpenAI兼容API的提供商：

# Use Anthropic
detector = Hallucination(
    provider="anthropic",
    api_key="sk-ant-...",
    model="claude-sonnet-4-20250514",
)

# Use a local model via Ollama
detector = Hallucination(
    provider="openai",          # Ollama exposes an OpenAI-compatible API
    base_url="http://localhost:11434/v1",
    model="llama3",
    api_key="ollama",           # Ollama doesn't need a real key
)

# Use Azure OpenAI
detector = Hallucination(
    provider="openai",
    base_url="https://your-resource.openai.azure.com/openai/deployments/gpt-4o",
    api_key="your-azure-key",
    model="gpt-4o",
)

Adding Toxicity and Bias Detection添加毒性和偏见检测

Hallucinations aren't the only thing that can go wrong. OpenLIT's eval SDK also covers toxicity and bias:幻觉不是唯一可能出错的问题。OpenLIT的评估SDK还涵盖毒性和偏见：

Toxicity Detection毒性检测

from openlit.evals import ToxicityDetector

toxicity = ToxicityDetector(
    provider="openai",
    model="gpt-4o-mini",
    threshold_score=0.5,
)

result = toxicity.measure(
    text="The LLM output you want to check",
    prompt="The original user prompt",
    contexts=["Retrieved context documents"],
)

if result["verdict"] == "yes":
    print(f"Toxic content detected: {result['explanation']}")

Bias Detection偏见检测

from openlit.evals import BiasDetector

bias = BiasDetector(
    provider="openai",
    model="gpt-4o-mini",
    threshold_score=0.5,
)

result = bias.measure(
    text="The LLM output you want to check",
    prompt="The original user prompt",
    contexts=["Retrieved context documents"],
)

if result["verdict"] == "yes":
    print(f"Bias detected: {result['explanation']}")

Run All Checks at Once一次性运行所有检查

If you want hallucination + toxicity + bias in a single call:如果您想在一次调用中完成幻觉+毒性+偏见：

from openlit.evals import All

evaluator = All(
    provider="openai",
    model="gpt-4o-mini",
    threshold_score=0.5,
)

results = evaluator.measure(
    prompt="user question",
    contexts=["context doc 1", "context doc 2"],
    text="LLM response to evaluate",
)

Custom Evaluation Categories自定义评估类别

The default categories cover common failure modes, but you can define your own:默认类别涵盖常见故障模式，但您可以定义自己的类别：

detector = Hallucination(
    provider="openai",
    model="gpt-4o-mini",
    custom_categories={
        "medical_misinformation": "Response contains medical claims not supported by the provided clinical context",
        "numerical_error": "Response contains numbers, dates, or quantities that differ from the source documents",
    },
    threshold_score=0.3,  # stricter threshold for medical use cases
)

This is especially useful for domain-specific applications where generic "hallucination" isn't granular enough.这对于通用“幻觉”不够细粒度的特定领域应用尤其有用。

Exporting Eval Results as OpenTelemetry Signals将评估结果导出为OpenTelemetry信号

Here's what makes OpenLIT's approach different from standalone eval tools: evaluation results are exported as OpenTelemetry signals, right alongside your traces.OpenLIT的方法与独立评估工具的不同之处在于：评估结果作为OpenTelemetry信号导出，与您的追踪并列。

When you initialize OpenLIT with tracing enabled, eval results automatically get emitted as OTel Log Records:当您启用追踪初始化OpenLIT时，评估结果会自动作为OTel日志记录发出：

import openlit
from openlit.evals import Hallucination

openlit.init(
    otlp_endpoint="http://localhost:4318",
    application_name="my-rag-app",
)

detector = Hallucination(
    provider="openai",
    model="gpt-4o-mini",
)

result = detector.measure(
    prompt="...",
    contexts=["..."],
    text="...",
    response_id="trace-span-id-here",  # ties eval to the original trace
)

The response_id parameter links the evaluation result to the original LLM trace span. This means you can:response_id参数将评估结果链接到原始LLM追踪跨度。这意味着您可以：

  1. Look at a trace in your dashboard在仪表板中查看追踪

  2. See the eval result attached to it查看附加到其上的评估结果

  3. Filter traces by eval verdict ("show me all hallucinated responses")按评估判定过滤追踪（“显示所有产生幻觉的响应”）

By default, results are exported as OTel Log Records. You can also configure them to be emitted as OTel Events:默认情况下，结果作为OTel日志记录导出。您也可以将它们配置为作为OTel事件发出：

openlit.init(
    evals_logs_export=True,  # default: Log Records
)

Integrating Into Your RAG Pipeline集成到您的RAG管道中

Here's a complete example showing evals integrated into a RAG workflow:以下是一个完整示例，展示了评估如何集成到RAG工作流中：

import openlit
from openlit.evals import Hallucination
from openai import OpenAI

openlit.init(otlp_endpoint="http://localhost:4318")

client = OpenAI()
hallucination_detector = Hallucination(provider="openai", model="gpt-4o-mini")

def answer_question(question: str, documents: list[str]) -> dict:
    context = "\n\n".join(documents)

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"Answer based on this context:\n{context}"},
            {"role": "user", "content": question},
        ],
    )

    answer = response.choices[0].message.content

    eval_result = hallucination_detector.measure(
        prompt=question,
        contexts=documents,
        text=answer,
    )

    return {
        "answer": answer,
        "hallucination_score": eval_result["score"],
        "is_hallucinated": eval_result["verdict"] == "yes",
        "explanation": eval_result["explanation"],
    }


result = answer_question(
    question="What's the maximum file upload size?",
    documents=[
        "The maximum file upload size is 50MB for free tier users.",
        "Enterprise users can upload files up to 500MB.",
    ],
)

if result["is_hallucinated"]:
    print(f"Warning: Response may contain hallucinations. {result['explanation']}")
else:
    print(result["answer"])

Setting Up Auto-Evaluation in the OpenLIT Platform在OpenLIT平台中设置自动评估

If you're running the self-hosted OpenLIT platform, you can configure auto-evaluation from the settings page:如果您运行自托管的OpenLIT平台，可以从设置页面配置自动评估：

  1. Go to Settings → Evaluation Config转到设置 → 评估配置

  2. Set your eval provider (OpenAI, Anthropic, or any compatible endpoint)设置您的评估提供商（OpenAI、Anthropic或任何兼容端点）

  3. Store the API key in the Vault (OpenLIT's built-in secrets manager)将API密钥存储在Vault（OpenLIT内置的秘密管理器）中

  4. Enable auto-evaluation启用自动评估

Once enabled, the platform automatically runs hallucination checks on incoming traces. Results show up in the dashboard alongside your traces.启用后，平台会自动对传入的追踪运行幻觉检查。结果会与您的追踪一起显示在仪表板中。

When to Evaluate (and When Not To)何时评估（以及何时不评估）

Running an LLM judge on every response adds latency and cost. Here are practical strategies:对每个响应运行LLM评判者会增加延迟和成本。以下是一些实用策略：

Sample in production: Evaluate 10-20% of responses in production. Enough to catch systemic issues without doubling your LLM costs.在生产中采样：评估生产中10-20%的响应。足以捕捉系统性问题，而不会使LLM成本翻倍。

Evaluate everything in staging: Run full evals in your staging environment before deploying prompt changes.在预发布环境中全面评估：在部署提示更改之前，在预发布环境中运行完整评估。

Use thresholds to trigger actions: Set threshold_score=0.3 for strict use cases (medical, legal, financial) and 0.7 for low-stakes use cases (content suggestions, summaries).使用阈值触发操作：对于严格用例（医疗、法律、金融）设置threshold_score=0.3，对于低风险用例（内容建议、摘要）设置0.7。

Gate on evals in CI/CD: Run evals against a test dataset before deploying. If hallucination rate exceeds your threshold, block the deployment.在CI/CD中基于评估设置门禁：在部署前对测试数据集运行评估。如果幻觉率超过阈值，则阻止部署。

FAQ

Can I use my own LLM as judge?我可以使用自己的LLM作为评判者吗？

Yes. Any OpenAI-compatible API works — including local models via Ollama, vLLM, or any other server that exposes a /v1/chat/completions endpoint. Set the base_url parameter.可以。任何OpenAI兼容的API都可以——包括通过Ollama、vLLM或任何其他暴露/v1/chat/completions端点的服务器运行的本地模型。设置base_url参数。

How do I evaluate in CI/CD?如何在CI/CD中进行评估？

Run your eval suite as a Python script in CI. Use a test dataset of (question, context, expected_answer) triples, measure each with the Hallucination class, and fail the pipeline if the hallucination rate exceeds a threshold.在CI中将评估套件作为Python脚本运行。使用（问题、上下文、预期答案）三元组的测试数据集，用Hallucination类测量每个三元组，如果幻觉率超过阈值则使管道失败。

What's the cost of running evals?运行评估的成本是多少？

Each eval call is one LLM call to your judge model. With gpt-4o-mini, that's roughly $0.0001-0.001 per evaluation depending on context length. At 10% sampling of 10,000 requests/day, that's about $1-10/day.每次评估调用是对评判模型的一次LLM调用。使用gpt-4o-mini，根据上下文长度，每次评估大约$0.0001-0.001。以每天10,000次请求的10%采样率计算，大约每天$1-10。

Does it work with non-English text?它适用于非英语文本吗？

Yes, as long as your judge model supports the language. GPT-4o and Claude both handle multilingual evaluation well.是的，只要您的评判模型支持该语言。GPT-4o和Claude都能很好地处理多语言评估。

Discuss on Twitter在Twitter上讨论 • View on GitHub在GitHub上查看在Twitter上讨论 • 在GitHub上查看
openlitopenlit
ragrag
hallucinationhallucination
evaluationevaluation
llmllm
pythonpython
  • Name
    Twitter

Previous Article上一篇文章

GPU Monitoring for LLM Inference: What to Track and Why It MattersLLM推理的GPU监控：跟踪什么以及为什么重要