Langfuse：AI 应用的可观测性利器

让大模型应用从"黑盒"走向"白盒"，从"能用"走向"好用"

📖 摘要

大模型应用开发中，你是不是经常遇到这些问题：AI 回答莫名其妙，却不知道哪里出了错；Token 消耗像流水，成本根本算不清；提示词改了好几版，效果好坏全靠猜。Langfuse 正是为了解决这些痛点而生的开源工具。

本文将用最通俗易懂的方式，带你全面了解 Langfuse 的核心功能（追踪、提示词管理、评估），并解答新手最常见的几个疑问（密钥的作用、云服务和自托管的区别、计费问题等）。无论你是 AI 应用开发者、产品经理还是技术决策者，这篇文章都能帮你快速判断 Langfuse 是否适合你的项目。

从"黑盒"到"白盒"：AI 应用面临的独特挑战

如果你正在构建一个稍微复杂一点的大模型应用，大概率经历过这样的场景：

同一个提示词，AI 有时候回答精彩绝伦，有时候却莫名其妙
用户反馈"AI 给出了奇怪的回答"，你完全不知道是哪个环节出了问题
成本在不知不觉中攀升，你根本说不清哪一部分在疯狂消耗 Token
信心满满地上线了一个新提示词或新模型，接下来的 48 小时都在祈祷别出岔子

这并非你的代码写得不够好，而是大模型应用的本质决定的。

传统软件是"确定性"的：输入 2+2，输出永远是 4。出了问题，顺着调用栈很快就能定位到 bug。

大模型应用是"概率性"的：同一个输入，每次输出都可能不一样。它的工作流往往是多步骤的------检索、调用工具、Agent 决策、路由、安全护栏......任何一个环节出了差错，都可能导致最终回答翻车。更麻烦的是，回答质量本身是"主观"的------"这个回答很糟糕"很难用一个简单的布尔值来表达。成本如果不逐层追踪 Token 消耗，就永远是一笔糊涂账。

Langfuse 就是为解决这一系列问题而生的。

Langfuse 是什么？

Langfuse 是一个开源的大语言模型（LLM）工程平台，它为 AI 应用提供从原型到生产全流程的可见性和控制力。

简单来说，Langfuse 就像一个为 AI 应用量身定制的 "全透明驾驶舱"------它能让你看清每一次请求的完整旅程、管理好每一个提示词的版本、量化每一次改动的效果。

截至 2025 年，已有 2300 多家企业 在使用 Langfuse，每月处理超过 100 亿次观测数据 ，超过 10 万名工程师 正在基于它构建 AI 应用。它的 GitHub 仓库已经获得了超过 1.7 万颗星 ，是 LLM 可观测性领域最受欢迎的开源项目之一。2026 年 1 月，ClickHouse 收购了 Langfuse，这意味着 Langfuse 的分析引擎与 ClickHouse 数据库现在属于同一家公司，两者之间的集成深度和优化程度进一步提升。

🛠️ 五大核心能力

Langfuse 将追踪、提示词管理、评估、实验和环境管理整合到一个平台中，覆盖了从原型开发到生产上线的完整生命周期。

1. 全链路追踪（Tracing）------ 看清每一次请求的完整旅程

这是 Langfuse 最核心、最基础的功能。

当用户向你的 AI 应用发起一次请求时，Langfuse 会像一台黑匣子记录仪一样，记录下整个过程的每一个细节：

用户输入了什么？
系统调用了哪个模型？
模型返回了什么回答？
中间有没有调用外部工具？检索了哪些知识库？
每一步花了多长时间？
消耗了多少 Token？产生了多少成本？

在 Langfuse 的可视化界面上，每一次请求都以一条 Trace（追踪链路） 的形式呈现。你可以像看 X 光片 一样，清晰地看到整个执行过程的分层结构------哪一步慢了、哪一步出错了、哪一步最烧钱，一目了然。当 AI 翻车时，你不再需要靠猜，而是可以直接从追踪图上精准定位问题出在哪一步。

Langfuse 还提供了内置的指标看板和自定义仪表盘，你可以追踪延迟、Token 用量、成本、错误率以及自定义指标。你甚至可以创建数据透视表和直方图，按模型、端点或功能维度进行多维度分析。

2. 提示词管理（Prompt Management）------ 像管理代码一样管理提示词

提示词是 AI 应用的灵魂。但在实际开发中，提示词往往是硬编码在代码里的------改一行提示词就要重新部署一次应用，产品经理想优化一下也无从下手。

Langfuse 的提示词管理功能，相当于给提示词建了一个 "版本控制系统"。它的核心价值在于：

版本控制：每次修改自动生成一个新的版本号，可以随时回滚到任意历史版本
标签部署 ：你可以给特定版本打上 production、staging 等标签，不同环境使用不同版本的提示词，无需修改任何代码
解耦部署：更新提示词不再需要重新部署应用------产品经理或运营同学可以直接在 Langfuse 的控制台上修改并发布
效果追踪：每个提示词版本都可以关联到追踪数据，Langfuse 会自动聚合该版本的延迟、成本和评估指标
提示词复用：你可以在一个提示词中引用另一个提示词，实现模块化的提示词管理

对于使用 LangChain 的开发者，Langfuse 的提示词管理可以无缝集成到 LangChain 的提示词模板中。

3. 评估与实验（Evaluation）------ 用数据说话，而不是凭感觉

"效果好像变好了"------这大概是 AI 应用开发中最不可靠的一句话。Langfuse 提供了多种评估手段，让你的优化有据可查：

LLM-as-a-Judge（AI 评委）：让更强大的 AI 模型（如 GPT-4）自动为你的回答打分。你可以使用内置的评估模板（如幻觉检测、毒性检测、相关性、正确性等），也可以创建自定义的评估标准。评估可以异步运行在 Langfuse 的基础设施上，不影响主流程
专业评估库集成 ：Langfuse 的 Python SDK 支持与多种专业评估库集成，包括 RAGAS （专为 RAG 系统设计）、OpenAI Evals 、LangChain Evaluators 和 UpTrain 等
用户反馈收集：收集真实用户的点赞或点踩
人工标注：在 Langfuse UI 中手动对观测数据进行标注和评分

你可以将生产环境中收集的真实交互数据整理成评估数据集，然后在新版本的提示词或模型上运行实验，对比不同版本的各项指标。每一次改动，都有数据支撑。

4. 环境隔离与协作（Environments & Collaboration）

Langfuse 支持 环境（Environments） 功能，允许你将生产环境和开发环境的追踪数据分离开来。你可以在同一个项目中用 production、staging、development 等标签来区分不同环境的流量，分别监控和分析。

团队协作方面，Langfuse 提供了丰富的协作功能------团队成员可以共同查看追踪、管理提示词、标注数据。Langfuse 还支持 实时告警（通过 Webhook 和 Slack），当提示词发生变化或用量超出阈值时，团队能第一时间收到通知。

5. Playground ------ 快速试验和对比

Langfuse 内置了一个 LLM Playground（游乐场） ，你可以在其中快速测试不同的模型、提示词和参数组合。Playground 支持 并排对比（Side-by-Side Comparison），让你同时运行多个版本的提示词或模型，直观地对比它们的输出质量和成本。这对于快速迭代和验证想法非常有帮助。

📍 Langfuse 在技术栈中的定位：别再搞混了！

刚接触 AI 应用开发的朋友，看到 LangChain 、LangGraph 和 Langfuse 这三个名字时，很容易搞混------毕竟都带"Lang"，而且经常在同一个项目里出现。但其实它们的定位完全不同，各司其职。

工具	定位	一句话理解
LangChain	LLM 组件、链式调用库	工具箱------调用模型的"扳手和螺丝刀"
LangGraph	搭建 Agent 流程图、状态机	业务代码框架------定义 AI 的工作流程
Langfuse	监控、日志、追踪 Agent 运行状态	观测平台------给整个系统装上"仪表盘"

注意：LangChain 和 LangGraph 都出自同一家公司（LangChain Inc.），而 Langfuse 是一个完全独立、由不同团队开发的开源项目。

打个比方就懂了

想象你在开一家智能咖啡店（这就是你的 AI 应用）：

LangChain 是你的咖啡机、研磨机、制冰机------各种工具，让你能完成"做一杯咖啡"这件事。它负责处理"怎么调用大模型""怎么格式化输出"这些具体操作。
LangGraph 是你的工作流程图------"顾客点单 → 研磨豆子 → 萃取咖啡 → 加配料 → 出杯"。它定义了整个业务流程的走向，包括判断、循环、条件分支（比如"如果顾客要冰的，就加冰"）。
Langfuse 是你店里的监控摄像头 + 收银系统 + 顾客评价箱------它记录每一单的详细过程（谁点的？用了多久？成本多少？），告诉你哪个环节慢了、哪杯咖啡做坏了、今天的成本超了多少。

它们的关系：协作而非替代

这三者不是竞争关系，而是协作关系。一个典型的 AI 应用可能同时使用三者：

text

复制代码

用户请求
    ↓
LangGraph —— 控制整个 Agent 的执行流程（先检索、再思考、再调用工具）
    ↓
LangChain —— 执行具体的 LLM 调用（用 ChatOpenAI 发送提示词、解析输出）
    ↓
Langfuse —— 全程记录每一步的耗时、Token、输入输出，生成可视化的追踪链路

你用 LangGraph 和 LangChain 把应用跑起来 ，然后用 Langfuse 看清楚它跑得怎么样。LangGraph 和 LangChain 关心的是"功能能不能实现"，Langfuse 关心的是"效果好不好、成本高不高、哪里出了问题"。

现实中的常见组合

在实际项目里，这三个工具的搭配方式非常灵活：

只用 LangChain + Langfuse：如果应用流程比较简单（比如一个问答机器人），不需要复杂的 Agent 状态管理，LangChain 就足够了，加上 Langfuse 做观测
LangGraph + Langfuse（不用 LangChain）：LangGraph 本身不强制依赖 LangChain，你可以用原生的 OpenAI SDK 来实现具体调用，但仍然可以用 LangGraph 来编排复杂的多步 Agent 逻辑
三者全用：这是最完整的组合，适合复杂的企业级 Agent 应用

一句话总结：LangChain 是"怎么做"的工具箱，LangGraph 是"做什么流程"的设计图，Langfuse 是"做得怎么样"的评价表。

🏗️ 架构与部署

Langfuse 的架构设计充分考虑了生产环境的高可用性和可扩展性。

组件构成

Langfuse 由以下几个核心组件构成：

组件	作用
Langfuse Web	主 Web 应用，提供 UI 界面和 API 服务
Langfuse Worker	后台工作进程，异步处理事件
PostgreSQL	主数据库，存储事务性数据
ClickHouse	高性能列式数据库，存储追踪、观测和评分数据
Redis / Valkey	缓存和消息队列
S3 / 对象存储	持久化存储所有 incoming 事件、多模态输入和大规模导出数据

Langfuse 自托管版本与 Langfuse Cloud 运行的是完全相同的代码库。Langfuse 团队自身就是用这套架构服务了数千个团队，保持着 99.9% 的可用性。

生产级数据管道

Langfuse 的生产级数据管道设计非常考究：所有追踪数据由 Web 容器批量接收后立即写入 S3，仅在 Redis 中保留一个引用用于排队。随后 Worker 从 S3 中取出数据，批量导入 ClickHouse。这种设计确保了即使在高并发场景下，系统也能稳定运行，不会因为瞬时流量高峰而丢失数据。

部署选项

Langfuse 支持多种部署方式：

Langfuse Cloud：全托管版本，零运维，开箱即用
Docker Compose：适合本地测试和低负载场景
Kubernetes / Helm：适合生产环境的高可用部署
Terraform：支持 AWS、Azure、GCP 等云平台的基础设施即代码部署

自托管的 Langfuse 可以部署在 VPC 内部甚至完全隔离的环境中，互联网访问是可选的------这对于有严格数据合规要求的企业来说至关重要。

🔌 生态与集成：不绑定任何框架

Langfuse 的一个重要设计理念是 "框架无关"（framework-agnostic） 。它不会强迫你使用某个特定的框架或库。

原生集成

Langfuse 提供了丰富的原生集成，覆盖了主流的 AI 开发框架：

LangChain & LangGraph：通过 CallbackHandler 自动追踪
LlamaIndex：通过 LangfuseCallbackHandler 无缝追踪
OpenAI SDK：通过 drop-in replacement 实现零代码侵入的追踪
Vercel AI SDK：官方支持
LiteLLM Proxy：捕获经过代理的所有 LLM 调用
Ollama：支持本地模型的追踪
Amazon Bedrock、Hugging Face、Anthropic 等

OpenTelemetry 标准

除了原生集成，Langfuse 还是一个 OpenTelemetry 后端（OTLP 端点） 。任何能够导出 OpenTelemetry traces 的应用、框架或采集器，都可以将数据发送到 Langfuse。这意味着：

你可以使用 Go、Java、C#、Ruby 等任何支持 OpenTelemetry 的语言
你可以集成 Semantic Kernel 等框架
你的数据不会被锁定在任何特定平台------OpenTelemetry 是 CNCF 旗下的行业标准

Langfuse 不会锁定你的数据。

⚖️ 同类工具对比：Langfuse vs LangSmith

在 LLM 可观测性领域，Langfuse 最常被拿来比较的是 LangSmith（由 LangChain Inc. 开发）。两者的核心差异如下：

对比维度	Langfuse	LangSmith
开源	✅ MIT 许可，代码完全开放	❌ 专有 SaaS，仅 SDK 开源
自托管	✅ 一等公民，功能与云版完全一致	⚠️ 仅企业版支持，需商业合同
框架绑定	框架无关，基于 OpenTelemetry	LangChain / LangGraph 原生
数据主权	高：可完全离线运行在自有 VPC	中：SaaS 默认存于 LangChain 云
存储引擎	ClickHouse（开源列式数据库）	SmithDB（专有数据库）
免费额度	每月 5 万观测单位	每月 5 千条追踪

选择建议：如果你优先考虑开源、数据可控、框架灵活性，或者不想被特定厂商锁定，Langfuse 是更合适的选择。如果你深度使用 LangChain/LangGraph 且不介意使用闭源 SaaS，LangSmith 会提供更原生的体验。

🔑 常见新手疑问

Q1: 为什么需要密钥？

就像你需要账号密码登录邮箱一样，Langfuse 使用 API 密钥来确认"你是谁"以及"你能做什么"。Langfuse 使用一对密钥------公钥（Public Key） 作为"用户名"，私钥（Secret Key） 作为"密码"。私钥需要严格保密，建议通过环境变量配置，绝不能硬编码在代码里或提交到公开仓库。

Q2: 自托管和使用云端有什么区别？

对比项	☁️ Langfuse Cloud（云端）	🏠 自托管（Self-hosted）
核心理念	开箱即用，省心省力	数据主权与完全控制
成本	按量付费，有免费额度	软件免费，但需承担服务器和数据库费用
运维负担	零运维	需自行部署、监控、备份、升级
数据存储	存在 Langfuse 的云上	完全留在你的基础设施内
技术门槛	极低	较高，需要 DevOps 能力
推荐场景	个人开发者、初创团队快速验证	有严格数据合规要求的企业

选择建议：个人开发者和初创团队可以优先选择云端，快速验证想法。有严格数据合规要求的企业，或者使用量极大希望控制成本的组织，可以考虑自托管。

值得一提的是，Langfuse 云端和自托管运行的是完全相同的代码库，你可以随时在两者之间迁移，不会被锁定。

Q3: 计费是美元，能换成人民币吗？

Langfuse Cloud 目前不支持将默认的美元计费直接切换为人民币。如果预算紧张，可以设置消费预警------在账单页面以美元设置阈值，超限时会收到邮件通知。自托管用户则可以在项目级别自定义模型价格，实现成本核算的"本地化"。

💎 总结

Langfuse 是一个为了让 AI 应用从 "能用" 变成 "好用、可靠、可控" 而生的工程化平台。它通过 追踪（Tracing） 、提示词管理（Prompt Management） 和 评估（Evaluation） 三大核心功能，配合环境隔离、Playground、自定义仪表盘等辅助能力，把 AI 应用的"黑盒"变成了"白盒"。

无论你是 AI 应用开发者、产品经理还是技术决策者，Langfuse 都值得你花时间去了解。你可以访问它的官网，从它的在线演示开始体验，或者查看它的 GitHub 仓库。

如果你觉得这篇文章有帮助，欢迎点赞、收藏、转发。想深入了解的话，可以去 Langfuse 的 GitHub 仓库点个 Star，或者体验一下它的在线演示。