写 Agent 的人大概都遇到过同一个场面：本地跑得好好的，一上生产就开始胡说八道。你看着终端里那一屏 tool_call，工具调对了、参数也没错，可最后吐出来的东西就是不对。想复现？日志里只有一句 “assistant finished”。
这时候真正救命的不是更强的模型，是能看见 Agent 中间每一步的「行车记录仪」。Langfuse 就是干这个的开源平台，35.3K 星，最近已经归到 ClickHouse 旗下了。
它到底解决什么问题
Langfuse 官方仓库自我定位是「open source LLM engineering platform」，翻译成人话：给 AI 应用做全链路追踪、评测和 Prompt 管理。核心是 Trace。
一次用户提问进来，Langfuse 会把整条链路建成一棵树：哪次模型调用、花了多少 token、延迟多久、检索阶段捞出了什么、Agent 调了哪个工具、中间每一句 Prompt 的原文，全都躺着不动。你点开就能看到某一次请求的完整时间轴，而不是一句 “请求失败”。
配套的三件套：
- Prompt Management — Prompt 集中管理 + 版本控制，改提示词不用再翻代码。客户端和服务端都有强缓存，改完不用等缓存过期。
- Evaluations — LLM-as-a-judge、代码评测器、用户点踩、人工标注都能塞进同一条流水线。
- Datasets & Playground — 拿固定测试集跑回归，Playground 里试提示词，试好了直接跳回 trace 对比。
架构和上手
Langfuse v4 的架构比想象中重，但边界很清楚：两个应用容器（langfuse/langfuse Web + langfuse/worker）+ PostgreSQL 存事务数据 + ClickHouse 存观测数据 + Redis/Valkey 排队 + S3 存事件附件。API 网关是可选的。
关键在于它自己就跑在 ClickHouse 上——2026 年 1 月 ClickHouse 把 Langfuse 收进了自家体系，v4 号称最多快 165 倍。
本地 5 分钟起步：
git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up
生产环境官方推荐 Kubernetes + Helm，另外备了 AWS/Azure/GCP 的 Terraform 模板。
接入方式从零到满都有：Python/JS SDK 手动埋点，OpenAI SDK 直接换包，LangChain、LlamaIndex、Haystack 传个 callback 就行，还有 LiteLLM、Vercel AI SDK、Mastra。
几句实话
第一，这是开发者工具，不是终端用户的产品。 我上面讲的每一步，前提都是你手里有代码、有日志权限。纯自己搭 Agent 玩，不接生产流量，装它就是给自己增加一台吃内存的机器。
第二，Open core，别看走眼了。 核心是 MIT，但 ee/ 目录下的一部分功能要走 Enterprise License，官方文档里明确写着要 license key。自己小范围用完全没问题，别指望所有高级功能都免费。
第三，它治不了模型的病。 Langfuse 让你看清 Agent 到底错在哪一步——是检索没捞到东西，还是工具参数错了，还是模型自己在胡编。但看清之后怎么改，还是你自己的事。指望接上去就自动变聪明，那是想多了。
同类还有 Arize Phoenix（11.7K 星，Python 写的）、Helicone（6.2K 星，Apache-2.0），偏评测红队的还有 promptfoo（25.7K 星，MIT）。想选型可以对照我之前写的 Agent 平台横向对比 和 Langflow 可视化平台——注意 Langfuse 和 Langflow 就差一个字母，完全是两类东西，别搞混。
放在哪、跑什么规格
它吃资源。ClickHouse 是出了名的内存 hungry，加上 Postgres 和 Redis，一台 2G 内存的小机器跑起来会很难受。想在家里的机器上折腾，可以参考我那篇 全志 A733 玩成 Agent 主机 的折腾记录——不过说句公道话，观测定点更吃的是内存和 SSD 随机写，不是 CPU 核数，配置的时候别照搬 LLM 推理那套思路。
什么时候该上，什么时候别碰
如果你还在本地 print(result) 阶段调 prompt，装它是给自己添麻烦。等你的 Agent 有了固定用户、有了线上报错、开始需要回答「昨天为什么慢了三秒」，再上。工具链这东西，前期全是成本，后期才是命。
一句话：Agent 从 demo 走向能用，中间那道坎就是「出问题时你看得见看不见」。这就是它存在的理由。
by 数码罗记·godsun.pro
本文数据核对于 2026 年 10 月 3 日，star 数与版本号取自 GitHub 实时数据。
