1. 部署概述LangGraph 应用基于LangSmith Deployment构建它建立在开源的 LangGraph 框架之上用于开发有状态的应用程序。LangGraph 提供核心抽象和执行模型LangSmith 支持从开发到生产的整个生命周期包括托管基础设施、可观察性、部署选项、助手和并发控制等。整个流程将 Agent 应用打包、构建为Agent Server并进行部署。2. 自托管部署的核心组件组件角色功能Agent Server核心运行时环境提供标准化 API处理执行、状态管理和持久化LangGraph CLI命令行工具本地构建、打包图并为部署做准备Studio集成开发环境可视化、交互和调试图可连接本地 Agent ServerPython SDK自行了解开发工具包编程接口与已部署的图和 Agent Server 交互RemoteGraph自行了解本地代理包装器像调用本地图一样调用远程部署的图Control Plane自行了解管理和配置层创建、更新和管理 Agent Server 部署的 UI/APIData 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 工作流程使用 CLI 或 Studio 在本地定义和测试图将应用服务打包为Docker 镜像将 Agent Server 部署到平台Kubernetes使用 LangSmith Helm 图表生产推荐Docker在本地开发机、VM、ECS 等运行适合开发或小规模5.2 部署前准备工作Agent Server 部署时需要以下组件PostgreSQL作为数据库存储所有持久化数据检查点、助手等Redis作为任务队列用于发布/订阅连接实现事件实时流传输若使用 LangSmith 云部署这些组件自动管理独立部署需自行搭建。启动 Redis 容器示例sudodockerrun-d\--nameredis-6380\-p6380:6379\-vredis-data:/data\redis:7-alpine\redis-server--appendonlyyes--requirepassyour_password启动 PostgreSQL 容器示例dockerpull postgres:latestdockerrun--namepostgres-sql-ePOSTGRES_PASSWORDbit-p5432:5432-dpostgres配置.env文件# DOCKER 必须 DATABASE_URIpostgresql://postgres:bit192.168.100.233:5432/postgres REDIS_URIredis://:bite%40123192.168.100.233:63805.3 部署姿势 1构建 Docker 镜像并运行使用langgraph build命令构建镜像。sudolanggraph build-thouse-agent-image查看镜像sudodockerimage list# REPOSITORY TAG IMAGE ID CREATED SIZE# house-agent-image latest 7884c6e8d937 39 minutes ago 626MB运行容器指定.env文件映射端口sudodockerrun --env-file .env-p8001:8000 house-agent-image# Starting API server默认端口为 8000必须设置REDIS_URI和DATABASE_URI5.4 部署姿势 2生成 Dockerfile 并组合 Docker Compose生成 Dockerfilesudolanggraph dockerfile-clanggraph.json Dockerfile该命令将langgraph.json中的配置转换成 Dockerfile 命令。每次更新langgraph.json后需重新运行。编写 Docker Compose 文件方案一仅包含服务使用已有的 Redis 和 PostgreSQLvolumes:langgraph-data:driver:localservices:langgraph-api:build:.ports:-8002:8000env_file:-.env方案二完整包含 Redis PostgreSQL Agent Servervolumes:langgraph-data:driver:localservices:langgraph-redis:image:redis:6healthcheck:test:redis-cli pinginterval:5stimeout:1sretries:5langgraph-postgres:image:postgres:16ports:-5432:5432environment:POSTGRES_DB:postgresPOSTGRES_USER:postgresPOSTGRES_PASSWORD:postgresvolumes:-langgraph-data:/var/lib/postgresql/datahealthcheck:test:pg_isready-U postgresstart_period:10stimeout:1sretries:5interval:5slanggraph-api:image:${IMAGE_NAME}# 需提前构建镜像ports:-8123:8000depends_on:langgraph-redis:condition:service_healthylanggraph-postgres:condition:service_healthyenv_file:-.envenvironment:REDIS_URI:redis://langgraph-redis:6379LANGSMITH_API_KEY:${LANGSMITH_API_KEY}DATABASE_URI:postgres://postgres:postgreslanggraph-postgres:5432/postgres?sslmodedisable启动服务sudodockercompose up# 源代码更新后可重新构建sudodockercompose up--build服务名5.5 部署姿势 3使用langgraph up命令sudolanggraph up-p8000该命令依赖 Docker会构建并启动 LangGraph API 服务查看镜像sudodockerimage 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.1langgraph.json主要字段总结字段必需描述$schema是Schema 验证 URLdependencies是依赖项如.表示本地包或路径、包名graphs是图定义映射格式{图ID: 文件路径:导出对象}auth否自定义认证配置base_image否基础 Docker 镜像image_distro否Linux 发行版debian/wolfi/bookworm/bullseyeenv否环境变量文件路径或键值对store否存储配置语义搜索索引、TTLcheckpointer否检查点配置TTL、序列化http否HTTP 服务器配置CORS、中间件等webhooks否出站 Webhook 配置python_version否Python 版本3.11/3.12/3.13node_version否Node.js 版本pip_installer否包安装器auto/pip/uvapi_version否LangGraph API 服务器语义版本6.2.env环境变量示例LANGSMITH_PROJECTnew-agent2 LANGSMITH_API_KEYlsv2... LANGSMITH_TRACINGtrue OPENAI_API_KEY... DATABASE_URIpostgresql://... REDIS_URIredis://...7. 项目扩展自行研究简要提及PDF 最后列举了可进一步探索的方向主图中进行消息管理在适当位置进行历史会话修剪、总结避免消息过多导致 LLM 调用错误。结构化输出用户期望信息与数据库表字段映射生成更准确的 SQL。执行 SQL 前加入中断人工审核 SQL 准确性。自定义流式输出前端展示更详细、流式的执行过程。8. 总结LangGraph 项目部署依赖Agent ServerPostgreSQLRedis。本地开发使用langgraph dev快速测试。独立部署可通过构建 Docker 镜像并运行或使用dockerfiledocker compose或langgraph up命令。必须正确配置langgraph.json和.env注意数据库迁移时的类型兼容问题。部署后可通过 API 或 Studio 与 Agent Server 交互实现完整的智能应用生命周期管理。
LangGraph 项目部署知识点总结
1. 部署概述LangGraph 应用基于LangSmith Deployment构建它建立在开源的 LangGraph 框架之上用于开发有状态的应用程序。LangGraph 提供核心抽象和执行模型LangSmith 支持从开发到生产的整个生命周期包括托管基础设施、可观察性、部署选项、助手和并发控制等。整个流程将 Agent 应用打包、构建为Agent Server并进行部署。2. 自托管部署的核心组件组件角色功能Agent Server核心运行时环境提供标准化 API处理执行、状态管理和持久化LangGraph CLI命令行工具本地构建、打包图并为部署做准备Studio集成开发环境可视化、交互和调试图可连接本地 Agent ServerPython SDK自行了解开发工具包编程接口与已部署的图和 Agent Server 交互RemoteGraph自行了解本地代理包装器像调用本地图一样调用远程部署的图Control Plane自行了解管理和配置层创建、更新和管理 Agent Server 部署的 UI/APIData 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 工作流程使用 CLI 或 Studio 在本地定义和测试图将应用服务打包为Docker 镜像将 Agent Server 部署到平台Kubernetes使用 LangSmith Helm 图表生产推荐Docker在本地开发机、VM、ECS 等运行适合开发或小规模5.2 部署前准备工作Agent Server 部署时需要以下组件PostgreSQL作为数据库存储所有持久化数据检查点、助手等Redis作为任务队列用于发布/订阅连接实现事件实时流传输若使用 LangSmith 云部署这些组件自动管理独立部署需自行搭建。启动 Redis 容器示例sudodockerrun-d\--nameredis-6380\-p6380:6379\-vredis-data:/data\redis:7-alpine\redis-server--appendonlyyes--requirepassyour_password启动 PostgreSQL 容器示例dockerpull postgres:latestdockerrun--namepostgres-sql-ePOSTGRES_PASSWORDbit-p5432:5432-dpostgres配置.env文件# DOCKER 必须 DATABASE_URIpostgresql://postgres:bit192.168.100.233:5432/postgres REDIS_URIredis://:bite%40123192.168.100.233:63805.3 部署姿势 1构建 Docker 镜像并运行使用langgraph build命令构建镜像。sudolanggraph build-thouse-agent-image查看镜像sudodockerimage list# REPOSITORY TAG IMAGE ID CREATED SIZE# house-agent-image latest 7884c6e8d937 39 minutes ago 626MB运行容器指定.env文件映射端口sudodockerrun --env-file .env-p8001:8000 house-agent-image# Starting API server默认端口为 8000必须设置REDIS_URI和DATABASE_URI5.4 部署姿势 2生成 Dockerfile 并组合 Docker Compose生成 Dockerfilesudolanggraph dockerfile-clanggraph.json Dockerfile该命令将langgraph.json中的配置转换成 Dockerfile 命令。每次更新langgraph.json后需重新运行。编写 Docker Compose 文件方案一仅包含服务使用已有的 Redis 和 PostgreSQLvolumes:langgraph-data:driver:localservices:langgraph-api:build:.ports:-8002:8000env_file:-.env方案二完整包含 Redis PostgreSQL Agent Servervolumes:langgraph-data:driver:localservices:langgraph-redis:image:redis:6healthcheck:test:redis-cli pinginterval:5stimeout:1sretries:5langgraph-postgres:image:postgres:16ports:-5432:5432environment:POSTGRES_DB:postgresPOSTGRES_USER:postgresPOSTGRES_PASSWORD:postgresvolumes:-langgraph-data:/var/lib/postgresql/datahealthcheck:test:pg_isready-U postgresstart_period:10stimeout:1sretries:5interval:5slanggraph-api:image:${IMAGE_NAME}# 需提前构建镜像ports:-8123:8000depends_on:langgraph-redis:condition:service_healthylanggraph-postgres:condition:service_healthyenv_file:-.envenvironment:REDIS_URI:redis://langgraph-redis:6379LANGSMITH_API_KEY:${LANGSMITH_API_KEY}DATABASE_URI:postgres://postgres:postgreslanggraph-postgres:5432/postgres?sslmodedisable启动服务sudodockercompose up# 源代码更新后可重新构建sudodockercompose up--build服务名5.5 部署姿势 3使用langgraph up命令sudolanggraph up-p8000该命令依赖 Docker会构建并启动 LangGraph API 服务查看镜像sudodockerimage 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.1langgraph.json主要字段总结字段必需描述$schema是Schema 验证 URLdependencies是依赖项如.表示本地包或路径、包名graphs是图定义映射格式{图ID: 文件路径:导出对象}auth否自定义认证配置base_image否基础 Docker 镜像image_distro否Linux 发行版debian/wolfi/bookworm/bullseyeenv否环境变量文件路径或键值对store否存储配置语义搜索索引、TTLcheckpointer否检查点配置TTL、序列化http否HTTP 服务器配置CORS、中间件等webhooks否出站 Webhook 配置python_version否Python 版本3.11/3.12/3.13node_version否Node.js 版本pip_installer否包安装器auto/pip/uvapi_version否LangGraph API 服务器语义版本6.2.env环境变量示例LANGSMITH_PROJECTnew-agent2 LANGSMITH_API_KEYlsv2... LANGSMITH_TRACINGtrue OPENAI_API_KEY... DATABASE_URIpostgresql://... REDIS_URIredis://...7. 项目扩展自行研究简要提及PDF 最后列举了可进一步探索的方向主图中进行消息管理在适当位置进行历史会话修剪、总结避免消息过多导致 LLM 调用错误。结构化输出用户期望信息与数据库表字段映射生成更准确的 SQL。执行 SQL 前加入中断人工审核 SQL 准确性。自定义流式输出前端展示更详细、流式的执行过程。8. 总结LangGraph 项目部署依赖Agent ServerPostgreSQLRedis。本地开发使用langgraph dev快速测试。独立部署可通过构建 Docker 镜像并运行或使用dockerfiledocker compose或langgraph up命令。必须正确配置langgraph.json和.env注意数据库迁移时的类型兼容问题。部署后可通过 API 或 Studio 与 Agent Server 交互实现完整的智能应用生命周期管理。
