Langfuse：LLM 应用的观测、调试与评估平台

2026-07-03
Markdown

Langfuse 是给 LLM / Agent 应用用的可观测性、调试、评估和 Prompt 管理平台。它回答的问题不是“模型能不能调用”，而是：这次 AI 请求到底发生了什么、为什么回答差、成本花在哪、改 prompt 后有没有变好。

最小心智模型

普通后端服务会看 request log、error log、latency、trace、metrics。LLM 应用还多了 prompt、模型输入输出、token、成本、RAG context、tool call、agent step、用户反馈、评估分数。

Langfuse 把这些内容组织成一条可回放链路：

Trace：一次完整用户请求
├── Span：中间步骤，比如检索、工具调用、外部 API
├── Generation：一次模型调用
└── Score：人工反馈、规则分或 LLM-as-a-judge 评价

四个核心词先记住：

概念 含义
Trace 一次完整请求的生命周期
Span 请求中的一个中间步骤
Generation 一次 LLM 调用，包含输入、输出、模型、token、成本
Score 对 trace 或 generation 的质量评价

Trace：一次请求的完整链路

用户问“帮我总结这篇 PDF”，系统内部可能会做很多事：

Trace: summarize-pdf
├── Span: 解析 PDF
├── Span: 切分文本
├── Span: RAG 检索
│   ├── Span: embedding
│   └── Span: vector search
├── Generation: 生成摘要
├── Generation: 改写成中文
└── Final Output: 返回用户

没有 Langfuse 时，你可能只看到最终回答。接入 Langfuse 后，可以看到每一步的输入、输出、耗时、错误和成本。

Generation：看清每次模型调用

一次 Generation 通常会记录：

  • model：用了哪个模型
  • input：system prompt、user message、RAG context
  • output：模型输出
  • usage：prompt tokens、completion tokens
  • cost：本次调用花费
  • latency：耗时
  • metadata：用户、环境、版本、业务标签

这能直接回答很多线上问题：

  • 模型到底看到了什么？
  • system prompt 是哪一版？
  • RAG context 是否拿错？
  • 输出差是模型问题、prompt 问题，还是检索问题？
  • 哪一步最慢？哪一步最贵？

Span：把 RAG 和 Agent 步骤摊开

Span 用来记录非模型调用的中间步骤：

  • 检索数据库
  • 调用外部 API
  • 执行 tool
  • 做 rerank
  • 解析网页
  • 读写文件
  • 进入 fallback

Agent 应用尤其需要 Span。因为 agent 的问题通常不是单次模型调用，而是多步链路里某一步偏了，后面全歪。

一个 research agent 的 trace 可能是：

Trace: research-agent-run
├── Generation: 规划搜索任务
├── Span: web_search("Langfuse docs")
├── Span: fetch_page(...)
├── Generation: 总结资料
├── Span: fetch_page(...)
├── Generation: 生成最终回答
└── Score: factuality = 0.86

有了这条链路，才能判断问题出在规划、搜索、抓取、总结，还是最终生成。

Prompt 管理：知道哪版 prompt 造成了结果

Langfuse 可以把 prompt 从代码里抽出来管理：

prompt name: support-agent-system-prompt
version: v7
content: ...

应用运行时拉取 prompt，并把 prompt 版本写入 trace。

这样可以做到：

  • prompt 版本化
  • 回滚 prompt
  • 对比不同 prompt 版本的效果
  • 回放某次请求时知道它用了哪版 prompt

典型问题：prompt v6 经常格式错，v7 改了约束后是否真的变好？Langfuse 可以把 trace、score 和 prompt version 关联起来看。

Score：把“感觉变好”变成可比较指标

LLM 应用不能只看有没有报错，还要看回答质量。Langfuse 的 Score 可以来自四类来源：

类型 例子
人工反馈 用户点赞/点踩、1-5 星、是否解决问题
规则打分 JSON 是否合法、是否有引用、是否超过字数
LLM-as-a-judge 相关性、忠实度、有害性、是否幻觉
离线评测 用测试集比较不同模型、prompt、pipeline

这样优化就不是凭感觉调 prompt，而是可以看：

方案 成本 延迟 正确率 用户满意度
prompt v1 + GPT-4.1 高 中 90% 82%
prompt v2 + Claude 中 中 92% 86%
prompt v3 + cheaper model 低 快 81% 75%

Dataset 和 Experiment：系统性改进

当你有一批固定测试样本时，可以把它们放进 Dataset：

问题 A → 标准答案 A
问题 B → 标准答案 B
问题 C → 标准答案 C

然后跑不同实验：

  • GPT-4.1 vs Claude
  • prompt v3 vs prompt v4
  • RAG top_k=5 vs top_k=10
  • 加 rerank vs 不加 rerank
  • temperature 0 vs 0.7
  • 使用工具 vs 不使用工具

Experiment 的价值是把“改了一版试试看”变成可复现、可比较的流程。

和传统 APM 的区别

传统 APM 看的是服务运行状态：

HTTP request
DB query
CPU / memory
error
latency

Langfuse 看的是 LLM 应用状态：

prompt
completion
model
token
cost
RAG context
tool call
agent step
score
user feedback
prompt version

所以它更像是 Datadog / Sentry / OpenTelemetry 在 LLM 应用层的补充，而不是替代。

和 AI 网关的关系

Langfuse 不是模型网关，也不是反代。它通常位于应用层和模型调用之间：

用户 / 产品
   ↓
AI 应用层：RAG / Agent / Chatbot
   ↓
观测与评估层：Langfuse
   ↓
模型网关层：LiteLLM / NewAPI / 自建 proxy
   ↓
模型供应商：OpenAI / Anthropic / Gemini / DeepSeek

模型网关回答：请求发给哪个模型、怎么鉴权、怎么限流、怎么计费、怎么 fallback。

Langfuse 回答：这次 AI 调用到底发生了什么、质量如何、成本多少、哪个 prompt 版本导致的、哪里需要优化。

两者互补：

  • LiteLLM / NewAPI 管流量
  • Langfuse 管观测、调试、评估和 prompt 版本

最小接入示例

Python 里可以手动创建 trace 和 generation：

from langfuse import Langfuse

langfuse = Langfuse()

trace = langfuse.trace(
    name="chat-request",
    user_id="user_123",
    input={"message": "帮我解释多区域架构"},
)

generation = trace.generation(
    name="answer-generation",
    model="gpt-4.1",
    input=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "帮我解释多区域架构"},
    ],
    output="多区域架构是...",
)

实际项目里通常不会每一处都手写，可以通过 OpenAI SDK wrapper、LangChain、LlamaIndex、OpenTelemetry、LiteLLM、Vercel AI SDK 等集成自动记录。

什么时候值得接入

适合接入 Langfuse 的场景：

  • 多用户 AI 产品
  • RAG 问答
  • 客服机器人
  • agent / tool calling 系统
  • 多模型 fallback
  • 成本需要监控
  • prompt 经常调整
  • 回答质量需要评估
  • 线上问题需要回放

暂时不太需要的场景：

  • 单人脚本
  • 一次性调用模型
  • 没有线上用户
  • 不需要长期评估质量

一句话总结

Langfuse 是 LLM 应用的黑匣子记录仪、Prompt 版本管理和质量评估平台。AI 应用从“能跑”走向“线上稳定、可调试、可评估、可优化”时，它就开始变得有用。