使用 LangSmith 部署和评估实现 CI/CD 管道

​

概览

• 自动化测试：单元测试、集成测试和端到端测试。
• 离线评估：使用 AgentEvals、OpenEvals 和 LangSmith 进行性能评估。
• 预览和生产部署：使用控制平面 API 进行自动化分段和质量门控生产发布。
• 监控：持续评估和警报。

​

管道架构

​

触发源

• 代码更改：推送到主/开发分支，您可以在其中修改 LangGraph 架构、尝试不同的模型、更新代理逻辑或进行任何代码改进。
• PromptHub 更新：对 LangSmith PromptHub 中存储的提示模板进行更改——每当有新的提示提交时，系统都会触发 webhook 来运行管道。
• 在线评估警报：来自实时部署的性能下降通知
• LangSmith 跟踪 Webhook：基于跟踪分析和性能指标的自动化触发器。
• 手动触发：手动启动管道以进行测试或紧急部署。

​

测试层

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

​

GitHub Actions 工作流

• 新代理部署：当新的 PR 打开且测试通过时，将使用 控制平面 API 在 LangSmith Deployments 中创建一个新的预览部署。这允许您在提升到生产环境之前在暂存环境中测试代理。
• 代理部署修订：当找到具有相同 ID 的现有部署时，或者当 PR 合并到主分支时，会发生修订。在合并到主分支的情况下，预览部署将被删除，并创建生产部署。这确保了对代理的任何更新都已正确部署并集成到生产基础设施中。
• 测试和评估工作流：除了更传统的测试阶段（单元测试、集成测试、端到端测试等），管道还包括 离线评估 和 LangGraph 开发服务器测试，因为您需要测试代理的质量。这些评估使用真实世界场景和数据对代理的性能进行全面评估。
  最终响应评估

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

  单步评估

  测试 LangGraph 工作流中的单个步骤或节点。这允许您独立验证代理逻辑的特定组件，确保每个步骤在测试完整管道之前都能正常运行。

  代理轨迹评估

  分析代理通过图的完整路径，包括所有中间步骤和决策点。这有助于识别代理工作流中的瓶颈、不必要的步骤或次优路由。它还评估代理是否以正确的顺序或在正确的时间调用了正确的工具。

  多轮评估

  测试代理在多个交互中保持上下文的对话流。这对于处理后续问题、澄清或与用户进行长时间对话的代理至关重要。
  有关特定测试方法，请参阅 LangGraph 测试文档；有关离线评估的全面概述，请参阅 评估方法指南。

​

先决条件

• 一个 AI 代理应用程序（在本例中是使用 LangGraph 构建的）
• 一个 LangSmith 帐户
• 一个 LangSmith API 密钥，用于部署代理和检索实验结果
• 在您的仓库密钥中配置了项目特定的环境变量（例如，LLM 模型 API 密钥、向量存储凭据、数据库连接）

​

部署选项

• 云端 LangSmith：直接 GitHub 集成或 Docker 镜像部署。
• 自托管/混合：基于容器注册表的部署。

​

手动部署的先决条件

1. LangGraph 图：您的代理实现（例如，./agents/simple_text2sql.py:agent）。
2. 依赖项：包含所有必需包的 requirements.txt 或 pyproject.toml。
3. 配置：langgraph.json 文件，指定
   • 您的代理图的路径
   • 依赖项位置
   • 环境变量
   • Python 版本

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

​

本地开发和测试

# Start local development server with LangGraph Studio
langgraph dev

• 启动一个带有 Studio 的本地服务器。
• 允许您可视化您的图并与之交互。
• 在部署之前验证您的代理是否正常工作。

​

方法 1：LangSmith 部署 UI

1. 访问您的 LangSmith 控制面板。
2. 导航到部署部分。
3. 点击右上角的+ 新建部署按钮。
4. 从下拉菜单中选择包含您的 LangGraph 代理的 GitHub 仓库。

• 云端 LangSmith：直接与 GitHub 集成，带有下拉菜单
• 自托管/混合 LangSmith：在图像路径字段中指定您的图像 URI（例如，docker.io/username/my-agent:latest）

​

方法 2：控制平面 API

• 使用控制平面 API 通过指向您的 GitHub 仓库来创建部署
• 云端部署无需构建 Docker 镜像

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

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

• 云端 LangSmith：使用控制平面 API 从您的 GitHub 仓库创建部署
• 自托管/混合 LangSmith：使用控制平面 API 从您的容器注册表创建部署

​

连接到您部署的代理

• LangGraph SDK：使用 LangGraph SDK 进行程序化集成。
• RemoteGraph：使用 RemoteGraph 进行远程图连接（在其他图中使用您的图）。
• REST API：使用基于 HTTP 的交互与您部署的代理进行交互。
• 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 部署 API (部署)