Langfuse：开源 LLM 可观测平台

为什么需要 Langfuse：LLM 应用是黑盒，上线后无法排查与优化

传统监控体系对 LLM 应用基本失效。常规日志只能记录一条最终的 completion（模型补全结果），检索到的上下文、多轮对话状态、prompt 模板、token 消耗这些关键信息全部丢失；APM 工具只能看到普通的 HTTP 请求，无法理解「一次用户请求内部调用了哪几个模型、各自花了多少钱、哪个环节拖慢了响应」。更麻烦的是，LLM 输出具有随机性，同样的问题换个参数就换一个答案，出了问题只能靠用户反馈倒推，复现和定位成本极高。

Langfuse 用两条思路解决这个问题。一是全链路追踪：一次请求从业务函数到模型调用，记录成一颗 Trace 树，每个节点携带模型名、参数、输入输出、token 数与成本，支持全文检索和属性筛选，输入一个 trace_id 就能复现任意一次线上请求的完整上下文。二是把观测与迭代打通：同一份数据既能做故障排查，也能用来跑数据集评估、提示词版本对比、成本聚合分析，让「观测」直接服务于「改进」，而不只是事后翻日志。

与同类工具相比，Langfuse 的气质差异在于「开源中立 + 平台化」：它不像 LangSmith 深绑 LangChain 生态，也不像 Helicone 偏网关接入，而是以 SDK 植入为主、框架无关，并把追踪、评测、提示词管理放在同一套开源代码里，自托管可完全掌控数据。

安装与环境配置：3 步就绪

步骤一：自托管服务端。 官方提供 Docker 镜像与 docker-compose 配置，一条命令即可启动完整服务（UI + API + 数据库）。

浏览器打开 http://localhost:3000，首次访问注册账号即完成部署。默认配置开放注册，生产环境务必按下文关闭。

步骤二：安装 Python SDK 并配置密钥。 在 UI 的「项目设置 → API Keys」中创建一对密钥（public key 与 secret key 配对使用），写入环境变量：

步骤三：验证连通。 运行健康检查脚本，确认数据能写入并在 UI 查询到：

UI 的 Traces 列表出现 healthcheck 记录即接入成功。

git clone https://github.com/langfuse/langfuse.gitcd langfusedocker compose up -d

pip install langfuseexport LANGFUSE_PUBLIC_KEY=pk-lf-xxxxexport LANGFUSE_SECRET_KEY=sk-lf-xxxxexport LANGFUSE_HOST=http://localhost:3000

python -c "from langfuse import Langfuse; c=Langfuse(); t=c.trace(name='healthcheck'); t.update(output='ok'); c.flush(); print('sent')"

快速上手：5 分钟给真实应用埋点

最小可用流程：不修改业务逻辑，用装饰器包裹需要观测的函数，再使用 Langfuse 包装的 OpenAI 客户端发起模型调用，调用链会自动上报为 Trace 树。

操作步骤：

1. 安装 SDK 并配置三个环境变量（见上节）。

2. 在代码中导入 langfuse.decorators.observe 装饰器，为业务函数加上 @observe()。

3. 将 openai 客户端替换为 langfuse.openai.openai——API 用法与原版 SDK 完全一致，只多一层自动埋点。

4. 正常调用函数，数秒后打开 UI 的 Traces 页面，点击最新一条记录查看完整 Trace 树。

运行结果：UI 中生成一条名为 answer 的 Trace，其下挂一个 Generation 节点，展示模型名、完整输入输出、token 数与成本估算。如果 answer 内部还有检索或工具调用，继续用 @observe() 装饰子函数，它们会成为 Trace 树的子节点。

进阶技巧：在函数参数中传入业务 ID（如订单号）作为 trace_id，可将业务数据与观测数据关联；用 @observe(as_type="generation") 直接把节点标记为模型调用，便于按类型筛选。

from langfuse.decorators import observefrom langfuse.openai import openai @observe()def answer(question: str):    client = openai.OpenAI()    resp = client.chat.completions.create(        model="gpt-4o-mini",        messages=[{"role": "user", "content": question}],    )    return resp.choices[0].message.content print(answer("用一句话解释什么是 RAG"))

核心能力详解：4 大支柱

支柱一：追踪与可观测（Trace 树）。 Langfuse 用 6 类观测对象描述一次请求：Trace（完整请求）、Span（耗时子操作，如检索、工具调用）、Generation（模型调用，自动记录 prompt、completion、用量）、Event（零散事件）、Score（评分）、Session（会话）。数据支持全文检索与任意属性筛选，可复现任意一次线上请求的完整上下文；检索质量、模型参数、耗时分布都以结构化字段存储，支持按模型、标签、用户维度切片分析。

支柱二：评测与数据集。 数据集（Dataset）可批量管理「输入-期望输出」样本，支撑回归测试；Score 支持人工打分、代码打分与 LLM-as-judge（用大模型当裁判自动评分）三种方式；评测可以对历史 Trace 重放——把当时的输入重新跑一遍并给出质量分数，从而量化「prompt 改一版是否真的变好了」，而不是凭感觉上线。

支柱三：提示词管理（Prompt Management）。 提示词在平台内版本化管理，支持灰度发布与回滚；应用代码通过 langfuse.get_prompt(name, version) 拉取指定版本并即时生效，提示词迭代无需发版。dev / staging / prod 环境可用不同版本实现隔离，回滚只需在 UI 中操作。

支柱四：用量与成本分析。 按模型、用户、会话、日期聚合 token 消耗与预估成本；成本单价模型内置 OpenAI 等主流厂商，也可自定义。可快速定位「哪个用户、哪个功能在烧钱」，配合阈值告警（token 用量、成本、错误率）防止费用失控。

生产部署与监控：从上线到运维

部署方式一：Docker Compose 生产化。 生产环境建议使用独立 Postgres 15+ 实例（或云数据库），并配置 Redis——v3 起 Redis 是必需组件，作为后台任务队列。首次启动前通过 LANGFUSE_INIT_USER_EMAIL、LANGFUSE_INIT_USER_PASSWORD 等环境变量初始化管理员，并开启 AUTH_DISABLE_SIGNUP 关闭开放注册。多副本场景下 web 与 worker 使用同一 Redis 队列，镜像分开部署。

部署方式二：Kubernetes / 托管云。 官方提供 Helm Chart，支持多副本、HPA（水平自动扩缩）与持久化存储；若启用会话回放（记录网页交互与 LLM 调用），需配置 S3 兼容对象存储（如 MinIO）存放媒体文件。数据合规要求高的团队可完全自托管；无运维人力的团队可直接使用 Langfuse Cloud（SaaS），核心功能与自托管一致。

可观测性： 平台的自我监控分为三层：一是业务告警，基于 token 用量、成本、错误率设置阈值，通过 Webhook / Slack / 邮件推送；二是数据量控制，SDK 初始化时配置 sampling_rate（采样率，按比例随机丢弃上报数据）以控制存储成本，配合数据保留期策略清理过期 trace；三是基础设施运维，定期备份 Postgres 数据库，关注 worker 队列积压与连接数，高峰期横向扩容 web 与 worker 副本。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>v3 起自托管必须配置 Redis，只装 Postgres 会启动失败——升级前先读官方 v3 部署变更说明。</li><li>Python SDK 默认异步批量上报，进程退出前要调用 client.flush()，否则最后一批数据会丢。</li><li>生产环境默认开放注册必须关闭并初始化管理员账号，否则任何访问者都能看到你的观测数据。</li><li>自托管不受消息量收费限制，但 trace 量过大会压垮默认 Postgres——按需开采样、设保留期清理历史数据。</li></ul>

版本迭代

Langfuse 从 2023 年专注 LLM 可观测起步，2024 年初的 2.0 完成架构重写，确立「追踪 + 评分 + 数据集」核心框架；2025 年 3 月的 3.0 带来全新 UI、会话回放，并引入 Redis 队列与对象存储，从「观测工具」走向「平台化」。其迭代节奏约为每两周一个小版本。

AI 应用场景

常见误区

面试题

参考来源

• webpageLangfuse 官网产品介绍、定价与登录入口
• webpageGitHub 仓库源码、Issue 与 Release 记录