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 条评论

登录 后参与评论

还没有评论,来抢沙发~