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 條評論

登入 後參與評論

還沒有評論,來搶沙發~