本地环境部署LangGraph

运行LangGraph本地服务器教程总结

该教程详细介绍了在本地环境搭建、运行LangGraph应用的完整流程，涵盖依赖安装、项目创建、环境配置、服务器启动及测试验证，同时提供后续部署与进阶学习方向，适用于开发者快速搭建LangGraph应用的本地开发环境，具体内容如下：

一、前提条件

需提前准备LangSmith API密钥（可免费注册获取），用于后续应用的追踪、调试与可观测性支持。

二、核心操作步骤

1. 安装LangGraph CLI（命令行工具）

LangGraph CLI是创建、管理LangGraph项目的核心工具，需确保Python版本≥3.11，安装命令如下：

bash 复制代码

pip install --upgrade "langgraph-cli[inmem]"

[inmem]：表示同时安装内存存储相关依赖，用于本地开发时的临时状态存储。

2. 创建LangGraph应用（基于模板）

通过CLI从官方模板创建新项目，快速生成可扩展的基础架构（示例使用new-langgraph-project-python模板，为单节点应用，便于后续自定义逻辑）：

bash 复制代码

langgraph new path/to/your/app --template new-langgraph-project-python

模板选择说明 ：若未指定--template参数，执行langgraph new path/to/your/app后会弹出交互式菜单，可从多个可用模板中选择（如多智能体模板、带记忆功能的模板等）。

3. 安装项目依赖（编辑模式）

进入项目根目录，以"编辑模式"（-e）安装依赖，确保本地代码修改能实时被服务器识别（无需重复安装）：

bash 复制代码

# 进入项目目录
cd path/to/your/app
# 安装依赖
pip install -e .

4. 配置环境变量（创建.env文件）

项目根目录会生成.env.example示例文件，需基于该文件创建.env并填充关键配置（核心为LangSmith API密钥）：

复制.env.example内容到新创建的.env文件；
替换LANGSMITH_API_KEY为实际密钥，示例：
env 复制代码
```
LANGSMITH_API_KEY=lsv2...  # 替换为你的LangSmith API密钥
```

5. 启动本地LangGraph服务器

通过langgraph dev命令启动本地API服务器，默认启用内存模式（仅适用于开发与测试，生产环境需切换至持久化存储后端）：

bash 复制代码

langgraph dev

启动成功后输出信息

启动成功后会显示3个关键链接，分别对应API地址、文档地址与可视化UI地址：

复制代码

>    Ready!
>
>    - API: http://localhost:2024/  # 本地API接口地址
>
>    - Docs: http://localhost:2024/docs  # API文档（Swagger风格，可查看所有接口）
>
>    - LangGraph Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024  # 可视化调试UI

Safari兼容性处理 ：若使用Safari浏览器，本地localhost连接可能受限，需添加--tunnel参数创建安全隧道：
bash 复制代码
```
langgraph dev --tunnel
```

6. 测试应用（通过LangGraph Studio）

LangGraph Studio是专为LangGraph设计的可视化UI，支持本地应用的交互、调试与流程可视化，操作步骤如下：

访问langgraph dev输出中的"LangGraph Studio Web UI"链接（如https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024）；
在Studio中可直接与LangGraph应用交互（如发送用户消息）、查看状态流转、调试工具调用逻辑；
若服务器使用自定义主机/端口（非默认localhost:2024），需手动修改链接中的baseUrl参数（如baseUrl=http://192.168.1.100:8080）。

7. 测试API接口（3种方式）

除可视化UI外，可通过Python SDK（同步/异步）或REST API直接调用本地服务器接口，验证应用功能。

方式1：Python SDK（异步）

安装LangGraph Python SDK：
bash 复制代码
```
pip install langgraph-sdk
```

发送异步请求（无对话线程，单次调用）：

python 复制代码

from langgraph_sdk import get_client
import asyncio

# 连接本地服务器
client = get_client(url="http://localhost:2024")

async def main():
    # 流式调用API，查询"What is LangGraph?"
    async for chunk in client.runs.stream(
        None,  # thread_id为None，表示"无线程"单次调用
        "agent",  # 智能体名称，在项目langgraph.json中定义
        input={
            "messages": [{"role": "human", "content": "What is LangGraph?"}]
        },
    ):
        print(f"接收事件类型: {chunk.event}...")
        print(chunk.data)
        print("\n\n")

# 执行异步函数
asyncio.run(main())

方式2：Python SDK（同步）

安装SDK（同上，已安装可跳过）；

发送同步请求：

python 复制代码

from langgraph_sdk import get_sync_client

# 连接本地服务器（同步客户端）
client = get_sync_client(url="http://localhost:2024")

# 流式调用API
for chunk in client.runs.stream(
    None,  # 无线程ID
    "agent",  # 智能体名称
    input={
        "messages": [{"role": "human", "content": "What is LangGraph?"}]
    },
    stream_mode="messages-tuple",  # 流式输出模式：按消息元组返回
):
    print(f"接收事件类型: {chunk.event}...")
    print(chunk.data)
    print("\n\n")

方式3：REST API（curl命令）

通过curl发送POST请求，直接调用API接口：

bash 复制代码

curl -s --request POST \
    --url "http://localhost:2024/runs/stream" \
    --header 'Content-Type: application/json' \
    --data "{
        \"assistant_id\": \"agent\",
        \"input\": {
            \"messages\": [
                {
                    \"role\": \"human\",
                    \"content\": \"What is LangGraph?\"
                }
            ]
        },
        \"stream_mode\": \"messages-tuple\"
    }"

assistant_id: 对应智能体名称（与SDK中的"agent"一致）；
stream_mode: 流式输出格式，此处为"消息元组"。

三、后续步骤

本地服务器运行成功后，可进一步探索LangGraph的部署与高级功能：

部署快速入门：通过LangGraph Platform将应用部署到生产环境（需配置持久化存储，如PostgreSQL）；
LangGraph Platform概述：学习平台核心概念（如多智能体协作、大规模部署优化等）；
API参考文档 ：访问http://localhost:2024/docs或官方文档，深入了解所有API的参数与使用场景；
Python SDK参考：探索SDK的更多功能（如对话线程管理、状态查询、批量调用等）。

四、关键注意事项

内存模式局限性 ：langgraph dev默认的内存模式下，服务器重启后所有状态（如对话历史、检查点）会丢失，生产环境需替换为SqliteSaver、PostgresSaver等持久化存储；
智能体名称配置 ：代码中使用的"agent"是默认智能体名称，可在项目根目录的langgraph.json中修改或新增智能体；
LangSmith的作用：LangSmith不仅提供API密钥，还用于追踪应用运行轨迹、调试错误、评估智能体性能，是LangGraph开发的重要辅助工具。