Deployment：从本地到云端
LangGraph 部署体系全解析

1 这一讲要解决什么问题？

前几讲我们构建了 Simple Graph、Chain、Router、Agent，全都在 Jupyter Notebook 里通过 graph.invoke() 同步调用。这在学习阶段没问题，但在生产环境会遇到几个严重问题：

2 五个组件的层次架构

LangGraph 部署体系由五个组件构成，它们的层次关系如下：从最底层的 Python/JS 库，到 API 服务器，再到三种不同的访问/托管方式。

逐层解析

3 为什么需要 LangGraph API？

这是理解整个部署体系的关键问题。直接用 invoke() 不是更简单吗？让我们对比两种方式：

invoke() 的问题：同步阻塞

# 直接 invoke —— 简单，但在生产环境有严重问题
result = graph.invoke({"messages": [HumanMessage("帮我研究量子计算的最新进展")]})
# ^ 这里会阻塞 5~10 分钟，直到 Agent 完成所有工具调用
# Web 服务器的请求会超时，用户体验极差

LangGraph API 的三大能力

# 通过 API 的异步方式 —— 立即返回，streaming 获取结果
async for chunk in client.runs.stream(thread_id, "agent", input=input):
    # 每个图步骤完成后立即收到更新，不阻塞
    print(chunk.data)

4 本地开发流程：langgraph dev

在把 Agent 部署到云端之前，你需要在本地启动 LangGraph API 服务器，这样才能用 Studio 可视化调试，并用 SDK 做集成测试。

studio/ 目录结构

每个模块都有一个 studio/ 子目录，这是 LangGraph API 服务器的根目录。结构如下：

langgraph.json 是核心配置

// module-1/studio/langgraph.json
{
  "dependencies": ["."],           // 依赖当前目录（读取 requirements.txt）
  "graphs": {
    "agent": "./agent.py:graph",   // 注册图：graph_id → 文件:变量名
    "router": "./router.py:graph"  // 可以注册多个图
  },
  "env": ".env"                   // 环境变量文件路径
}

启动本地服务器

# 在 studio/ 目录下运行
$ langgraph dev

# 成功启动后输出：
🚀 API: http://127.0.0.1:2024
🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

Studio 能做什么？

• 可视化图的节点和边（自动渲染为流程图）
• 直接输入消息，手动触发 run
• 每步执行后查看完整 State 内容
• 查看 LangSmith 的追踪详情（每次 LLM 调用、工具调用）
• 支持 Interrupt（人工介入），即 Module 3 的 Human-in-the-Loop

5 SDK：程序化访问图的方式

LangGraph SDK（pip install langgraph-sdk）是 Python 客户端库，让你在代码中与 LangGraph API 交互。核心入口是 get_client()：

from langgraph_sdk import get_client

# 连接本地开发服务器
URL = "http://127.0.0.1:2024"
client = get_client(url=URL)

# 连接云端部署（切换一行代码即可）
# URL = "https://your-deployment-xxxx.us.langgraph.app"
# client = get_client(url=URL, api_key="lsv2_...")

client 是整个 SDK 的操作入口，通过它访问所有资源：

完整 SDK 调用示例

from langgraph_sdk import get_client
from langchain_core.messages import HumanMessage

# 1. 建立连接
URL = "http://127.0.0.1:2024"
client = get_client(url=URL)

# 2. 查看已注册的图（对应 langgraph.json 里的 graphs）
assistants = await client.assistants.search()
print(assistants)
# [{'assistant_id': '...', 'graph_id': 'agent', ...},
#  {'assistant_id': '...', 'graph_id': 'router', ...}]

# 3. 创建一个对话线程（对应一个持久化的 State 容器）
thread = await client.threads.create()
print(thread['thread_id'])   # 类似 UUID 的字符串

# 4. 在这个线程上发起流式运行
input = {"messages": [HumanMessage(content="Multiply 3 by 2.")]}

async for chunk in client.runs.stream(
    thread['thread_id'],   # 线程 ID
    "agent",              # graph_id（对应 langgraph.json 中的键）
    input=input,
    stream_mode="values",  # 每步后返回完整 State
):
    if chunk.data and chunk.event != "metadata":
        print(chunk.data['messages'][-1])

6 三个核心概念：Assistant / Thread / Run

理解这三个概念是用好 SDK 的基础。它们是 LangGraph API 的资源模型，类似于数据库里的三张表。

三者的关系

7 流式运行：stream_mode 详解

client.runs.stream() 返回一个异步迭代器，每次迭代得到一个 chunk 对象。chunk 有两个关键字段：chunk.event 和 chunk.data。

chunk.event 的类型

stream_mode 参数对比

stream_mode="values" 的 chunk.data 结构

# chunk.event == "values" 时，chunk.data 就是完整 State：
chunk.data = {
    "messages": [
        HumanMessage(content="Multiply 3 by 2."),
        AIMessage(content="", tool_calls=[{
            "name": "multiply",
            "args": {"a": 3, "b": 2}
        }]),
        ToolMessage(content="6"),
        AIMessage(content="3 multiplied by 2 equals 6.")
    ]
}

# 每步执行后都会收到一次这样的 chunk，messages 列表逐步增长
# 所以用 chunk.data['messages'][-1] 只看最新的消息

8 本地 vs 云端：SDK 的统一接口

LangGraph SDK 最重要的设计理念是本地开发和云端生产使用完全相同的 API。唯一的差异是连接时的 URL 和认证 key。

from langgraph_sdk import get_client

# 本地：只需 URL
client = get_client(
    url="http://127.0.0.1:2024"
)

# 以下代码完全相同 ↓
thread = await client.threads.create()
async for chunk in client.runs.stream(
    thread['thread_id'],
    "agent",
    input=input,
    stream_mode="values",
):
    ...

from langgraph_sdk import get_client

# 云端：URL + API Key
client = get_client(
    url="https://xxx.us.langgraph.app",
    api_key="lsv2_pt_..."
)

# 以下代码完全相同 ↓
thread = await client.threads.create()
async for chunk in client.runs.stream(
    thread['thread_id'],
    "agent",
    input=input,
    stream_mode="values",
):
    ...

本地 vs 云端：完整对比

9 云端部署流程（LangSmith Deployment）

当你的 Agent 在本地测试通过后，可以将它部署到 LangSmith 云端，获得稳定的线上服务地址。

10 完整流程串联

把所有知识点串联起来，看看一个完整的 LangGraph 开发到部署的流程：

知识点速查卡