主题
阶段 1：Langfuse 是什么？
预计学习时间：半天
一句话总结：Langfuse 是专为 LLM 应用设计的「可观测性 + 工程化」平台。
目录
1. 从一个生活场景开始
想象你开了一家智能客服奶茶店：
顾客：「我要一杯少糖去冰的珍珠奶茶，顺便查一下我上周的订单」
背后发生的事：
① 前台听懂需求（意图识别）
② 查订单系统（Tool 调用）
③ 问配方 AI（LLM 生成回复）
④ 再次确认库存（RAG 检索）
⑤ 回复顾客顾客只看到了最终一句话：「好的，已为您下单少糖去冰珍珠奶茶，上周您共有 2 笔订单……」
但作为老板，你需要知道：
- AI 到底理解了什么？有没有听错「少糖」？
- 查订单那次调用成功了吗？花了多久？
- 这次回复用了多少 token？花了多少钱？
- 顾客不满意时，能回放完整过程吗？
这就是 LLM 应用可观测性（LLM Observability） 要解决的问题。
Langfuse 就是这套「后厨监控 + 顾客反馈」系统。
2. 传统监控为什么不够用
2.1 普通日志：像便利贴
[2026-06-05 10:00:01] INFO 收到用户消息
[2026-06-05 10:00:02] INFO 调用 OpenAI
[2026-06-05 10:00:04] INFO 返回结果问题：
- 三条日志看不出因果关系（哪次 LLM 对应哪次 Tool？）
- 没有 token、模型名、prompt 原文
- 多轮对话时，日志散落各处，无法按「一次对话」聚合
2.2 传统 APM（如 Jaeger）：像公路摄像头
Jaeger 擅长追踪：
API Gateway → User Service → Order Service → MySQL它对 HTTP 请求链路 很专业，但对 LLM 应用「看不懂」：
| LLM 特有信息 | 传统 APM |
|---|---|
| Prompt 原文 | ❌ 通常不记录 |
| Completion 原文 | ❌ |
| Token 用量 | ❌ |
| 模型参数 temperature | ❌ |
| Tool 调用的 input/output | ⚠️ 需大量自定义 |
| RAG 检索到的文档片段 | ❌ |
2.3 Langfuse 的定位
┌─────────────────────────────────────────────────────────┐
│ Langfuse 平台 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Tracing │ │ Prompt │ │ Eval │ │ Dashboard│ │
│ │ 追踪 │ │ 管理 │ │ 评测 │ │ 看板 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────┘
↑ 专为 LLM / Agent 应用设计3. Langfuse 是什么
Langfuse（读作「Lang-fuse」，lang + fuse，把语言模型相关的数据「熔合」到一起）是一个开源的 LLM 工程平台，核心能力包括：
- Tracing（追踪）：记录每次请求的完整链路
- Prompt Management（提示词管理）：版本化、发布、回滚 Prompt
- Evaluation（评测）：人工或 LLM 自动打分
- Datasets & Experiments（数据集与实验）：对比不同模型/Prompt 效果
- Analytics（分析）：延迟、成本、用量统计
它由德国创业公司 Langfuse GmbH 开发，YC W23 批次，GitHub 2 万+ Star，可自托管也可使用云服务。
核心设计哲学
不拖慢你的应用。
Langfuse SDK 在后台异步批量上报数据，不会让你的 API 响应变慢。就像外卖平台记录订单，不会因为你点了外卖就让厨师炒菜变慢。
4. 和其他工具对比
| 工具 | 擅长什么 | 和 Langfuse 的关系 |
|---|---|---|
| 普通日志（ELK/Loki） | 记录离散事件 | Langfuse 结构化程度更高，专为 LLM 设计 |
| Jaeger / Zipkin | 分布式 HTTP 追踪 | Langfuse 底层兼容 OTel，但 UI 和模型更懂 LLM |
| OpenTelemetry | 统一采集标准 | Langfuse 是 OTel 的「下游消费者」之一 |
| LangSmith | LangChain 生态追踪 | 商业产品，绑定 LangChain；Langfuse 开源、框架无关 |
| Weights & Biases | ML 实验跟踪 | 偏训练阶段；Langfuse 偏推理/应用阶段 |
| Prometheus | 指标监控 | 互补：Langfuse 看单次请求细节，Prometheus 看聚合指标 |
生活类比：
- 普通日志 = 收银台小票
- Jaeger = 商场监控（看人流走向）
- Langfuse = 奶茶店「全流程录像 + 原料消耗单 + 顾客满意度表」
5. Langfuse 能帮你做什么
场景 1：调试「AI 胡说八道」
用户在客服里问「退款政策」，AI 回答了完全错误的内容。
在 Langfuse 里点开这条 Trace，你能看到：
- 实际发给模型的 Prompt（是不是 RAG 检索错了文档？）
- 检索到的 chunks 是什么
- 模型 Completion 原文
- 哪一步 Tool 返回了脏数据
场景 2：成本失控
月底账单暴涨。在 Langfuse Dashboard 里：
- 按
model分组看 token 消耗 - 找出「单次请求 token 最多」的 Trace
- 发现某个 Agent 循环调用了 20 次 LLM
场景 3：Prompt 迭代
你把 Prompt 从 v1 改到 v2，想对比效果：
- Prompt Management 管理版本
- 用 Datasets 跑批量实验
- Evaluation 自动打分，看 v2 是否真的更好
场景 4：多轮对话复盘
用户说「第 3 轮开始你就答非所问了」。
用 Session 把同一聊天室的多条 Trace 串起来，逐轮回放。
6. 部署方式
| 方式 | 适合谁 | 说明 |
|---|---|---|
| Langfuse Cloud | 个人/小团队快速上手 | https://cloud.langfuse.com，免费额度可用 |
| 自托管（Docker） | 企业、数据不出内网 | 官方提供 docker-compose / Helm |
| 自托管（K8s） | 大规模生产 | 社区 Helm Chart |
自托管需要你自己维护 PostgreSQL、ClickHouse、Redis 等依赖（官方文档有完整清单）。
学习阶段建议：先用 Cloud，专注理解概念；生产环境再评估自托管。
7. 学习检查
- [ ] 能用「智能客服奶茶店」的例子向别人解释 Langfuse 的价值
- [ ] 能说出 Langfuse 和普通日志、Jaeger 的一个关键区别
- [ ] 知道 Langfuse 是开源的，Tracing 只是其能力之一
- [ ] 已注册 Cloud 账号或确认自托管环境可用
下一章 → 2_core_concepts.md：深入 Trace、Observation、Session 等核心概念。