LangGraph 项目部署知识点总结

1. 部署概述

LangGraph 应用基于 LangSmith Deployment 构建，它建立在开源的 LangGraph 框架之上，用于开发有状态的应用程序。

• LangGraph 提供核心抽象和执行模型
• LangSmith 支持从开发到生产的整个生命周期，包括托管基础设施、可观察性、部署选项、助手和并发控制等。

整个流程将 Agent 应用打包、构建为 Agent Server，并进行部署。

---

2. 自托管部署的核心组件

组件	角色	功能
Agent Server	核心运行时环境	提供标准化 API，处理执行、状态管理和持久化
LangGraph CLI	命令行工具	本地构建、打包图，并为部署做准备
Studio	集成开发环境	可视化、交互和调试图，可连接本地 Agent Server
Python SDK（自行了解）	开发工具包	编程接口，与已部署的图和 Agent Server 交互
RemoteGraph（自行了解）	本地代理包装器	像调用本地图一样调用远程部署的图
Control Plane（自行了解）	管理和配置层	创建、更新和管理 Agent Server 部署的 UI/API
Data plane（自行了解）	执行层	实际运行图的运行时层，包含 Agent Server 实例及后端（PostgreSQL、Redis 等）

开发者使用 CLI 和 Studio 在本地开发测试图，然后部署为 Agent Server。应用程序通过 SDK、RemoteGraph 或 Agent Server 提供的 API 调用服务。

---

3. 本地启动与测试

3.1 修改 langgraph.json 配置文件

在配置文件中添加新增的图：

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "house_agent": "./src/agent/graph.py:graph",
    "recommend_agent": "./src/agent/recommend.py:recommended_graph",
    "reserve_agent": "./src/agent/reserve.py:reserve_graph",
    "extend_agent": "./src/agent/extend.py:extend_graph"
  },
  "env": ".env",
  "image_distro": "wolfi"
}

3.2 启动本地开发服务器

langgraph dev

• 该命令以内存模式启动 Agent Server，适合开发和测试。
• 启动后会提供 API 和 Studio UI 的访问地址。

3.3 测试 Graph

通过 Studio 或 API 发送测试问题，例如：

在西安，我的预算是1000-2000一个月，帮我推荐4套房子。要求在雁塔区。
我想在北京海淀租个1室1厅1卫，预算5000以内，最好近地铁。
帮我推荐几套房子   # 会触发信息收集中断

---

4. LangSmith 部署方式

Agent Server 可根据基础设施采用不同部署方式：

方式	说明
云部署（自行研究）	完全托管模式，LangChain 负责基础设施、更新、扩展；从 GitHub 部署；自动 CI/CD；全面访问 LangSmith UI
带 Control Plane 的混合/自托管（自行研究）	本地构建 Docker 镜像，推送到注册表，通过 LangSmith UI 部署到 Kubernetes
独立服务器（本文重点）	直接部署 Agent Server，不通过 Control Plane 和 LangSmith UI，作为独立服务运行

---

5. 独立部署 Agent Server（详细步骤）

5.1 工作流程

1. 使用 CLI 或 Studio 在本地定义和测试图
2. 将应用服务打包为 Docker 镜像
3. 将 Agent Server 部署到平台：
   • Kubernetes：使用 LangSmith Helm 图表（生产推荐）
   • Docker：在本地开发机、VM、ECS 等运行（适合开发或小规模）

5.2 部署前准备工作

Agent Server 部署时需要以下组件：

• PostgreSQL：作为数据库，存储所有持久化数据（检查点、助手等）
• Redis：作为任务队列，用于发布/订阅连接，实现事件实时流传输

若使用 LangSmith 云部署，这些组件自动管理；独立部署需自行搭建。

启动 Redis 容器（示例）

sudo docker run -d \
  --name redis-6380 \
  -p 6380:6379 \
  -v redis-data:/data \
  redis:7-alpine \
  redis-server --appendonly yes --requirepass "your_password"

启动 PostgreSQL 容器（示例）

docker pull postgres:latest
docker run --name postgres-sql -e POSTGRES_PASSWORD=bit -p 5432:5432 -d postgres

配置 .env 文件

# DOCKER 必须
DATABASE_URI=postgresql://postgres:bit@192.168.100.233:5432/postgres
REDIS_URI=redis://:bite%40123@192.168.100.233:6380

---

5.3 部署姿势 1：构建 Docker 镜像并运行

使用 langgraph build 命令构建镜像。

sudo langgraph build -t house-agent-image

查看镜像：

sudo docker image list
# REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
# house-agent-image   latest    7884c6e8d937   39 minutes ago 626MB

运行容器（指定 .env 文件，映射端口）：

sudo docker run --env-file .env -p 8001:8000 house-agent-image
# Starting API server

• 默认端口为 8000
• 必须设置 REDIS_URI 和 DATABASE_URI

---

5.4 部署姿势 2：生成 Dockerfile 并组合 Docker Compose

生成 Dockerfile

sudo langgraph dockerfile -c langgraph.json Dockerfile

该命令将 langgraph.json 中的配置转换成 Dockerfile 命令。每次更新 langgraph.json 后需重新运行。

编写 Docker Compose 文件

方案一：仅包含服务（使用已有的 Redis 和 PostgreSQL）

volumes:
  langgraph-data:
    driver: local
services:
  langgraph-api:
    build: .
    ports:
      - "8002:8000"
    env_file:
      - .env

方案二：完整包含 Redis + PostgreSQL + Agent Server

volumes:
  langgraph-data:
    driver: local
services:
  langgraph-redis:
    image: redis:6
    healthcheck:
      test: redis-cli ping
      interval: 5s
      timeout: 1s
      retries: 5
  langgraph-postgres:
    image: postgres:16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - langgraph-data:/var/lib/postgresql/data
    healthcheck:
      test: pg_isready -U postgres
      start_period: 10s
      timeout: 1s
      retries: 5
      interval: 5s
  langgraph-api:
    image: ${IMAGE_NAME}   # 需提前构建镜像
    ports:
      - "8123:8000"
    depends_on:
      langgraph-redis:
        condition: service_healthy
      langgraph-postgres:
        condition: service_healthy
    env_file:
      - .env
    environment:
      REDIS_URI: redis://langgraph-redis:6379
      LANGSMITH_API_KEY: ${LANGSMITH_API_KEY}
      DATABASE_URI: postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable

启动服务

sudo docker compose up
# 源代码更新后可重新构建
sudo docker compose up --build 服务名

---

5.5 部署姿势 3：使用 langgraph up 命令

sudo langgraph up -p 8000

• 该命令依赖 Docker，会构建并启动 LangGraph API 服务
• 查看镜像：

sudo docker image list
# REPOSITORY              TAG       IMAGE ID       CREATED        SIZE
# house-langgraph-api     latest    90ae2bcbab92   39 minutes ago 626MB

可能遇到的问题

• 若 .env 中 DATABASE_URI 指向与之前本地使用的 PostgreSQL 同一库，可能导致数据库迁移失败 。
  原因：checkpoints 表的 thread_id 为 text 类型，而 thread 表的 thread_id 为 uuid 类型，类型不一致无法建立外键关系。
  解决方案：新建一个数据库，实现环境隔离。

---

6. 配置文件关键说明

6.1 langgraph.json 主要字段（总结）

字段	必需	描述
$schema	是	Schema 验证 URL
dependencies	是	依赖项（如 . 表示本地包，或路径、包名）
graphs	是	图定义映射，格式 {"图ID": "文件路径:导出对象"}
auth	否	自定义认证配置
base_image	否	基础 Docker 镜像
image_distro	否	Linux 发行版（debian/wolfi/bookworm/bullseye）
env	否	环境变量（文件路径或键值对）
store	否	存储配置（语义搜索索引、TTL）
checkpointer	否	检查点配置（TTL、序列化）
http	否	HTTP 服务器配置（CORS、中间件等）
webhooks	否	出站 Webhook 配置
python_version	否	Python 版本（3.11/3.12/3.13）
node_version	否	Node.js 版本
pip_installer	否	包安装器（auto/pip/uv）
api_version	否	LangGraph API 服务器语义版本

6.2 .env 环境变量（示例）

LANGSMITH_PROJECT=new-agent2
LANGSMITH_API_KEY=lsv2...
LANGSMITH_TRACING=true
OPENAI_API_KEY=...
DATABASE_URI=postgresql://...
REDIS_URI=redis://...

---

7. 项目扩展（自行研究，简要提及）

PDF 最后列举了可进一步探索的方向：

1. 主图中进行消息管理：在适当位置进行历史会话修剪、总结，避免消息过多导致 LLM 调用错误。
2. 结构化输出用户期望信息：与数据库表字段映射，生成更准确的 SQL。
3. 执行 SQL 前加入中断：人工审核 SQL 准确性。
4. 自定义流式输出：前端展示更详细、流式的执行过程。

---

8. 总结

• LangGraph 项目部署依赖 Agent Server + PostgreSQL + Redis。
• 本地开发使用 langgraph dev 快速测试。
• 独立部署可通过构建 Docker 镜像并运行，或使用 dockerfile + docker compose，或 langgraph up 命令。
• 必须正确配置 langgraph.json 和 .env，注意数据库迁移时的类型兼容问题。
• 部署后可通过 API 或 Studio 与 Agent Server 交互，实现完整的智能应用生命周期管理。