LangServe 部署指南
从本地开发到云端上线，一次讲清楚 LangServe 的完整部署流程
如果你已经用 LangChain / LangGraph 写过 Agent，那么下一步绕不开的问题一定是：
👉 “我怎么把这个 Agent 变成一个真正能被别人访问的服务？”
LangServe，正是为了解决这个问题而生的。
这篇文章会从整体架构到每一步实操，带你完成一次完整的 LangServe 部署流程，包括：
- 后端 API 服务（FastAPI + LangServe）
- 前端调用（Streamlit）
- 云端部署（DigitalOcean）
- 网络与安全配置
- 验证与测试
一、整体架构与核心概念
在正式动手之前，先用一句话理解整个系统的结构：
LangServe 负责把 LangChain / LangGraph 的“可运行对象”，包装成 HTTP API，对外提供服务。
整体可以拆成三层：
前端（Streamlit）
↓ HTTP
后端（FastAPI + LangServe）
↓
LangGraph / Chain / Agent
1️⃣ LangServe：API 包装器
LangServe 的作用不是“写 Agent”，而是：
- 把 Chain / Graph / Runnable
- 直接暴露成 REST API
- 自动生成
/invoke、/stream、/docs等接口
你可以把它理解为：
“专门为 LLM 应用设计的 API Server 插件”
2️⃣ FastAPI：后端 Web 框架
LangServe 本身并不是 Web Server，它是 基于 FastAPI 工作的：
- 路由管理
- 请求/响应模型
- 文档自动生成（Swagger）
所以部署 LangServe，本质上就是在部署一个 FastAPI 服务。
3️⃣ LangGraph：代理逻辑核心
如果你使用的是 多步骤 Agent / 状态机逻辑，LangGraph 非常适合：
- 节点（Node）= 一个处理步骤
- 边（Edge）= 状态流转
- 可控、可调试、可中断
最终，你会把一个 LangGraph Runnable 交给 LangServe 去暴露。
二、代码准备阶段
我们先从后端和前端代码结构开始。
三、后端部署（LangServe）
1️⃣ 定义 LangGraph 可运行对象
你的核心 Agent，最终必须是一个 Runnable。
示例逻辑：
- 定义 State
- 定义 Node 函数
- 构建 Graph
- 编译为 runnable
这是 LangServe 能识别并暴露的关键前提。
2️⃣ 使用 add_routes 绑定 API 路由
在 FastAPI 中，LangServe 提供了 add_routes 方法：
作用只有一个：
把 runnable 自动注册为一组 API 接口
逻辑上等价于：
/agent/invoke
/agent/stream
/agent/batch
你无需自己写 Controller。
3️⃣ 配置 uvicorn 运行参数
启动服务时，需要关注几个关键参数：
- host：
0.0.0.0（云服务器必须） - port：常见
8000 - reload：开发环境可开，生产关闭
这一步决定了你的服务是否能被外部访问。
四、前端调用（Streamlit）
前端的目标只有一个：
通过 HTTP 调用远程 LangServe，而不是本地运行 Agent
1️⃣ 导入 RemoteRunnable
LangServe 提供 RemoteRunnable：
- 用来“伪装”成一个本地 runnable
- 实际调用的是远程 API
这一步非常关键，它让前端和后端彻底解耦。
2️⃣ 配置服务端点 URL
你只需要提供：
http://<服务器IP>:8000/agent
之后所有 .invoke() 调用，都会自动走 HTTP。
3️⃣ 替换本地运行逻辑
原本代码：
agent.invoke(input)
替换为：
remote_agent.invoke(input)
前端代码几乎不用改。
五、云端部署（DigitalOcean）
当本地一切正常后，就可以上云了。
1️⃣ 创建 Droplet
推荐配置：
- Ubuntu（20.04 / 22.04）
- 基础套餐（$7/月足够）
- CPU 型即可（非 GPU）
2️⃣ 设置 SSH 或密码登录
建议：
- 使用 SSH Key
- 禁止 root 密码登录（后期）
这是后续安全的基础。
六、环境配置
进入服务器后，按顺序来。
1️⃣ 克隆 Git 仓库
git clone your-repo
cd your-repo
2️⃣ 创建虚拟环境（venv）
python3 -m venv venv
source venv/bin/activate
3️⃣ 安装 Python 依赖
pip install -r requirements.txt
4️⃣ 配置 .env 环境变量
包括但不限于：
- API Key
- 模型地址
- 环境标识
这是生产环境与代码解耦的关键一步。
七、网络安全配置
1️⃣ 启用 ufw 防火墙
ufw enable
2️⃣ 开放 8000 端口
ufw allow 8000
如果不开放，外部永远访问不到。
八、验证与测试
1️⃣ 访问 /docs
在浏览器打开：
http://<服务器IP>:8000/docs
你应该能看到：
- invoke
- stream
- batch
这说明 LangServe 已经正常运行。
2️⃣ 更新前端 API IP 地址
把前端的 URL 指向云服务器 IP。
3️⃣ 测试 Agent 功能
例如：
- 多轮对话
- 工具调用（如 Asana）
- 状态流转是否正确
九、总结
到这里，你已经完成了：
✅ Agent → Runnable
✅ Runnable → API
✅ API → 云端服务
✅ 前端 → 远程调用
