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

本指南演示如何为部署在 LangSmith 部署中的 AI 代理应用程序实现全面的 CI/CD 管道。在此示例中，您将使用 LangGraph 开源框架来编排和构建代理，使用 LangSmith 进行可观测性和评估。此管道基于 cicd-pipeline-example 仓库。

概述

CI/CD 管道提供：

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

管道架构

CI/CD 管道由几个关键组件组成，它们协同工作以确保代码质量和可靠的部署：

触发源

您可以通过多种方式触发此管道，无论是在开发期间还是在应用程序已上线时。管道可以由以下方式触发：

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

测试层

与传统软件相比，测试 AI 代理应用程序还需要评估响应质量，因此测试工作流的每个部分都很重要。该管道实现了多个测试层：

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

GitHub actions 工作流

CI/CD 管道使用 GitHub Actions 与控制平面 API 和 LangSmith API 来自动化部署。一个辅助脚本管理 API 交互和部署：https://github.com/langchain-ai/cicd-pipeline-example/blob/main/.github/scripts/langgraph_api.py。该工作流包括：

新代理部署：当打开新的 PR 并且测试通过时，使用控制平面 API 在 LangSmith 部署中创建一个新的预览部署。这允许您在将代理提升到生产环境之前，在暂存环境中对其进行测试。
代理部署修订：当找到具有相同 ID 的现有部署，或者当 PR 合并到主分支时，会发生修订。在合并到主分支的情况下，预览部署将被删除，并创建一个生产部署。这确保了对代理的任何更新都被正确部署并集成到生产基础设施中。
测试和评估工作流：除了更传统的测试阶段（单元测试、集成测试、端到端测试等）之外，管道还包括离线评估和代理开发服务器测试，因为您想要测试代理的质量。这些评估使用真实场景和数据对代理的性能进行全面评估。
最终响应评估
根据预期结果评估代理的最终输出。这是最常见的评估类型，检查代理的最终响应是否符合质量标准并正确回答用户的问题。
单步评估
测试 LangGraph 工作流中的单个步骤或节点。这允许您单独验证代理逻辑的特定组件，确保每个步骤在测试完整管道之前都能正常工作。
代理轨迹评估
分析代理在图中采取的完整路径，包括所有中间步骤和决策点。这有助于识别代理工作流中的瓶颈、不必要的步骤或次优路由。它还评估您的代理是否在正确的时间以正确的顺序调用了正确的工具。
多轮评估
测试代理在多次交互中保持上下文的对话流程。这对于处理后续问题、澄清或与用户进行扩展对话的代理至关重要。
有关具体的测试方法，请参阅 LangGraph 测试文档，有关离线评估的全面概述，请参阅评估方法指南。

先决条件

在设置 CI/CD 管道之前，请确保您拥有：

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

虽然此示例使用 GitHub，但 CI/CD 管道也适用于其他 Git 托管平台，包括 GitLab、Bitbucket 等。

部署选项

LangSmith 支持多种部署方法，具体取决于您的 LangSmith 实例的托管方式：

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

部署流程从修改您的代理实现开始。至少，您的项目中必须有一个 langgraph.json 和依赖文件（requirements.txt 或 pyproject.toml）。使用 langgraph dev CLI 工具检查错误——修复任何错误；否则，部署到 LangSmith 部署时将会成功。

手动部署的先决条件

在部署代理之前，请确保您拥有：

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

示例 langgraph.json：

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

本地开发和测试

首先，使用 Studio 在本地测试您的代理：

# 使用 Studio 启动本地开发服务器
langgraph dev

这将：

使用 Studio 启动一个本地服务器。
允许您可视化和交互您的图。
在部署前验证您的代理是否正常工作。

如果您的代理在本地运行没有任何错误，则意味着部署到 LangSmith 很可能会成功。这种本地测试有助于在尝试部署之前捕获配置问题、依赖项问题和代理逻辑错误。

有关更多详细信息，请参阅 LangGraph CLI 文档。

方法 1：LangSmith 部署 UI

使用 LangSmith 部署界面部署您的代理：

转到您的 LangSmith 仪表板。
导航到 Deployments 部分。
单击右上角的 + New Deployment 按钮。
从下拉菜单中选择包含您的 LangGraph 代理的 GitHub 仓库。

支持的部署：

云 LangSmith：通过下拉菜单直接 GitHub 集成
自托管/混合 LangSmith：在 Image Path 字段中指定您的镜像 URI（例如，docker.io/username/my-agent:latest）

优点：

基于 UI 的简单部署
与您的 GitHub 仓库直接集成（云）
无需手动管理 Docker 镜像（云）

方法 2：控制平面 API

使用控制平面 API 进行部署，针对每种部署类型采用不同的方法： 对于云 LangSmith：

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

对于自托管/混合 LangSmith：

# 构建 Docker 镜像
langgraph build -t my-agent:latest

# 推送到您的容器注册表
docker push my-agent:latest

您可以推送到您的部署环境可以访问的任何容器注册表（Docker Hub、AWS ECR、Azure ACR、Google GCR 等）。 支持的部署：

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

有关更多详细信息，请参阅 LangGraph CLI 构建文档。

连接到已部署的代理

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

环境配置

数据库和缓存配置

默认情况下，LangSmith 部署会为您创建 PostgreSQL 和 Redis 实例。要使用外部服务，请在新的部署或修订中设置以下环境变量：

# 为外部服务设置环境变量
export POSTGRES_URI_CUSTOM="postgresql://user:pass@host:5432/db"
export REDIS_URI_CUSTOM="redis://host:6379/0"

有关更多详细信息，请参阅环境变量文档。

故障排除

错误的 API 端点

如果您遇到连接问题，请验证您是否使用了适用于您的 LangSmith 实例的正确端点格式。有两个不同的 API，具有不同的端点：

LangSmith API（跟踪、摄取等）

对于 LangSmith API 操作（跟踪、评估、数据集）：

区域	端点
美国 (GCP)	`https://api.smith.langchain.com`
欧盟 (GCP)	`https://eu.api.smith.langchain.com`
美国 (AWS)	`https://aws.api.smith.langchain.com`

对于自托管 LangSmith 实例，使用 http(s)://<langsmith-url>/api，其中 <langsmith-url> 是您的自托管实例 URL。

如果您在 LANGSMITH_ENDPOINT 环境变量中设置端点，则需要在末尾添加 /v1（例如，https://api.smith.langchain.com/v1 或自托管时使用 http(s)://<langsmith-url>/api/v1）。

LangSmith 部署 API（部署）

对于 LangSmith 部署操作（部署、修订）：

区域	端点
美国 (GCP)	`https://api.host.langchain.com`
欧盟 (GCP)	`https://eu.api.host.langchain.com`
美国 (AWS)	`https://aws.api.host.langchain.com`

对于自托管 LangSmith 实例，使用 http(s)://<langsmith-url>/api-host，其中 <langsmith-url> 是您的自托管实例 URL。

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​概述

​管道架构

​触发源

​测试层

​GitHub actions 工作流

​先决条件

​部署选项

​手动部署的先决条件

​本地开发和测试

​方法 1：LangSmith 部署 UI

​方法 2：控制平面 API

​连接到已部署的代理

​环境配置

​数据库和缓存配置

​故障排除

​错误的 API 端点

​LangSmith API（跟踪、摄取等）

​LangSmith 部署 API（部署）

概述

管道架构

触发源

测试层

GitHub actions 工作流

先决条件

部署选项

手动部署的先决条件

本地开发和测试

方法 1：LangSmith 部署 UI

方法 2：控制平面 API

连接到已部署的代理

环境配置

数据库和缓存配置

故障排除

错误的 API 端点

LangSmith API（跟踪、摄取等）

LangSmith 部署 API（部署）