使用 LangSmith Deployment 和 Evaluation 实现 CI/CD 流水线

​

概览

• 自动化测试：单元测试、集成测试和端到端测试。
• 离线评估：使用 AgentEvals、OpenEvals 和 LangSmith 评估性能。
• 预览环境和生产环境部署：使用 Control Plane API 自动部署到预发布环境，并在质量门禁通过后发布到生产环境。
• 监控：持续评估和告警。

​

流水线架构

​

触发源

• 代码更改：向 main/development 分支推送代码，包括修改 LangGraph 架构、尝试不同模型、更新 Agent 逻辑或进行其他代码改进。
• PromptHub 更新：存储在 LangSmith PromptHub 中的提示词模板发生更改时触发。每当有新的提示词提交，系统都会触发 Webhook 来运行流水线。
• 在线评估告警：来自线上部署的性能下降通知。
• LangSmith 追踪记录 Webhook：基于追踪记录分析和性能指标的自动触发器。
• 手动触发：手动启动流水线，用于测试或紧急部署。

​

测试层级

1. 单元测试：测试单个节点和工具函数。
2. 集成测试：测试组件之间的交互。
3. 端到端测试：测试完整的 Graph 执行过程。
4. 离线评估：使用真实场景评估性能，包括端到端评估、单步评估、Agent 轨迹分析和多轮模拟。
5. LangGraph 开发服务器测试：使用 langgraph-cli 工具在本地启动服务器（在 GitHub Action 内部），以运行 LangGraph Agent。该工具会持续轮询服务器的 /ok API 端点，直到端点可用；如果 30 秒后仍不可用，则会抛出错误。

​

GitHub Actions 工作流

• 新 Agent 部署：当新的 PR 创建且测试通过后，使用 Control Plane API 在 LangSmith Deployment 中创建新的预览部署。这样，你可以先在预发布环境中测试 Agent，再将其晋升到生产环境。
• Agent 部署修订：当发现具有相同 ID 的现有部署，或 PR 合并到 main 分支时，就会创建修订。当代码合并到 main 分支时，系统会删除预览部署并创建生产部署。这样可以确保 Agent 的所有更新都能正确部署，并集成到生产基础设施中。
• 测试和评估工作流：除更传统的测试阶段（单元测试、集成测试、端到端测试等）外，流水线还包括离线评估和 Agent 开发服务器测试，因为你需要测试 Agent 的质量。这些评估使用真实场景和数据，对 Agent 的性能进行全面评估。
  最终响应评估

  根据预期结果评估 Agent 的最终输出。这是最常见的评估类型，用于检查 Agent 的最终响应是否符合质量标准，以及是否正确回答了用户的问题。

  单步评估

  测试 LangGraph 工作流中的单个步骤或节点。这样可以单独验证 Agent 逻辑中的特定组件，确保每个步骤在测试完整流水线之前都能正常运行。

  Agent 轨迹评估

  分析 Agent 在 Graph 中执行的完整路径，包括所有中间步骤和决策点。这有助于识别 Agent 工作流中的瓶颈、不必要的步骤或非最优路由。同时，它还会评估 Agent 是否以正确的顺序或在正确的时间调用了正确的工具。

  多轮评估

  测试 Agent 在多次交互中保持上下文的对话流程。对于需要处理后续问题、澄清请求或与用户进行长时间对话的 Agent，这一点非常重要。
  请参阅 LangGraph 测试文档，了解具体的测试方法；参阅评估方法指南，全面了解离线评估。

​

前置条件

• 一个 AI Agent 应用（本示例使用 LangGraph 构建）
• 一个 LangSmith 账户
• 一个 LangSmith API 密钥，用于部署 Agent 和获取实验结果
• 已在仓库密钥中配置项目所需的环境变量（例如 LLM 模型 API 密钥、向量存储凭据和数据库连接信息）

​

部署选项

• Cloud LangSmith：直接集成 GitHub。
• Self-Hosted/Hybrid：基于容器注册表进行部署。

​

手动部署的前置条件

1. LangGraph Graph：Agent 实现（例如 ./agents/simple_text2sql.py:agent）。
2. 依赖项：包含所有必需软件包的 requirements.txt 或 pyproject.toml。
3. 配置：用于指定以下内容的 langgraph.json 文件：
   • Agent Graph 的路径
   • 依赖项位置
   • 环境变量
   • Python 版本

{
    "graphs": {
        "simple_text2sql": "./agents/simple_text2sql.py:agent"
    },
    "env": ".env",
    "python_version": "3.11",
    "dependencies": ["."],
    "image_distro": "wolfi"
}

​

本地开发和测试

# Start local development server with Studio
langgraph dev

• 使用 Studio 启动本地服务器。
• 让你能够可视化并与 Graph 交互。
• 在部署前验证 Agent 是否正常工作。

​

方法 1：LangSmith Deployment UI

1. 前往 LangSmith 控制台。
2. 进入 Deployments 部分。
3. 点击右上角的 + New Deployment 按钮。
4. 从下拉菜单中选择包含 LangGraph Agent 的 GitHub 仓库。

• Cloud LangSmith：通过下拉菜单直接集成 GitHub
• Self-Hosted/Hybrid LangSmith：在 Image Path 字段中指定镜像 URI（例如 docker.io/username/my-agent:latest）

​

方法 2：Control Plane API

• 使用 Control Plane API，通过指定 GitHub 仓库来创建部署
• 云端部署无需构建 Docker 镜像

# Build Docker image
langgraph build -t my-agent:latest

# Push to your container registry
docker push my-agent:latest

• Cloud LangSmith：使用 Control Plane API 从 GitHub 仓库创建部署
• Self-Hosted/Hybrid LangSmith：使用 Control Plane API 从容器注册表创建部署

​

连接到已部署的 Agent

• LangGraph SDK：使用 LangGraph SDK 进行编程集成。
• RemoteGraph：使用 RemoteGraph 连接远程 Graph（以便在其他 Graph 中使用你的 Graph）。
• REST API：使用基于 HTTP 的方式与已部署的 Agent 交互。
• Studio：访问可视化界面，用于测试和调试。

​

环境配置

​

数据库和缓存配置

# Set environment variables for external services
export POSTGRES_URI_CUSTOM="postgresql://user:pass@host:5432/db"
export REDIS_URI_CUSTOM="redis://host:6379/0"

​

故障排除

​

API 端点错误

​

LangSmith API（追踪记录、数据摄取等）

​

LangSmith Deployment API（部署）