Langfuse：开源 LLM 可观测性与评估平台实战指南

1. 什么是 Langfuse

Langfuse 是一个开源的 LLM 可观测性与评估平台，用于追踪、监控和调试基于大语言模型的应用。它帮助开发者记录每一次 LLM 调用的输入输出、Token 消耗、延迟和成本，并提供完整的链路追踪能力，覆盖从用户请求到模型响应再到下游工具调用的全过程。

Langfuse 的核心价值在于让 LLM 应用开发具备传统软件工程中的可观测性。无论是 Prompt 调试、成本核算、质量评估还是线上问题排查，Langfuse 都能提供统一的数据视图，是 LLM 应用从原型走向生产的重要基础设施。

2. 核心功能

Langfuse 围绕 LLM 应用的全生命周期提供了一系列能力，主要包括以下几个方面：

链路追踪（Tracing）：以 Trace 和 Span 为粒度记录一次完整请求的执行过程，包括模型调用、检索、工具调用等子步骤。
Prompt 管理：在平台内集中管理 Prompt 版本，支持版本对比、回滚和线上发布，方便团队协作迭代。
评估与打标（Evaluation）：支持人工评分、自定义评分规则以及基于模型的自动评估，帮助衡量输出质量。
数据集管理（Datasets）：沉淀高质量样本用于回归测试、批量评测和微调数据准备。
成本与延迟监控：自动统计每次调用的 Token 用量、费用和耗时，支持按项目、模型、用户等维度聚合分析。
在线调试与回放：在 UI 中查看每次请求的完整输入输出，快速定位 Prompt 或参数问题。

3. 工作原理与架构

Langfuse 采用「SDK 采集 + 服务端存储 + Web 可视化」的整体架构。应用通过官方 SDK 或集成框架（如 LangChain、LlamaIndex、OpenAI SDK）在运行时埋点，将追踪数据异步上报到 Langfuse 服务端，再由前端控制台完成查询、分析和评估。

从数据模型上看，Langfuse 的核心抽象包括：

Trace：一次用户请求的完整记录，是追踪的顶层单位。
Observation（Span / Event / Generation）：Trace 内部的子步骤，用于描述一次模型调用、一次检索或一个中间事件。
Session：将多个 Trace 关联到同一用户会话，便于分析多轮交互。
Score：对某次生成结果的质量评价，可来自人工或自动评估。

Langfuse 支持自托管部署（Docker Compose、Kubernetes）和云托管服务两种方式。自托管时服务端由 Web 应用、Worker 和 PostgreSQL 数据库组成，数据完全掌握在自己手中，适合对数据安全有严格要求的团队。

4. 快速开始

下面以 Python 为例，演示如何在项目中接入 Langfuse。首先安装 SDK：

bash 复制代码

pip install langfuse

然后在代码中初始化客户端并创建追踪：

python 复制代码

from langfuse import Langfuse
langfuse = Langfuse(
public_key="pk-...",
secret_key="sk-...",
host="https://cloud.langfuse.com"
)
创建一次追踪
trace = langfuse.trace(name="user-query")
记录一次 LLM 调用
generation = trace.generation(
name="chat-completion",
model="gpt-4o",
input={"messages": [{"role": "user", "content": "你好"}]},
output={"content": "你好，有什么可以帮你？"}
)
手动结束追踪
trace.update(output="done")

如果使用 LangChain，可以通过回调处理器自动接入，无需手动埋点：

python 复制代码

from langfuse.callback import CallbackHandler
from langchain_openai import ChatOpenAI
langfuse_handler = CallbackHandler()
llm = ChatOpenAI(model="gpt-4o")
response = llm.invoke("介绍一下 Langfuse", config={"callbacks": [langfuse_handler]})

运行上述代码后，即可在 Langfuse 控制台中看到完整的调用链路、Token 消耗和耗时数据。

5. 与主流框架集成

Langfuse 为常见 LLM 开发框架提供了官方集成，可以在不侵入业务代码的情况下自动完成埋点：

LangChain / LangGraph：通过 CallbackHandler 自动追踪链和 Agent 的每一步执行。
LlamaIndex：通过回调处理器记录检索、合成等关键环节。
OpenAI SDK：通过包装客户端自动记录补全和对话请求。
Haystack、DSPy 等：同样提供对应的集成方式，覆盖主流技术栈。

对于自研框架，也可以直接使用 SDK 的底层 API 手动创建 Trace 和 Generation，保持灵活性的同时获得完整追踪能力。

6. 评估与质量监控

Langfuse 的评估体系分为人工评估和自动评估两类。人工评估可以在控制台中对单条生成结果打分或添加标注，适合需要领域专家判断的场景。自动评估则支持接入模型评判（LLM-as-a-judge）或自定义规则，适合大规模批量质检。

通过将评估结果与 Trace 数据关联，团队可以持续观察 Prompt 迭代对输出质量的影响，形成「采集---评估---优化」的闭环。结合数据集功能，还可以在发布新 Prompt 或新模型前进行回归测试，避免质量回退。

7. 生产环境实践建议

将 Langfuse 落地到生产环境时，建议关注以下几点：

采样策略：高流量场景下可配置采样率，在数据完整性与存储成本之间取得平衡。
数据脱敏：对包含敏感信息的输入输出做脱敏处理后再上报，保障数据安全。
自托管运维：若选择自托管，需规划好 PostgreSQL 的备份、监控和扩容方案。
权限管理：为不同团队配置独立项目和访问权限，避免数据互相干扰。
与告警联动：将错误率、延迟和成本指标接入现有监控告警体系，及时发现问题。

8. 总结

Langfuse 为 LLM 应用提供了从开发调试到线上监控的完整可观测性方案。通过链路追踪、Prompt 管理、评估体系和成本分析等能力，它帮助团队更高效地迭代 Prompt、定位问题并保障服务质量。无论是个人项目还是企业级生产系统，Langfuse 都是一款值得纳入技术栈的开源工具。