Skip to main content
本指南演示了如何为部署在 LangSmith Deployment 中的 AI 智能体应用程序实现一个全面的 CI/CD 流水线。在这个例子中，你将使用 LangGraph 开源框架来编排和构建智能体，使用 LangSmith 进行可观测性和评估。此流水线基于 cicd-pipeline-example 仓库。

​
概述

CI/CD 流水线提供：
  • 自动化测试：单元测试、集成测试和端到端测试。
  • 离线评估：使用 AgentEvals、OpenEvals 和 LangSmith 进行性能评估。
  • 预览和生产部署：使用控制平面 API 实现自动化的暂存环境和质量门控的生产发布。
  • 监控：持续评估和告警。

​
流水线架构

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

​
触发源

在开发过程中或应用程序已上线时，有多种方式可以触发此流水线。流水线可以由以下事件触发：
  • 代码变更：推送到主分支/开发分支，你可以修改 LangGraph 架构、尝试不同模型、更新智能体逻辑或进行任何代码改进。
  • PromptHub 更新：存储在 LangSmith PromptHub 中的提示词模板发生变更——每当有新的提示词提交时，系统会触发 webhook 来运行流水线。
  • 在线评估告警：来自实时部署的性能下降通知。
  • LangSmith 追踪记录 webhook：基于追踪分析和性能指标的自动化触发器。
  • 手动触发：用于测试或紧急部署的手动启动流水线。

​
测试层级

与传统软件相比，测试 AI 智能体应用程序还需要评估响应质量，因此测试工作流的每个部分都很重要。流水线实现了多个测试层级：
  1. 单元测试：单个节点和工具函数测试。
  2. 集成测试：组件交互测试。
  3. 端到端测试：完整图执行测试。
  4. 离线评估：使用真实场景进行性能评估，包括端到端评估、单步评估、智能体轨迹分析和多轮模拟。
  5. 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 Deployment 中创建一个新的预览部署。这允许你在提升到生产环境之前在暂存环境中测试智能体。
  • 智能体部署修订：当发现具有相同 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 Deployment 时，部署将会成功。

​
手动部署的先决条件

在部署你的智能体之前，请确保你拥有：
  1. LangGraph 图：你的智能体实现（例如，./agents/simple_text2sql.py:agent）。
  2. 依赖项：包含所有必需包的 requirements.txt 或 pyproject.toml。
  3. 配置：langgraph.json 文件，指定：
    • 智能体图的路径
    • 依赖项位置
    • 环境变量
    • Python 版本
示例 langgraph.json： 
{
    "graphs": {
        "simple_text2sql": "./agents/simple_text2sql.py:agent"
    },
    "env": ".env",
    "python_version": "3.11",
    "dependencies": ["."],
    "image_distro": "wolfi"
}

​
本地开发和测试

Studio CLI 界面 首先，使用 Studio 在本地测试你的智能体： 
# 使用 Studio 启动本地开发服务器
langgraph dev
这将：
  • 启动一个带有 Studio 的本地服务器。
  • 允许你可视化并与你的图交互。
  • 在部署前验证你的智能体是否正确工作。
如果你的智能体在本地运行没有任何错误，这意味着部署到 LangSmith 很可能会成功。这种本地测试有助于在尝试部署之前捕获配置问题、依赖项问题和智能体逻辑错误。
更多详情请参阅 LangGraph CLI 文档。

​
方法 1：LangSmith 部署 UI

使用 LangSmith 部署界面部署你的智能体：
  1. 转到你的 LangSmith 仪表板。
  2. 导航到 Deployments 部分。
  3. 点击右上角的 + New Deployment 按钮。
  4. 从下拉菜单中选择包含你的 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 Deployment 会为你创建 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 操作（追踪记录、评估、数据集）：
区域端点
美国https://api.smith.langchain.com
欧盟https://eu.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 Deployment API（部署）

对于 LangSmith Deployment 操作（部署、修订）：
区域端点
美国https://api.host.langchain.com
欧盟https://eu.api.host.langchain.com
对于自托管 LangSmith 实例，使用 http(s)://<langsmith-url>/api-host，其中 <langsmith-url> 是你的自托管实例 URL。
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.