LangGraph 怎么接入 Langfuse 做链路追踪:CallbackHandler 配置、会话分组与自托管注意事项

不想绑定商业闭源追踪平台时,给 LangGraph 接开源的 Langfuse 是最稳妥的生产可观测方案。本文按官方最新文档讲清环境变量配置、CallbackHandler 挂载写法、多轮会话归组以及短脚本防丢日志的 flush 细节。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. LangGraph 不需要改任何节点内部业务代码就能接上 Langfuse:只需在调用 graph.invoke 或 astream 时,通过 config={"callbacks": [langfuse_handler]} 传入回调处理器。
  2. 注意新版导入路径变化:Langfuse Python SDK 新版统一从 from langfuse.langchain import CallbackHandler 导入,自动把整张状态图的节点跳转、条件分支与工具调用串成一棵完整的嵌套调用树(Trace)。
  3. 一次性命令行脚本退出前务必调用刷新(Flush):Langfuse 默认在后台异步批量上报日志,脚本跑完立刻退出进程会导致队列里的数据还没发出去就被掐断。
  4. 企业内网合规零改造切换:代码完全不变,只需把环境变量 LANGFUSE_HOST 从官方云地址改成你们内网自建的 Langfuse 地址,敏感提示词就绝不出内网。

LangGraph 接入 Langfuse 四步流程

图:本站根据 Langfuse 官方 LangGraph 集成文档 整理的示意图

本文根据 Langfuse 官方 LangChain / LangGraph 集成文档与开源仓库说明整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Langfuse 或 LangChain 官方网站。

适用于谁

  • 搜「langgraph 使用 langfuse」「langgraph 接入开源链路追踪」的人;
  • 选择了免费开源库自建部署(计费对比见 /guides/langgraph-pricing-open-source-vs-platform),需要一套能私有化部署在内网、看清每个节点耗时和 Token 账单的可观测面板的后端团队;
  • 配完回调运行脚本后,发现 Langfuse 后台空空如也、一条记录都没收到的开发者。

如果你还在开发期做单步改状态调试,优先用本地 Studio(见 /guides/langgraph-debug-visualize-studio-guide);上了测试和生产环境监控真实用户请求,就轮到 Langfuse 上场了。

一、第一步:安装依赖与配置三项环境变量

在已经装好 langgraph(基础环境见 /guides/langgraph-quickstart-install-first-graph)的虚拟环境里安装 langfuse:

bash
pip install -U langfuse langgraph langchain-openai

登录 Langfuse 后台(官方云或你们自己的私有实例)创建一个项目,拿到公钥和私钥后写入系统环境变量或 .env 文件:

bash
export LANGFUSE_PUBLIC_KEY="pk-lf-你的公钥"
export LANGFUSE_SECRET_KEY="sk-lf-你的私钥"
# 欧区默认云、美区云或内网自建地址按实际项目填写:
export LANGFUSE_HOST="https://cloud.langfuse.com"

Langfuse 云端版与私有化自托管对比

图:本站根据 Langfuse 官方自托管与安全文档 整理的示意图

二、第二步:挂载 CallbackHandler 追踪完整状态图

无需给每个 Python 节点函数挨个加装饰器,LangGraph 在运行期会自动把顶层 config 里的 callbacks 向下透传给图里的所有大模型调用、ToolNode 工具执行以及嵌套子图。

python
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition
from langfuse import get_client
from langfuse.langchain import CallbackHandler

@tool
def check_order_status(order_id: str) -> str:
    """查询指定订单号的物流状态。"""
    return f"订单 {order_id} 已发出,预计明日送达"

tools = [check_order_status]
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)

def agent_node(state: MessagesState):
    return {"messages": [llm.invoke(state["messages"])]}

builder = StateGraph(MessagesState)
builder.add_node("agent", agent_node)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
graph = builder.compile()

if __name__ == "__main__":
    # 1. 初始化回调处理器(自动读取环境变量中的密钥)
    langfuse_handler = CallbackHandler()

    # 2. 在调用图时通过 config 注入 callbacks 与业务元数据
    res = graph.invoke(
        {"messages": [("user", "帮我查一下订单 ORD-8899 到哪了")]},
        config={
            "callbacks": [langfuse_handler],
            "metadata": {
                "langfuse_user_id": "user_42",
                "langfuse_session_id": "chat_thread_001",
                "langfuse_tags": ["order-bot", "prod"],
            },
        },
    )
    print(res["messages"][-1].content)

    # 3. 短生命周期脚本退出前强制把缓冲区日志发完
    get_client().flush()

跑完打开 Langfuse 后台的 Traces 列表,点开最新一条记录,你就能清晰看到顶层 LangGraph 下面依次挂着 agent 首次推理、tools 调用 check_order_status 的入参返回值、以及 agent 第二次汇总回复的耗时与 Token 明细。

三、多轮对话归组与成本审计技巧

在真实多 Agent 生产系统里,光抓单次请求还不够,建议把下面两项配置一起用上:

  1. 把 LangGraph 的 thread_id 同步传给 langfuse_session_id:当你的图开启了检查点多轮对话记忆时,把同一个对话线程 ID 同时赋给 configurable.thread_id 和 metadata.langfuse_session_id,后台就能在 Sessions 视图里把用户连续十轮追问按时间线串在一起回看;
  2. 用模型单价表定位高消耗节点:多智能体循环最怕某个子代理暗中跑了十几次重试烧光预算(原因拆解见 /guides/multi-agent-token-cost-why-high-how-to-control)。在 Langfuse 后台按节点名称筛选平均耗时与累计 Token,一眼就能揪出最该降级为轻量模型或加缓存的瓶颈节点。

日常在个人工作站调试多节点提示词并对照官方云端模型输出质量时,如需了解个人 Claude 或 ChatGPT 订阅方案,也可参考 /chongzhi/claude-pro 的整理说明。

常见问题

Q:运行没有报错,但 Langfuse 面板里一直看不到任何 Trace 数据?

按三步排查:第一,检查是不是跑完脚本直接退出了进程但漏写了 get_client().flush()(常驻 FastAPI 服务不需要每次手动 flush,但单次测试脚本必须加);第二,核对 LANGFUSE_HOST 区服是否填错(官方欧洲默认区和美国区地址不同,填反会鉴权失败);第三,确认虚拟环境里没有同时开启冲突的 OpenTelemetry 导出器拦截。

Q:从旧版 Langfuse v2 升级到 v3 后报 ModuleNotFoundError: No module named 'langfuse.callback' 怎么办?

v3 重构了底层采集架构,把导入语句改成 from langfuse.langchain import CallbackHandler,并将原本传在 CallbackHandler(...) 构造函数里的 user_id、session_id 移到 graph.invoke 的 config["metadata"] 里即可平滑迁移。

Q:生产环境里可以把测试集评测(Prompt Management 与 Datasets)也和状态图连起来吗?

可以。你可以在 Langfuse 面板里把线上真实出错的某条用户消息一键加入测试数据集(Dataset),修改节点提示词或切换底层模型后批量重跑整张状态图,客观对比新旧版本在耗时、费用和回答准确率上的变化,不用靠人工凭感觉盲调。

相关教程

参考资料

  • Langfuse 官方文档:LangChain & LangGraph Integration — https://langfuse.com/integrations/frameworks/langchain
  • langfuse/langfuse 官方开源仓库 — https://github.com/langfuse/langfuse

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~