Langfuse：看清线上 AI 聊天机器人在做什么

目录

• AI 机器人的三种无声故障
• 什么是 LLM 可观测性
• Langfuse 管哪些事

  • 费用怎么算
• 十分钟拿到第一条 trace

  • 如果数据要放在自己的服务器上
• 什么时候值得用
• 做出来只是一半

周一，客户来信：“机器人跟一位顾客说包邮。其实不包邮。”你打开后台，对话看得到。看不到的，是它为什么会这么答。

当时生效的是哪版提示词？检索塞进来的是哪些文档？是模型的问题，是上下文的问题，还是有人周五改完就发出去了？缺了这些，所谓修复就是猜。

给公司做聊天机器人和 WhatsApp 流程时，这一幕会反复出现。写 AI 的文章几乎都在教你怎么把机器人做出来。很少有人教：真客户开始跟它说话之后，怎么看清它在干什么。如果这条流程你还在搭，上一篇是如何把流程变成聊天机器人。这篇讲的是上线之后。

AI 机器人的三种无声故障

传统机器人坏起来很响：崩溃、报错，总会有人看见。AI 机器人坏起来很安静，因为它总会吐出一句回答。生产里最常见的，是这三种：

1. 听着像对的，其实是错的。 模型可以非常笃定地编出一个价格、一条政策或一张时间表。没人发觉，直到客户来投诉。
2. 费用往上跳，却看不出原因。 对话历史不限长度地涨，或者智能体内部打转，API 账单就能翻倍。发票月底才到，那时已经没什么可砍的了。
3. 提示词变差了，没人说得清。 你改提示词，想修好一个例子，结果另外三个坏了。没有可以对照的版本，最后是用户来告诉你。

三件事，原因是同一个。问题不只在模型。问题是你看不见里面发生了什么。

什么是 LLM 可观测性

可以把它想成飞机上的黑匣子。它阻止不了事故，但能让你一步一步还原当时发生了什么。LLM 可观测性对机器人做的就是这件事：把每次对话的每一步存下来，方便事后回看。

每次交互存成一条 trace。“包邮吗？”这样一条问题，看起来会是这样：

• Trace： 客户发来的 WhatsApp 消息（1.8 秒 · 0.004 美元）
  • 知识库检索：它找到的文档
  • 模型调用：完整的提示词和它的版本、回复，以及 token
  • 发给用户的那条回复

有了这些，包邮这件事几分钟就能查清。你会看到检索带回一条已经过期的促销，模型却把它当成仍有效。你不用再猜。你知道该改哪里。

如果你是从营销过来的，这就是对话的分析：谁问了什么、花了多少钱、效果怎么样。

Langfuse 管哪些事

Langfuse 是一个采用 MIT 许可证的开源平台，用来追踪、评估并改进那些调用语言模型的应用。上面每一种故障，都有一项能力对着它。

能力	它做什么	对着哪种故障
追踪	记下每次对话的每一步，带上成本和延迟	“不知道它为什么这么答”
提示词管理	给提示词做版本，并能退回较早的一版	“提示词变差了，我不知道是什么时候”
评估	用另一个模型、用规则，或由人来复核，给回复打分	“听着对，其实是错的”
实验	上线前，拿真实案例去测新的提示词或新模型	“修好一个，弄坏了三个”
仪表盘	成本、延迟和质量随时间怎么变，并可告警	“账单翻倍了”

它能接上 OpenAI、Anthropic、Google、LangChain、Vercel AI SDK、CrewAI、n8n，以及任何支持 OpenTelemetry 的技术栈。定价页上列着 Canva、Khan Academy、Hugging Face 这些团队。

2026 年 1 月 16 日，ClickHouse 收购了 Langfuse。项目继续开源，也可以自己托管，许可证仍是原来的 MIT。公告里，ClickHouse 称该项目在 2025 年底的 GitHub 星标超过 20,000。这次收购不改变本指南：云端的端点照旧，埋点代码接云端还是接你自己的服务器，写法一样。

费用怎么算

方案	价格	包含的用量	保留时间
Hobby	免费	每月 50,000 个单位，2 个用户	30 天
Core	29 美元/月	每月 100,000 个单位，用户不限	90 天
Pro	199 美元/月	每月 100,000 个单位，用户不限	3 年
自托管	免费（服务器自付）	平台不设上限	由你设定

价格来自官方页面，核对于 2026 年 10 月。Hobby 没有额外单位：额度一用完，这个方案就到头。Core 和 Pro 包含前 100,000 个单位，超出部分按档计费，从每 100,000 个单位 8 美元起。一个单位就是一个追踪数据点：这条 trace、其中的每一步，以及每一次评估。

拿来试，Hobby 就够。创建项目时选定区域。云端把数据放在美国、欧盟或日本，基础 URL 会随这个选择改变。

十分钟拿到第一条 trace

最快上手的，是一个已经在用 OpenAI 的 Python 机器人。如果你用的是 n8n、LangChain 或其他工具，思路一样，细节在集成指南里。

1. 创建账号。 打开 cloud.langfuse.com，创建项目，把公钥和私钥都复制下来。
2. 安装软件包：

pip install langfuse openai

3. 设置环境变量。 下面这条是欧盟的 URL。如果选了别的区域，改用 https://us.cloud.langfuse.com 或 https://jp.cloud.langfuse.com。

LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_BASE_URL="https://cloud.langfuse.com"
OPENAI_API_KEY="sk-..."

4. 换掉 import，并把同一次对话归到一起。 Langfuse 自带一个可直接替换的 OpenAI 客户端，调用会被记下来。propagate_attributes 标上用户和会话，界面才能把一次聊天的每一轮归在一组。脚本如果马上退出，要在进程结束前用 flush() 把数据送出去。

from langfuse import observe, propagate_attributes, get_client
from langfuse.openai import openai  # antes: import openai

@observe()
def responder(mensaje: str, usuario_id: str, conversacion_id: str):
    with propagate_attributes(user_id=usuario_id, session_id=conversacion_id):
        respuesta = openai.chat.completions.create(
            name="respuesta-bot",
            model="gpt-4o-mini",
            messages=[
                {"role": "system", "content": "Eres el asistente de una tienda online."},
                {"role": "user", "content": mensaje},
            ],
        )
        return respuesta.choices[0].message.content

print(responder("¿El envío es gratis?", "cliente-123", "chat-456"))
get_client().flush()

5. 打开面板。 在 Tracing 里能看到这条 trace：提示词、回复、token、成本和耗时。有了 session_id，就能把这位用户的整段对话串起来看。

如果数据要放在自己的服务器上

可以用 Docker 自己托管。在本地，克隆仓库，检查 docker-compose.yml 里标成 CHANGEME 的密钥，再把容器拉起来：

git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up

文档写着，Web 容器大约 2 到 3 分钟后会在 http://localhost:3000 就绪。没有预置的管理员账号：第一次打开就是注册。同一份指南对生产机器的建议是至少 4 个 CPU 核心和 16 GB 内存，并提醒 Compose 做不到高可用。刚起步的小公司，免费的云方案通常比单独备这台服务器更划算。

什么时候值得用

从机器人开始跟真实客户说话那一刻起，Langfuse 就值得用。在那之前，你多半还不需要。

适合这些情况：

• 机器人在服务客户，或经手价格、订单、客服。
• 你给别的公司做机器人，出了问题得讲得清到底发生了什么。
• 你每个月在 AI 的 API 上要花掉不止几美元，而且想知道花在哪。
• 提示词经常改，或者改的人不止一个。

现在还用不着，如果：

• 还只是自己用的原型，或周末拿来试试。
• 机器人所在的平台是封闭的，不让你接外部工具。那就先看平台自己提供的日志。

其他选择。 LangSmith 和 Braintrust 覆盖的范围差不多。和 Langfuse 实际的差别在于：它是开源的，数据可以拿到你自己的服务器上。

做出来只是一半

一个 AI 机器人，一个下午就能送上线。能不能知道它跑得好不好，才把一次实验和一个客户敢信任的产品分开。

Langfuse 不会让模型更聪明。它做的更有用：让你看见正在发生什么，于是改提示词、改文档、看成本，眼前都有证据。入门那一档是免费的。等来了第一通客户投诉，再盲飞就没有借口了。