Langfuse 完整攻略：从新手到高手

Langfuse 完整使用攻略：开源 LLM 观测平台的深度指南

是什么 / 适合谁

Langfuse 是一款来自德国的开源 LLM 观测平台，专注于帮助开发者追踪、调试和优化大语言模型应用。它本质上是一个“监控+调试”工具箱，让你能看到模型在真实场景中的每一次调用、输入输出、延迟、成本以及异常行为。

核心能力：

• 追踪（Tracing）：记录每次 LLM 调用的完整链路，包括 Prompt、Completion、Token 消耗、耗时等。
• 评估（Evaluation）：支持人工打分或自动评估（如基于 GPT 的评分），量化模型输出质量。
• 成本与性能监控：实时统计 API 调用次数、Token 用量、费用、响应时间。
• 数据集与测试：可创建测试集，批量重放历史请求，对比不同模型或 Prompt 的效果。

适合谁：

• AI 应用开发者：尤其是用 LangChain、LlamaIndex 或直接调用 OpenAI API 构建产品的团队。
• Prompt 工程师：需要反复调试 Prompt 并量化效果的人。
• 小型创业团队：希望低成本自建观测系统，避免被商业平台锁定。
• 技术管理者：想了解 LLM 应用的运行状况、成本分布和错误率。

不适合谁：

• 纯业务用户：不懂代码、不想接触命令行和 Docker 的运营或产品人员。
• 追求开箱即用：需要中文界面、一键部署、无代码配置的用户。

---

阶段学习路径

第 1 天：快速上手与基础部署

目标：用 Docker 自托管 Langfuse，并完成一次最简单的 LLM 调用追踪。

1. 环境准备：确保本地有 Docker 和 Docker Compose（Windows/Mac/Linux 均可）。无需 GPU，普通服务器即可。
2. 一键部署：
   • 克隆官方仓库：git clone https://github.com/langfuse/langfuse.git
   • 进入目录，运行 docker compose up -d。等待镜像拉取完成（约 2-3 分钟）。
   • 访问 http://localhost:3000，注册第一个管理员账号。
3. 创建第一个项目：在 UI 中新建项目，系统会自动生成一个 API Key 和 Secret Key。
4. 集成 SDK：以 Python 为例，安装 pip install langfuse。在代码中初始化：

   from langfuse import Langfuse
   langfuse = Langfuse(public_key="你的公钥", secret_key="你的私钥", host="http://localhost:3000")
   

5. 追踪一次调用：调用 OpenAI 的 Chat Completion，并包裹在 Langfuse 的 trace 和 generation 中：

   trace = langfuse.trace(name="my-first-trace")
   generation = trace.generation(name="openai-call", model="gpt-3.5-turbo")
   # 你的实际 LLM 调用代码
   generation.end(output="Hello, world!")
   trace.end()
   

6. 查看仪表盘：刷新 Langfuse 页面，你会在“Traces”中看到刚才的记录，包含输入、输出、Token 数、耗时。

第 1 天小结：你已经拥有一个自托管的观测平台，并成功记录了第一条追踪。此时可探索 UI 中的“Scores”和“Cost”模块，了解基本数据。

第 1 周：深度集成与自动化评估

目标：将 Langfuse 嵌入真实项目，实现自动评估和错误告警。

1. 集成 LangChain：Langfuse 提供 LangChain 回调处理器，只需一行代码：

   from langfuse.callback import CallbackHandler
   handler = CallbackHandler(public_key="...", secret_key="...", host="http://localhost:3000")
   # 在 LangChain 的 Agent 或 Chain 中传入 callbacks=[handler]
   

   之后每次 Chain 调用都会自动记录完整链路，包括工具调用、中间步骤。

2. 设置自动评估：在 UI 的“Evaluation”中创建“Auto Evaluation”，选择“LLM as Judge”模板。配置一个 GPT-4 模型来打分（比如评估回答的“有帮助性”）。系统会自动对历史追踪进行评分。

3. 配置错误监控：在“Alerts”中设置规则，例如“当错误率超过 5% 时发送邮件通知”。Langfuse 会检测 HTTP 状态码或异常。

4. 创建测试数据集：将生产环境中的真实用户请求（如常见问题）导出为数据集。在“Datasets”中创建，然后批量重放，对比不同 Prompt 或模型版本的效果。

第 1 周小结：你已能监控生产环境的 LLM 调用，并自动评估质量。此时可尝试修改 Prompt 后重放数据集，观察评分变化。

进阶：自定义插件与性能优化

目标：编写自定义评估函数、优化存储、集成 CI/CD。

1. 自定义评估：Langfuse 支持 Python 脚本作为评估器。创建一个函数，接收 trace 数据，返回分数：

   def my_evaluator(trace):
       if "错误" in trace.output:
           return 0
       return 1
   

   在 UI 中注册该评估器，即可对实时追踪打分。

2. 数据保留策略：默认存储所有数据，长期运行会占用磁盘。在 docker-compose.yml 中配置环境变量 LANGFUSE_DATA_RETENTION_DAYS=30，自动清理超过 30 天的追踪。

3. 集成 CI/CD：在代码仓库中增加测试步骤，使用 Langfuse 的 Python SDK 在 CI 中运行测试集，对比新版本 Prompt 的评估分数是否下降。若下降则阻断合并。

4. 多环境隔离：用不同项目区分开发、测试、生产环境。每个环境使用独立的 API Key，避免数据混淆。

---

优势

• 完全开源：代码可审计，无数据泄露风险，可定制功能。
• 自托管：数据留在自己的服务器，不依赖第三方服务。
• LangChain 深度集成：原生回调处理器，几行代码即可接入。
• 成本透明：实时计算每次调用的 Token 费用，便于预算管理。
• 灵活评估：支持人工、自动、自定义三种评估方式，适合不同场景。
• 轻量部署：Docker 一键启动，资源占用低（2 核 4G 即可运行）。

---

短板

• 面向开发者：UI 和文档均为英文，配置需要写代码，非技术人员上手困难。
• 无中文界面：国内团队使用需适应英文环境。
• 高级功能需编程：自定义评估、数据导出等需要 Python 基础。
• 社区规模有限：相比 Datadog 等商业产品，插件和教程较少。
• 存储扩展性：默认使用 SQLite，高并发场景需切换为 PostgreSQL（需手动配置）。

---

价格规划

Langfuse 本身完全免费（MIT 协议），无任何功能限制或收费计划。你需要承担的成本仅为服务器费用：

• 最低配置：2 核 CPU、4GB 内存、20GB 磁盘的云服务器（约 50-100 元/月）。
• 推荐配置：4 核、8GB 内存、50GB SSD（约 200 元/月），可支撑中等规模团队。
• 无隐藏费用：无按量计费、无用户数限制、无高级功能付费。

注意：如果调用外部 LLM（如 OpenAI），API 费用需单独计算，Langfuse 不涉及这部分。

---

不合适怎么办

如果 Langfuse 不适合你的场景，可以考虑以下替代方案：

• 需要中文界面、零代码：尝试商业平台如 Helicone（有中文社区版）或 Arize AI（部分中文支持）。
• 需要更丰富的可视化：Weights & Biases 的 LLM 追踪功能更强大，但需付费。
• 只想监控成本：直接用 OpenAI 的 Usage Dashboard，或写脚本解析 API 日志。
• 团队无技术能力：雇佣一名兼职 DevOps 或使用托管版 Langfuse（官方提供 SaaS，但需海外服务器）。

最终建议：如果你的团队有 1-2 名开发者，且愿意花半天时间部署和集成，Langfuse 是目前性价比最高的自托管观测方案。如果完全不想碰代码，建议直接使用商业 SaaS 产品。