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

圖:本站根據 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 的本地量化模型在複雜圖編排裏容錯率較低,按下面三條收斂設計成功率會高很多:
- 單個節點掛載的工具不要超過 3 到 5 個:如果你通過 MCP 一次性灌入二十幾個工具(接入方法見 /guides/langgraph-mcp-integration-guide),本地小模型極易選錯工具或填錯字段。按業務拆成專職節點,每個節點只綁兩三個扁平參數工具;
- 需要強制返回 JSON 時用
with_structured_output:做前置意圖路由節點時,定義 Pydantic 模型調用llm.with_structured_output(RouteSchema),利用底層的語法約束(Grammar / JSON Schema)鎖死輸出格式,別靠提示詞求它「請不要輸出多餘文字」; - 採用「本地小模型做前哨 + 雲端強模型兜底」混合圖:在非涉密場景下,把高頻字段清洗、簡單分類留給本機免費 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 當前版本支持的推理字段分離參數,或在進入下游節點前只保留精簡結論,避免把冗長思考草稿原樣塞進後續狀態。
相關教學
- /guides/langgraph-quickstart-install-first-graph:LangGraph Python 安裝與第一個狀態圖
- /guides/langgraph-mcp-integration-guide:LangGraph 接入 MCP 工具伺服器指南
- /guides/claude-agent-sdk-vs-langchain-how-to-choose:Claude Agent SDK 與 LangChain 選型對比
- /guides/multi-agent-token-cost-why-high-how-to-control:多 Agent 系統成本分析與降本方案
參考資料
- LangChain 官方文檔:
ChatOllama集成指南 — https://docs.langchain.com/ - Ollama 官方模型庫與文檔 — https://ollama.com/
0 條評論
還沒有評論,來搶沙發~