LangGraph Server Agent 框架本地部署指南

发表于 2026-08-24 分类于《大模型应用技术实践》

本文讲解基于 LangGraph Server 服务搭建本地离线 AI Agent 的完整部署流程，适配 Windows 开发环境，全程无需调用公有大模型接口，实现纯本地化 AI 推理与工作流编排，帮助开发者快速搭建可调试、可复用的本地私有化 AI Agent 服务，适用于个人开发、本地功能调试、轻量化私有化 AI 场景落地。

需要特别区分的是，LangGraph 底层核心 Python 库采用 MIT 开源协议，可以永久免费使用，不存在运行额度限制；但教程中用到的 LangGraph Server 属于配套服务组件，即便采用本地自托管的 Lite 轻量模式，也受软件许可约束：每年最多提供 100 万次节点运行额度，该统计为工作流内部节点执行次数，不等同于接口请求次数。当年度节点执行量超出额度，按照许可要求，则需要升级购买企业版授权。

LangGraph Server

1、本次部署仅安装运行 LangGraph Server 与 SDK 所需核心依赖，保证环境纯净无冗余、无版本冲突，采用清华源加速安装，适配 Windows 离线本地化部署。执行以下 CMD 命令安装核心组件。

CMD> pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple "langgraph-cli[inmem]"
CMD> pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple langgraph-sdk
CMD> pip list
Package                                  Version
---------------------------------------- -----------
langchain                                1.3.15
langgraph-api                            0.12.6
langgraph-checkpoint                     4.2.0
langgraph-cli                            0.4.31
langgraph-prebuilt                       1.1.0
langgraph-runtime-inmem                  0.32.6
langgraph-sdk                            0.4.2
langsmith                                0.11.0

2、为快速搭建标准化 LangGraph 项目结构，直接拉取官方开源模板项目，适配 LangGraph Server 运行规范。

打开 CMD 执行以下命令，克隆项目并进入项目根目录：

CMD> git clone https://github.com/langchain-ai/new-langgraph-project
CMD> cd new-langgraph-project
CMD> pip install -e .

3、进入项目根目录，新建 .env 环境配置文件。Windows 系统无法直接右键创建/改名该文件，可通过 Sublime Text、VS Code 等编辑器直接新建保存。该文件用于配置本地大模型地址、项目标识，实现完全离线私有化调用。

文件配置内容如下，适配本地 llama.cpp 部署的大模型接口

# To separate your traces from other application
LANGSMITH_PROJECT=new-agent

# Add API keys for connecting to LLM providers, data sources, and other integrations here
OPENAI_API_KEY=dummy
OPENAI_BASE_URL=http://127.0.0.1:11433/v1

4、为避免 Windows 编码乱码问题，先配置系统编码为 UTF-8，再启动 LangGraph 内存开发服务，内存模式专为本地调试、功能测试设计，支持代码热重载、可视化调试。

在项目根目录 CMD 中依次执行命令，其中测试环境可以使用dev，在编译环境则使用build部署

CMD> set PYTHONUTF8=1
CMD> set PYTHONIOENCODING=utf-8
CMD> langgraph dev

INFO:langgraph_api.cli:
        Welcome to
╦  ┌─┐┌┐┌┌─┐╔═╗┬─┐┌─┐┌─┐┬ ┬
║  ├─┤││││ ┬║ ╦├┬┘├─┤├─┘├─┤
╩═╝┴ ┴┘└┘└─┘╚═╝┴└─┴ ┴┴  ┴ ┴

- API: http://127.0.0.1:2024
- Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
- API Docs: http://127.0.0.1:2024/docs

This in-memory server is designed for development and testing.
For production use, please use LangSmith Deployment.

5、进入本地 llama.cpp 程序目录，执行启动命令，加载本地 GGUF 量化模型，开启 jinja 模板解析，保证与 LangGraph 服务正常消息交互，全程无公网调用。

CMD> llama-server.exe -m qwen2.5-1.5b-instruct-q4_k_m.gguf --host 127.0.0.1 --port 11433 -c 4096 --jinja
init: llama threadpool init, n_threads = 12
load_model: initializing, n_slots = 4, n_ctx_slot = 4096, kv_unified = 'true'
llama_server: model loaded
llama_server: listening on http://127.0.0.1:11433

6、项目核心工作流逻辑位于 new-langgraph-project/src/agent/graph.py，替换默认代码，实现本地大模型调用、自定义系统提示、消息应答逻辑，完成离线智能体功能调试。

完整测试代码如下：

from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Dict
from langgraph.graph import StateGraph
from langgraph.runtime import Runtime
from typing_extensions import TypedDict
from langchain_openai import ChatOpenAI

# 读取.env配置
llm = ChatOpenAI(model="qwen2.5:1.5b")

class Context(TypedDict):
    my_configurable_param: str

@dataclass
class State:
    changeme: str = "example"

async def call_model(state: State, runtime: Runtime[Context]) -> Dict[str, Any]:
    messages = [
        ("system", "你是AI助手，所有回答必须使用简体中文，禁止输出英文回答。"),
        ("human", state.changeme)
    ]
    resp = await llm.ainvoke(messages)
    return {
        "changeme": resp.content
    }

graph = (
    StateGraph(State, context_schema=Context)
    .add_node(call_model)
    .add_edge("__start__", "call_model")
    .compile(name="New Graph")
)

LangGraph SDK

LangGraph SDK 是对接本地 LangGraph Server 的核心工具，支持同步调用、流式响应、批量执行、会话记忆等多种场景，以下提供多套完整可运行案例，适配不同业务需求。

通过 stream 接口实现 SSE 流式输出，逐段返回大模型推理内容，适用于聊天界面实时刷新、长文本生成场景：

from langgraph_sdk import get_client
import asyncio

client = get_client(url="http://127.0.0.1:2024")

async def stream_chat():
    # 流式执行工作流
    async for chunk in client.runs.stream(
        None,
        "agent",
        input={
            "changeme": "你会做什么工作"
        },
    ):
        print(f"事件类型：{chunk.event}")
        print(f"返回数据：{chunk.data}")
        print("-" * 50)

if __name__ == "__main__":
    asyncio.run(stream_chat())

输出内容如下

CMD> python main.py

事件类型：metadata
返回数据：{'run_id': '01a0334b-3b5f-7661-8944-ee72f849d1b8', 'attempt': 1}
--------------------------------------------------
事件类型：values
返回数据：{'changeme': '你会做什么工作'}
--------------------------------------------------
事件类型：values
返回数据：{'changeme': '作为一个AI助手，我可以帮助用户进行多种任务，包括但不限于：\n\n1. 提供信息搜索和查询服务。\n2. 回答各种问题，涵盖科技、文化、生活等各个领域。\n3. 收发邮件
，处理日常事务。\n4. 与用户进行对话交流，提供娱乐、教育等互动内容。\n5. 进行数据分析和机器学习训练。\n6. 与各种应用和服务进行集成，提供更全面的服务。\n\n总的来说，我会尽力协助用
户解决各种问题，提供便利和高效的服务。'}
--------------------------------------------------