LangGraph 怎麼使用本地模型:對接 Ollama、vLLM 與解決工具調用失敗

想在內網或零 API 帳單環境下跑 LangGraph 智能體,可以通過官方 langchain-ollama 包接入本機 Ollama,或用 OpenAI 兼容接口接入 vLLM 與 LM Studio。本文講清完整代碼、工具調用模型挑選以及調大 num_ctx 防截斷的關鍵細節。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. 接本機 Ollama 請裝官方獨立包 langchain-ollama 並導入 ChatOllama,不要再抄舊教學裏已廢棄的 langchain_community 同名類。
  2. 接 vLLM、LM Studio 或 llama.cpp 本地服務,直接用 langchain-openai 的 ChatOpenAI,把 base_url 指向本地端口即可無縫複用。
  3. 本地跑圖成敗的第一前提是模型本身支持原生工具調用(Tool Calling):在 Ollama 模型庫裏必須挑帶有 Tools 標籤的型號(如 qwen2.5、llama3.1 等),不支持工具調用的模型無法觸發 ToolNode。
  4. 必改參數 num_ctx:Ollama 預設上下文窗口通常只有 2048 Token,掛上幾個工具跑兩輪就會截斷前文,初始化 ChatOllama 時務必顯式調大 num_ctx(如 8192 或 16384)。

LangGraph 對接本地 Ollama 四步

圖:本站根據 LangChain ChatOllama 官方集成文檔 整理的示意圖

本文根據 LangChain 官方 langchain-ollama 集成文檔與 Ollama 官方說明整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 LangChain 或 Ollama 官方網站。

適用於誰

  • 搜「langgraph 使用 本地 模型」「langgraph 接入 ollama」的人;
  • 處於企業內網隔離環境,或者想在本地開發調試階段免掉雲端 API 帳單的 Python 開發者;
  • 把本地模型接進 StateGraph 後,遇到「模型死活不調工具、直接把 JSON 吐在正文裏」或「跑兩輪就失憶報錯」的人。

如果你還沒跑通第一個基礎狀態圖,建議先看 /guides/langgraph-quickstart-install-first-graph。

一、準備工作:拉取帶 Tools 能力的本地模型與安裝包

先確保本機已安裝並啟動 Ollama,拉取一個明確支持函數工具調用的權重(個人筆記本顯存有限可選 7B / 14B 檔位,單節點工具數較多時建議 14B 以上準確率更穩):

bash
ollama pull qwen2.5:14b

然後在你的 Python 虛擬環境裏安裝 langgraph 與專用集成包 langchain-ollama:

bash
pip install -U langgraph langchain-core langchain-ollama

二、完整代碼:用 ChatOllama 驅動 StateGraph

新建 local_graph.py。注意我們在初始化 ChatOllama 時顯式固定了 temperature=0(減少工具參數格式漂移)和 num_ctx=16384(防止多輪工具輸出把系統指令擠出窗口):

python
from langchain_core.tools import tool
from langchain_ollama import ChatOllama
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition

# 1. 本地模型非常依賴清晰的類型註解和中文/英文文檔註釋來生成參數結構
@tool
def query_warehouse_stock(sku_code: str) -> str:
    """根據商品編碼(如 SKU-101)查詢本地倉庫當前可用庫存數量。"""
    mock_db = {"SKU-101": "剩餘 42 件", "SKU-205": "缺貨補單中"}
    return mock_db.get(sku_code.upper(), "未找到該商品編碼")

tools = [query_warehouse_stock]

# 2. 連接本機 Ollama 服務(預設地址 http://127.0.0.1:11434)
llm = ChatOllama(
    model="qwen2.5:14b",
    temperature=0,
    num_ctx=16384,
).bind_tools(tools)

# 3. 定義推理節點與狀態圖
def assistant_node(state: MessagesState):
    return {"messages": [llm.invoke(state["messages"])]}

builder = StateGraph(MessagesState)
builder.add_node("assistant", assistant_node)
builder.add_node("tools", ToolNode(tools))

builder.add_edge(START, "assistant")
builder.add_conditional_edges("assistant", tools_condition)
builder.add_edge("tools", "assistant")

graph = builder.compile()

if __name__ == "__main__":
    out = graph.invoke({
        "messages": [("user", "幫我查一下 SKU-101 還有沒有貨?")]
    })
    for m in out["messages"]:
        m.pretty_print()

如果 Ollama 跑在內網另一台 GPU 伺服器上,只需在 ChatOllama(...) 裏加上 base_url="http://內網伺服器IP:11434" 即可。

三、如果本地跑的是 vLLM 或 LM Studio 怎麼接

企業顯卡伺服器常使用 vLLM 啟動高並發推理(開啟工具解析參數如 --enable-auto-tool-choice --tool-call-parser hermes),桌面用戶則常用 LM Studio 開啟本地 HTTP Server。這類服務端都提供標準的 OpenAI /v1 兼容接口,直接用 ChatOpenAI 就能接入同一張圖:

python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="Qwen/Qwen2.5-14B-Instruct",
    base_url="http://127.0.0.1:8000/v1",
    api_key="EMPTY",  # 本地免鑑權服務隨便填非空佔位符即可
    temperature=0,
).bind_tools(tools)

本地模型工具調用常見報錯排查

圖:本站根據 LangChain 與 Ollama 官方文檔 整理的示意圖

四、讓小參數本地模型在多 Agent 圖裏不翻車的三個技巧

和雲端百億千億級旗艦模型相比,7B 到 14B 的本地量化模型在複雜圖編排裏容錯率較低,按下面三條收斂設計成功率會高很多:

  1. 單個節點掛載的工具不要超過 3 到 5 個:如果你通過 MCP 一次性灌入二十幾個工具(接入方法見 /guides/langgraph-mcp-integration-guide),本地小模型極易選錯工具或填錯字段。按業務拆成專職節點,每個節點只綁兩三個扁平參數工具;
  2. 需要強制返回 JSON 時用 with_structured_output:做前置意圖路由節點時,定義 Pydantic 模型調用 llm.with_structured_output(RouteSchema),利用底層的語法約束(Grammar / JSON Schema)鎖死輸出格式,別靠提示詞求它「請不要輸出多餘文字」;
  3. 採用「本地小模型做前哨 + 雲端強模型兜底」混合圖:在非涉密場景下,把高頻字段清洗、簡單分類留給本機免費 Ollama 節點,遇到複雜規劃節點再路由給雲端強模型(成本拆分思路見 /guides/multi-agent-token-cost-why-high-how-to-control 與 /guides/claude-agent-sdk-vs-langchain-how-to-choose)。平時對照評估本地開源模型與雲端前沿模型的真實差距時,個人測試環境也可參考 /chongzhi/claude-pro 的官方套餐說明。

常見問題

Q:為什麼模型沒有觸發 ToolNode,而是在回覆正文裏打印了一段 {"name": "query_warehouse_stock", ...} 代碼塊?

兩個常見原因:第一,你拉取的模型版本在 Ollama 官方庫裏不支持原生 Tools 協議模板;第二,忘了把 .bind_tools(tools) 返回的新對象賦給節點裏實際調用的變量(注意 llm.bind_tools(tools) 不會原地修改原 llm 對象,必須接住返回值)。

Q:在 Docker 容器裏跑 Python 腳本連宿主機 Ollama 報 Connection refused 怎麼辦?

容器內的 127.0.0.1 指的是容器自己而不是宿主機。在 macOS / Windows 的 Docker Desktop 裏把 base_url 改成 http://host.docker.internal:11434,並確認宿主機 Ollama 環境變量配置允許非迴環地址監聽。

Q:本地深度思考模型(如帶思維鏈標籤的推理權重)接進圖裏要注意什麼?

部分推理模型會在正文裏輸出較長的 <think> 思考過程,不僅佔用 num_ctx 窗口,還可能在多輪歷史回傳時拖慢下一輪首字響應。建議查看 ChatOllama 當前版本支持的推理字段分離參數,或在進入下游節點前只保留精簡結論,避免把冗長思考草稿原樣塞進後續狀態。

相關教學

參考資料

  • LangChain 官方文檔:ChatOllama 集成指南 — https://docs.langchain.com/
  • Ollama 官方模型庫與文檔 — https://ollama.com/

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

登入 後參與評論

還沒有評論,來搶沙發~