langchain-halu：给LangChain加一层LLM幻觉检测

一个针对LLM幻觉的轻量LangChain集成

大语言模型的幻觉问题（编造事实、伪造引用）一直是生产环境落地的痛点。近日一位开发者在Reddit上分享了自己的开源项目 langchain-halu（Apache-2.0协议），试图用一种更工程化的方式，把幻觉检测直接嵌入到LangChain的调用链中。

这个项目的定位很明确：它不是一个大而全的框架，而是一层"薄"的集成代码。核心思路是提供几个小型的 Runnable，让开发者能够在 LCEL（LangChain Expression Language）链条中原地插入一次幻觉检查，而不需要重构现有的调用逻辑。

三种处理策略：标注、拦截与重试

项目最有价值的设计在于，它没有把幻觉检测停留在"打分"这一步，而是提供了三种可组合的下游动作：

annotate（标注）：给生成结果附加一个幻觉概率分数，供后续逻辑参考，但不改变输出内容。
gate（拦截）：当结果被判定为很可能是幻觉时，直接抛出异常或替换掉这段内容，起到"闸门"的作用。
auto-retry（自动重试）：带着反馈信息让模型重新生成，直到输出通过检测为止。

这种分层设计在实际项目中很实用——不同场景对幻觉的容忍度差异很大。内部工具可能只需要标注提醒，而面向用户的问答系统则可能需要严格拦截或强制重试。

极简的接入方式

从代码上看，接入成本被控制得很低：

from langchain_halu import halu_guard

chain = prompt | model | StrOutputParser() | halu_guard(threshold=0.5)

只需在已有的 LCEL 链尾部追加一个 halu_guard 节点并设定阈值，整条链就获得了幻觉守卫能力。对于已经在使用 LangChain 的团队来说，这种"即插即用"的形式几乎没有迁移负担。

这三种策略在软件工程中对应了一种经典的"防御性编程"模式。annotate 类似于日志采集，适合在灰度阶段积累数据；gate 类似于断路器（Circuit Breaker）模式，在检测到异常时快速失败以保护下游；auto-retry 则类似于指数退避重试，但不同之处在于它会把检测结果作为反馈注入到新的 Prompt 中，引导模型自我修正，而非简单地重发同一请求。将三者分离而非合并为单一行为，使得开发者可以根据 SLA 要求、成本预算和用户体验目标灵活组合——例如在高吞吐场景下优先选 annotate 以避免重试带来的延迟，在合规场景下强制启用 gate。

LCEL（LangChain Expression Language）是 LangChain 0.1 版本引入的链式调用语法，核心设计是将 Prompt、模型调用、输出解析等各环节统一抽象为 Runnable 接口，用管道符 | 串联，类似 Unix 管道。每个 Runnable 既可以同步调用，也天然支持异步和流式传输，并可直接接入 LangSmith 进行追踪。langchain-halu 将 halu_guard 也实现为一个 Runnable，使其能无缝插入任意位置而不破坏链的接口契约，这正是 LCEL 设计的核心优势——扩展点对用户透明且改动最小。

底层检测器：校准概率与错误类型

据作者介绍，halu_guard 背后调用的是他自己一直在开发的检测器。这个检测器不只返回一个简单的是/否判断，而是给出一个经过校准的概率值，同时标注出错误的类型——比如"捏造的事实"（fabricated fact）或"虚假的引用"（fake citation）。

返回错误类型这一点值得关注。相比单纯的置信度分数，明确区分是事实性错误还是引用造假，能让开发者制定更有针对性的处置策略。例如在学术或法律场景中，伪造引用的危害往往比一般的事实偏差更严重。

需要注意的是，检测器本身需要一个（免费的）API Key 才能使用，但集成层的代码是完全开源且透明的。这意味着开发者可以自由审查、修改集成逻辑，而核心检测能力则依赖远端服务。

"经过校准的概率值"是一个值得细究的表述。普通分类模型输出的置信度分数往往存在过度自信（overconfidence）问题——模型以 0.95 的置信度给出的预测，实际准确率可能远低于 95%。概率校准（Probability Calibration）是通过 Platt Scaling、Isotonic Regression 等后处理技术，让模型输出的概率与真实频率更吻合。对幻觉检测来说，校准的概率更有实际意义：开发者设定 threshold=0.5 时，含义是"我希望误报率与漏报率达到某种平衡"，而非仅凭直觉选一个数字。未经校准的分数则难以合理解释阈值的实际含义。

诚实的能力边界

难得的是，作者在分享时明确列出了这个工具的局限，没有夸大其能力：

它提供的是一个概率信号，而非事实核查器——它告诉你某段内容"看起来"有多大可能是幻觉，但不能替你去验证真伪。
目前仅支持英语。
在完整的回复上效果最好，对流式或片段化输出的支持有限。

这些坦诚的边界说明反而增强了项目的可信度。幻觉检测本质上是一个难题，任何声称能"彻底解决"的工具都值得警惕。把它定位为一层辅助性的风险信号，而不是最终裁决者，是更务实的做法。

值得关注的工程化方向

作者也做了充分的利益披露：检测器和集成层都是他本人开发的，分享的是集成而非推广商业产品，并表示如果不合适可以随时下架。这种坦率在开发者社区中往往更容易获得信任。

从更宏观的角度看，langchain-halu 反映了一个正在成熟的趋势：LLM 应用的可靠性正在从模型层面下沉到工程层面。与其等待更强的模型彻底消除幻觉，不如在调用链中构建检测、拦截、重试等防护机制，把不可靠的输出挡在用户之前。对于正在构建 RAG 或 Agent 应用的团队来说，这类轻量的守卫组件提供了一个可参考的实践模式。

项目地址：github.com/komplexai/langchain-halu