上个月排查一个生产环境的Agent问题时，我盯着LangChain终端日志看了快三个小时，愣是没定位到是哪一步的Prompt把模型带偏了。真正让我破防的是第二天找到原因后，发现这个问题在日志里其实出现过三次，只是被淹没在几十条RunnableSequence输出里，谁也没注意到。从那天起，我给所有新项目定了一条规矩：不接LangFuse就准上线，这跟"不写日志不准上生产"一个级别。
这篇东西我打算把LangFuse+LangChain这套组合从埋点到成本监控完整过一遍，包括怎么自建服务、怎么把trace里的token消耗换算成真金白银、以及我在真实项目里踩过的几个比较影响效率的坑。不管你是刚摸到LangChain入门、在纠结LangGraph和LangChain该选哪个，还是已经在生产环境里跑Agent、正为排查问题和成本失控头疼，这篇应该都能给你一些能直接抄作业的东西。
1. 为什么调试AI应用比调试普通Web服务更痛苦
1.1 一次"找不到原因"的线上事故
先交代一下那个让我印象极深的线上问题。我们的客服Agent会在某些问法下，把文档里一段毫不相关的定价条款当作答案返回给用户。从传统后端视角看，这个请求的HTTP状态码是200，延迟正常，日志里也没有异常堆栈，数据库查询也都成功。可业务方就是反馈"答非所问"。
我当时的排查手段非常原始：在chain执行链路里到处print中间结果，把每轮Prompt拼出来手动粘到Playground里试。但问题是我没法复现线上那一次调用的真实输入。LangChain打印的verbose日志默认只给到Runnable的类名和参数，真正模型收到的完整Prompt长什么样，不借助额外工具根本看不全。更别说Agent场景下还有工具调用、多轮重试，一次用户请求背后可能藏着5到6次真正的模型请求，它们的输入输出、token消耗、耗时，全部散落在不同日志行里，根本拼不回去。
1.2 LLM应用可观测的三个特有难题
如果你也做过传统后端开发，就会发现可观测性在LLM应用里突然变难了，原因主要是下面这三点。
第一，执行路径不确定。传统Web应用的一次请求，代码执行的路径基本是确定的，出了错有调用栈、有异常类型，排错思路很清晰。但LLM应用里，模型下一步会调用哪个工具、会不会继续追问、在哪个节点突然开始胡说，全都不是代码写死的，是模型自己决定的。这导致同样的用户输入，每次实际走的链路可能都不一样，光靠静态代码分析看不出问题。
第二，模型的"输入"和"输出"不是普通参数。对模型来说，输入不只是用户那几十个字，而是完整的Prompt模板加上检索回来的上下文、历史会话、工具描述，这些内容本身可能就是几千甚至上万token。而输出呢，又是非确定性的。同一个Prompt同一套参数，跑两次结果就是可能不一样。也就是说，即使你辛辛苦苦复现了日志，也没法保证能复现问题本身。
第三，成本是随着一次调用动态产生的。每条trace消耗了多少输入token、多少输出token，这直接决定你月底账单。但传统日志系统里，token用量如果不去专门打印，根本不会出现在任何一条日志里。等账单出来发现超预算，再想回溯是哪类请求烧的钱，几乎不可能。
所以这个东西光靠加日志是救不回来的，需要一种把"一次完整请求"当成一个聚合单元来记录、关联、展示的系统。这也是LangFuse这类工具存在的价值。
2. LangFuse的核心设计：从Trace到Observation的一棵树
2.1 核心数据模型：Trace、Observation、Session、User
LangFuse的数据模型其实不复杂，核心就一张树状结构。最顶层叫Trace，代表端到端一次请求，比如用户问了一句"帮我总结这份合同的风险条款"，从他发出请求到他拿到完整回答，整个过程算一条trace。
往下拆，这条trace里可能有若干个Observation。Observation是树上的节点，又分四种类型：SPAN、GENERATION、EVENT和LOG。SPAN是内部操作单元，比如"调用向量数据库检索"或者"执行工具tavily_search"；GENERATION特指一次模型调用，也就是真正发生token计费的地方；EVENT和LOG是辅助的记录节点，用于标记异常、错误或状态变化。每个Observation都有自己的parent节点，一层层挂在trace下面，最终形成一棵完整的调用树。
另外两个维度是Session和User。Session表示跨多次trace的连续会话，对应真实用户的一次"客观会话"，比如App里的一次对话窗口；User则标记这个请求归属于哪个用户。这两层信息不是摆设，后面做用户级成本统计全靠它们兜底。
2.2 LangChain、LangGraph与LangFuse分别扮演什么角色
这里我得多说几句，因为很多刚上手的同学很容易把这三者搞混。LangChain的核心价值是提供了Chain以及一系列与模型、向量库、工具交互的组件，让你能够"编排"一次LLM调用流程；LangGraph则是LangChain团队在后期推出的更强编排引擎，它把流程建模成一张有状态的图：节点是计算，边是流转条件，不同节点共享一个可读写状态，这使得它处理Agent这类需要循环、分支、多Agent协作的场景比LangChain跑chain顺手得多。用大白话说，LangChain更像一条流水线，LangGraph更像一张有回路的地图。
那LangFuse在里面的位置就清晰了，它既不负责调用模型，也不负责编排流程，它只做一件事：把一条流水线或者一张地图在执行过程中发生的所有事件，按调用树的形式记录下来，再送到一个可以做检索分析、打标评估、成本统计的网页控制台里。三者不是替代关系，LangFuse一个通用LLM可观测平台，LangChain、LangGraph以及任何你手写的LLM代码，都可以是它的数据源。
2.3 为什么不直接打日志到ES
可能有人会问，我写一个日志中间件把prompt、响应、usage全打到ES，再用Kibana做面板，不也一样？这个方案不是完全不能用，我在小项目里也这么干过，但有几件事你做起来非常费劲。
一是调用链的还原。ES里存的是一条条单独的日志，你需要自己设计trace_id、parent_id，自己维护跨进程的上下文传递，然后在查询时一层层递归拼树。二是类型语义的丢失。ES里一条日志是"一个JSON对象"，但你很难告诉Kibana"这条是模型调用、那条是检索span"，更别说基于这些语义做模型成本计算。三是你最终想要的是"看到一次请求的全貌"，LangFuse直接把树状结构渲染成UI，点开trace就能看到prompt原文、模型返回、token用量、延迟和cost，零代码。工具的意义在于帮你省掉这层自己造轮子的成本。
3. 本地部署LangFuse：十分钟起一个观测服务
3.1 docker compose 一键拉起全部依赖
LangFuse是开源项目，官方直接提供docker compose文件，自托管部署比想象中简单。我自己比较推荐先在局域网内一台Linux机器上起一套，开发环境、测试环境共用，成本几乎为零。
部署前确认机器上装了Docker和Docker Compose插件。然后新建一个目录，把官方docker-compose.yml拉下来：
mkdir langfuse && cd langfuse curl -o docker-compose.yml https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml文件里默认包含了几个服务：LangFuse本身的服务端和一个后台worker，数据层用PostgreSQL保存结构化数据，Redis做队列缓存，另外还有一个MinIO对象存储服务，用来存放音视频、图片这类文件类型的观测数据。如果你不需要存文件，可以精简配置，但为省事我建议第一次直接全量起，后续再按需裁剪。
启动之前先编辑一下环境变量。其中几个必须关注：NEXTAUTH_URL要设成你实际访问LangFuse的地址，浏览器里不带这个域名登录会不通过；NEXTAUTH_SECRET、SALT、ENCRYPTION_KEY是安全相关的随机串，尤其ENCRYPTION_KEY，旧版迁移或者集群扩容时必须保持一致，否则历史数据里的敏感字段解不开。
然后执行：
docker compose up -d等PostgreSQL和Redis健康检查通过，浏览器访问http://服务器IP:3000就能看到登录页。整个过程通常不超过五分钟。
3.2 初始化账号与签发API密钥
第一次打开会提示你创建管理员账号。创建完账号之后，建议立刻创建一个Project，名字按环境区分，比如prod-server-agent、dev-chatbot、staging-copilot。每新建一个Project，系统会为你生成一对API密钥：一个Public Key和一个Secret Key。这对密钥就是埋在应用里的凭据，SDK发送数据到哪台服务器、属于哪个Project，全靠它们区分。
有一点容易忽略：LangFuse的Project粒度没你想的那么"粗"，一个Project可以同时承载多个应用，只要这些应用共用同一套密钥。但为了清洗数据、控制权限、分开统计成本，我还是建议按业务线拆Project。同一个环境里的不同Agent应用，可以在同Project下用trace的name字段继续区分，这样成本报表和告警规则都能做得更干净。
3.3 数据存储与多环境规划
刚部署起来的新手一般不会考虑数据量问题，但我提醒一句：LangFuse的记录详细程度可以非常高，prompt原文、响应全文、token明细全都会落到PostgreSQL里。一个日调用量过万的Agent应用，一天可能产生几GB数据量。所以接手一个正式项目前，你得先想清楚几件事：
- 生产环境数据必须定期清理。LangFuse提供数据保留策略配置，建议生产环境把原始数据保留期设成30天或60天，过期自动清理，降低存储压力。
- 开发环境和生产环境一定分开。千万别让开发联调数据和生产流量混在同一个Project里，否则排查问题时噪音会非常大。
- 对象存储的MinIO如果只是单机跑，先考虑挂一块独立磁盘，别和系统盘抢空间，文件观测数据膨胀速度会比想象中快。
4. 接入埋点：从自动CallbackHandler到手动精确控制
4.1 最快路径：LangChain自动埋点
我推荐刚上手的人先走自动埋点路径，五分钟就能看到trace。
先在Python环境里安装依赖：
pip install langfuse langchain openai然后设置环境变量，可以直接写到shell或者项目的.env里：
LANGFUSE_PUBLIC_KEY=你的PublicKey LANGFUSE_SECRET_KEY=你的SecretKey LANGFUSE_HOST=http://你的服务器IP:3000接下来在LangChain代码里加一个回调处理器：
from langfuse.callback import CallbackHandler langfuse_handler = CallbackHandler() # 方式一：调用时动态传入 answer = chain.invoke( {"question": "帮我总结这份合同的风险条款"}, config={"callbacks": [langfuse_handler]} )如果你用的是LangGraph，写法也一样，把callbacks传进图的invoke配置里，LangFuse会自动识别图中的每个节点，并把它们展开成trace下的SPAN节点。这大概就是热词里"langgraph和langchain的区别"在实际观测维度上的体现：不管底层是Chain还是Graph，对LangFuse来说都是一串可观测的事件流。
跑一次之后打开LangFuse页面，左侧列表应该已经出现一条trace。点进去能看到调用树，每个LLM调用的输入输出、模型名称、token用量全部都在。这一步就走通了。
4.2 手动埋点：不依赖LangChain也能全链路可观测
但如果你不是在用LangChain，而是自己手写了OpenAI调用，或者公司内部封装了SDK，那自动埋点就失效了。这时可以完全用手动SDK构造trace，自由度最高。
from langfuse import Langfuse langfuse = Langfuse() trace = langfuse.trace( name="customer-service-agent", user_id="user_12345", session_id="session_abc", metadata={"env": "production", "prompt_version": "v2.1"} ) # 手动标记一个外部检索span retrieval_span = trace.span(name="vector-search", input={"query": "合同风险条款"}) retrieval_span.end(output={"hits": [{"id": "doc_1", "score": 0.91}]}) # 手动标记一次模型调用 gen = trace.generation( name="gpt-4o-summary", model="gpt-4o", model_parameters={"temperature": 0.3}, input={"messages": [{"role": "user", "content": "..."}]} ) # 拿到模型响应之后 gen.end( output={"content": "合同主要风险..."}, usage={"input": 1234, "output": 567, "total": 1801} ) # 最后整条trace输出 trace.update(output={"final_answer": "合同主要风险..."})这段代码里有几个需要解释的细节。trace.span和trace.generation创建出来的对象，在结束时必须调用.end()，不调用的话这个节点会一直显示为"未结束"状态，UI里会标红，也拿不到完整的耗时统计。usage字段虽然LangChain自动埋点时会自动带上，但手动埋点时如果忘了传，成本计算就直接归零，这是导致很多新手"明明有trace但没成本"的原因之一。
4.3 埋点命名、用户与Session关联
随着数据量增加，"会查"比"会记"更重要。我强烈建议团队内统一出一套命名规范。比如trace的name用业务域-场景，generation的name用模型-用途，span的name用操作-对象。不要用question-answer或run-1这种没有区分度的名字。原因很简单，后面你在LangFuse的列表页检索、按name聚合看指标时，name就是你最核心的分组标签，起得好，报表事半功倍。
用户和Session我建议应用层有值就一定要传。user_id可以是真实的用户ID，也可以是设备ID，关键是它能让你回答"某个用户消耗了多少token、用了多少次工具调用"；session_id用来把同一次多轮对话的多条trace关联在一起，看单次会话的完整过程。设置方式都写在前面，注意user_id不要放明文手机号邮箱这类隐私字段，放系统内部主键就行。
4.4 三种接入方式怎么选
我把常见接入方式整理成一张表，你可以根据自己项目情况快速做决定：
| 接入方式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| LangChain CallbackHandler | 项目基于LangChain/LangGraph | 接入最快，组件自动展开 | 依赖框架回调，自定义逻辑需要额外SDK打点 |
| 手动SDK调用 | 自研调用、非LangChain框架 | 可精确控制每个节点，不绑定框架 | 需要自己管理对象生命周期，代码侵入性稍高 |
| OpenTelemetry集成 | 多语言、跨服务，已有OTel基建 | 标准协议，统一技术栈 | 配置复杂，LLM语义不如原生SDK丰富 |
如果是新项目，我的建议是：先用自动CallbackHandler跑通，再把手动SDK的埋点补到关键业务节点上。两个并用不冲突，LangFuse SDK内部本身会合并同类数据，同一个trace下既可以有自动识别的节点，也可以有手动创建的节点。
5. 成本监控：把每轮对话的token消耗变成账单
5.1 成本是怎么算出来的
很多人以为LangFuse的成本是它自己"猜"出来的，其实不是。它只是忠实地记录了每个generation的模型名和token用量，然后把这两个值跟你在配置中心里维护的"模型价格表"做乘法，得到单次调用的估算成本。
具体算法很简单。假设你用的是gpt-4o，在模型配置里填了输入价格是每百万token 2.5美元，输出价格是每百万token 10美元。某次调用的输入是2000个token，输出是500个token，那么这次调用的成本就是：
input cost = 2000 / 1_000_000 * 2.5 = 0.005 美元 output cost = 500 / 1_000_000 * 10 = 0.005 美元 total cost = 0.01 美元单看这笔好像不贵，但如果你有100万个这样的请求，就是1万美元。LangFuse做的事情本质上是把这笔账从"月底看账单"提前到"实时看trace"。
5.2 模型价格配置实操
在LangFuse控制台的配置页面里找到Models入口，新增模型时需要填以下几项：
- 模型名称：这里必须是generation里写入的model字段值完全一致，大小写、连字符都不能差
- 单位：一般是token
- 输入价格：每百万token的价格，按美元填
- 输出价格：每百万token的价格
- 还有可选的是每千条请求的固定费用，部分第三方模型有按请求计费的场景用得上
这里的坑在"模型名称一致性"上。举个例子，如果你代码里用的是gpt-4o，但在LangFuse模型配置里建的是openai/gpt-4o，那成本匹配会直接失败，这一条trace显示cost为0，但又不会报错。我习惯的做法是，在LangFuse模型配置里把实际可能出现的模型名都建一遍，比如gpt-4o、gpt-4o-mini、gpt-4-turbo、text-embedding-3-large，宁可多建不要漏建。
5.3 从trace明细到用户级成本报表
成本配置完之后，进入trace详情页，右侧会看到一个cost字段，精确到小数后四位。这只是单次调用的视角。
更有价值的是把成本和数据做交叉分析。LangFuse的仪表盘里有几个维度我日常用得最频繁。
第一个是"按用户看成本"。只要你在埋点里正确传了user_id，就能按用户聚合出每个人的token消耗和费用。这个对做To B业务尤其关键，你能直接判断哪些客户正在重度过量使用，是否需要调整套餐配额。
第二个是"按Session看成本"。传了session_id之后，可以看某一轮客服会话从开始到结束一共烧了多少钱。我见过最离谱的一次是某个Agent在用户一句话后反复调用工具重试了17次，最后回答质量还很差，而普通日志根本看不出这17次内部调用花了多少钱。从session成本列表一眼就抓出来了。
第三个是"按trace name看成本"。如果你的不同场景用了不同trace name，这一维度能直观对比"合同总结"和"意图识别"两个场景谁更烧钱，后续优化方向就有了依据。
5.4 成本异常预警与数据采样
LangFuse默认有Alert功能，支持设置基于成本、延迟、错误率的触发规则。我自己维护生产环境时，配了两条比较基础的规则：一条是单条trace成本超过某个阈值就告警，另一条是连续N条trace的错误率超过某个百分比就告警。前者主要防prompt工程事故导致的token疯涨，后者防模型输出异常。
对于高流量的应用，还有一招是用采样率控制记录数据量。在Project的Settings里调整采样率，比如设成0.1，那么只有10%的trace会被完整记录。这个机制并不会损失你在宏观层面的统计准确性，因为LangFuse在做聚合指标时会对采样数据做加权还原。真正高频核心链路我建议全量保留，旁路数据或调试数据大幅采样甚至直接不开埋点，能明显降低数据库负载。
6. 踩坑实录：部署与埋点中的几个高频问题
6.1 "Dashboards上始终没有trace"的完整排查链路
这个是我在技术社区里见过最多的问题，也是热词里"埋点捕获"类问题的重灾区。现象很统一：代码跑完了，业务一切正常，但LangFuse页面空荡荡，一条trace都没有。
我按自己的排查习惯给你一条链路，照着走基本能定位问题。
第一步，确认环境变量真的生效了。很多人在Jupyter或者IDE里设置环境变量之后，用的是旧进程，环境变量根本没加载进来。先写个一次性脚本打印一下：
import os from langfuse import Langfuse print(os.getenv("LANGFUSE_PUBLIC_KEY") is not None) print(os.getenv("LANGFUSE_HOST"))两个都非空再往下走。
第二步，检查LangFuse服务端本身是否健康。在服务器上执行：
curl http://localhost:3000/api/public/health如果这个接口返回200且是JSON格式的healthy状态，服务端是好的；如果是502或者拒绝连接，问题出在LangFuse服务的容器启没起来，回看docker compose ps排查。
第三步，检查宿主机和容器的网络。如果你的应用跑在Docker容器里，而LangFuse跑在宿主机上，那LANGFUSE_HOST不能填http://localhost:3000，因为容器里的localhost是容器自己。要填宿主机IP，或者用http://host.docker.internal:3000。反过来如果应用和LangFuse都在同一个compose网络里，建议用服务名作为host，比如http://langfuse:3000。
第四步，确认SDK发送没有抛异常但也没有成功。LangFuse的SDK默认是异步批量上报，写代码时如果进程立刻退出，缓冲区的数据还没来得及发送就被杀掉了。在长驻服务里问题不大，但如果是一次性脚本，别忘了在脚本结尾加一句langfuse.flush()强制刷新缓冲。
6.2 回调对业务性能的影响与规避
我一开始也担心过，多套一个CallbackHandler会不会明显拖慢接口。实测下来，在正常网络下影响很小，因为LangFuse SDK是先把事件放到本地队列，然后由后台线程批量发送，不会阻塞主链路。但有几个场景需要注意。
第一，如果应用和LangFuse服务不在同一地域，网络延迟过高时，本地队列会积压，内存增长就得关注。解决方案是缩短批量发送间隔，或者干脆在离业务近的位置部署LangFuse。第二，如果单个trace里的generation数量特别多，比如一个Agent循环调用了几十次工具，树本身会非常大，记录、存储、渲染都有成本。这种场景建议只保留generation级别的记录，SPAN级别的内部噪音可以适当关闭，或者把采样率降下来。
其实我更想提醒的是"不要因为观测代码导致业务故障"。LangFuse的回调异常被设计为不会向上抛出，业务代码不会被带崩，但你自己的代码在手动打点时要小心，不要在.end()之类的调用里传错误的类型，异常被吞掉也好，但最终你会看到数据缺失，排查起来反而更费时间。
6.3 数据脱敏与存储安全
既然prompt和模型输出都会被写入LangFuse数据库，这条链路里必然涉及敏感数据规范的问题。我不建议把用户完整输入明文打到观测平台里，尤其是姓名、手机号、身份证这类个人隐私信息。
我现在的做法是：进入模型调用之前，先在应用层做一个脱敏或分类，把明显的PII替换成占位符；有些场景不能脱敏，比如必须保留原文才能排查对话质量问题，那我就在LangFuse侧开启加密存储，并缩小数据库访问权限。另外，日志保留期要按数据规范来，别为了排查方便无限期存。前面提到的数据保留策略，这个阶段就能派上用场。
7. Agent场景进阶：LangGraph调用链与评估闭环
7.1 LangGraph的节点观测
如果你已经进入LangGraph阶段，可观测性反而变得更有意思了。LangGraph的图执行过程中，每个节点的状态变化其实都是很宝贵的排查信息。LangFuse的CallbackHandler接入之后，LangGraph的每个节点会以SPAN的形式出现在LangFuse的trace树中，节点调用模型会拆成更细的GENERATION，节点之间传递的state摘要也会被LangFuse通过metadata记录。
实际项目里我看的最多的就是"路由决策"类的问题。Agent决定调用哪个工具、在什么条件下结束循环、在哪一步把状态搞丢了，在LangGraph节点展开之后一目了然。每次看到状态从A节点传到B节点后字段丢了，不用再靠猜，直接看trace里两节点之间的state变化就能定位到是哪段代码覆盖了字段。
顺手说一句，多Agent编排在新框架里越来越常见。像Agent2Agent这种多Agent通信的协议场景，各Agent之间的消息流转同样会体现在trace树上，LangFuse 3.x也已经跟进这类语义，搜到相关trace时能看到跨Agent的完整消息链路，排查"消息到底在哪一环被截断"会轻松很多。
7.2 用LangFuse给trace打分，把评估接到生产链路里
观测只是起点，LangFuse真正让我离不开的功能是trace评分。你可以在每一条真实trace上打一个业务得分，比如"回答是否相关""是否成功调用了工具""用户是否点了踩"，然后跟token成本、延迟放在一起分析。这样你就能回答一个在传统日志里根本答不了的问题：这个Agent版本到底是在变好还是在变坏。
打分的接入也不复杂。如果是在服务端代码里自动打分，直接调用SDK：
from langfuse import Langfuse langfuse = Langfuse() langfuse.score( trace_id="实际trace的ID", name="answer-relevance", value=0.95, comment="回答命中知识库，推荐合同风险条款准确" )如果你有一套自己的LLM-as-a-judge的评估逻辑，可以在拿到trace_id后批量回填分数。LangFuse支持在UI上单独查看每个打分维度的分布曲线，还能把负分样本连回trace详情，做bad case归因。
7.3 结合Prompt管理做回归对比
还有一个容易被低估的功能是LangFuse内置的Prompt管理。它可以把Prompt模板版本化，每次发布Prompt版本后，线上trace里会记录用的是哪个版本。配合评估分，你可以直接对比"v3.2版本的prompt比v3.1版本的prompt在同一批真实请求上的平均分是不是更高"。我以前做prompt优化全靠拍脑袋和肉眼观察，现在起码有一份数据支撑的回归结果。
这套玩法的完整链路是：线上trace采集到真实请求 -> 自动评估服务打分 -> 聚合评分与成本 -> 决定是否切换prompt或模型版本 -> 新版本继续进入下一轮观测。整个闭环跑起来之后，Agent系统的迭代就不再是玄学，每一次改动有没有效果，数据会直接告诉你。
就我个人的实操感受来说，LangFuse真正改变我工作习惯的是"每次改动必有数据对比"这件事。现在不管是调整Prompt模板、切换模型、改检索逻辑还是改工具调用顺序，第一件事都是看一眼改动前后的trace对比，第二件事看成本趋势。如果你的AI应用也已经到了需要认真对待质量、成本和可维护性的阶段，我建议你今晚就花十分钟把LangFuse部署起来，接一条最核心的链路试试水。只有真正点开那棵完整的调用树，你才知道之前自己瞎猜浪费了多少时间。
