> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

本指南演示如何为部署在 LangSmith 部署中的 AI 代理应用程序实现全面的 CI/CD 管道。在此示例中，您将使用 [LangGraph](/oss/python/langgraph/overview) 开源框架来编排和构建代理，使用 [LangSmith](/langsmith/home) 进行可观测性和评估。此管道基于 [cicd-pipeline-example 仓库](https://github.com/langchain-ai/cicd-pipeline-example)。

## 概述

CI/CD 管道提供：

* <Icon icon="circle-check" /> **自动化测试**：单元测试、集成测试和端到端测试。
* <Icon icon="chart-line" /> **离线评估**：使用 [AgentEvals](/oss/python/langchain/test/evals)、[OpenEvals](/langsmith/openevals#setup) 和 [LangSmith](/langsmith/home) 进行性能评估。
* <Icon icon="rocket" /> **预览和生产部署**：使用控制平面 API 进行自动化暂存和质量门控的生产发布。
* <Icon icon="eye" /> **监控**：持续评估和警报。

## 管道架构

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

```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
graph TD
    A1[代码或图更改] --> B1[触发 CI 管道]
    A2[PromptHub 中的提示提交] --> B1
    A3[在线评估警报] --> B1
    A4[PR 已打开] --> B1

    subgraph "测试"
        B1 --> C1[运行单元测试]
        B1 --> C2[运行集成测试]
        B1 --> C3[运行端到端测试]
        B1 --> C4[运行离线评估]

        C4 --> D1[使用 OpenEvals 或 AgentEvals 进行评估]
        C4 --> D2[断言：硬断言和软断言]

        C1 --> E1[运行 LangGraph 开发服务器测试]
        C2 --> E1
        C3 --> E1
        D1 --> E1
        D2 --> E1
    end

    E1 --> F1[推送到暂存部署 - 作为开发类型部署到 LangSmith]

    F1 --> G1[在实时数据上运行在线评估]
    G1 --> H1[将分数附加到跟踪]

    H1 --> I1[如果质量低于阈值]
    I1 --> J1[发送到标注队列]
    I1 --> J2[通过 Webhook 触发警报]
    I1 --> J3[将跟踪推送到黄金数据集]

    F1 --> K1[如果全部通过则提升到生产 - 部署到 LangSmith 生产环境]

    J2 --> L1[Slack 或 PagerDuty 通知]

    subgraph 人工审核
        J1 --> M1[人工标注]
        M1 --> J3
    end

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
    classDef alert fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643
    classDef neutral fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68

    class A1,A2,A3,A4 trigger
    class B1,C1,C2,C3,C4,D1,D2,E1 process
    class H1,I1 decision
    class F1,G1,K1 output
    class J2,L1 alert
    class J1,J3,M1 neutral
```

### 触发源

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

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

### 测试层

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

1. <Icon icon="puzzle" /> **单元测试**：单个节点和实用函数测试。
2. <Icon icon="link" /> **集成测试**：组件交互测试。
3. <Icon icon="route" /> **端到端测试**：完整图执行测试。
4. <Icon icon="brain" /> **离线评估**：使用真实场景进行性能评估，包括端到端评估、单步评估、代理轨迹分析和多轮模拟。
5. <Icon icon="server" /> **LangGraph 开发服务器测试**：使用 [langgraph-cli](/langsmith/cli) 工具在 GitHub Action 内启动本地服务器来运行 LangGraph 代理。它会轮询 `/ok` 服务器 API 端点，直到其可用并持续 30 秒，之后会抛出错误。

## GitHub actions 工作流

CI/CD 管道使用 GitHub Actions 与 [控制平面 API](/langsmith/api-ref-control-plane) 和 [LangSmith API](https://api.smith.langchain.com/redoc) 来自动化部署。一个辅助脚本管理 API 交互和部署：[https://github.com/langchain-ai/cicd-pipeline-example/blob/main/.github/scripts/langgraph\_api.py。](https://github.com/langchain-ai/cicd-pipeline-example/blob/main/.github/scripts/langgraph_api.py。)

该工作流包括：

* **新代理部署**：当打开新的 PR 并且测试通过时，使用 [控制平面 API](/langsmith/api-ref-control-plane) 在 LangSmith 部署中创建一个新的预览部署。这允许您在将代理提升到生产环境之前，在暂存环境中对其进行测试。

* **代理部署修订**：当找到具有相同 ID 的现有部署，或者当 PR 合并到主分支时，会发生修订。在合并到主分支的情况下，预览部署将被删除，并创建一个生产部署。这确保了对代理的任何更新都被正确部署并集成到生产基础设施中。

  <img src="https://mintcdn.com/other-405835d4/U_V3brHb6y_62TSF/langsmith/images/cicd-new-lgp-revision.png?fit=max&auto=format&n=U_V3brHb6y_62TSF&q=85&s=4ac60500eb4365a2aad024253dcfb483" alt="代理部署修订工作流" width="1022" height="196" data-path="langsmith/images/cicd-new-lgp-revision.png" />

* **测试和评估工作流**：除了更传统的测试阶段（单元测试、集成测试、端到端测试等）之外，管道还包括[离线评估](/langsmith/evaluation-concepts#offline-evaluations)和[代理开发服务器测试](/langsmith/local-dev-testing)，因为您想要测试代理的质量。这些评估使用真实场景和数据对代理的性能进行全面评估。

  <img src="https://mintcdn.com/other-405835d4/U_V3brHb6y_62TSF/langsmith/images/cicd-test-with-results.png?fit=max&auto=format&n=U_V3brHb6y_62TSF&q=85&s=618fc6cab0aea1fdcf5f226022de0862" alt="带结果的测试工作流" width="2050" height="996" data-path="langsmith/images/cicd-test-with-results.png" />

  <AccordionGroup>
    <Accordion title="最终响应评估" icon="circle-check">
      根据预期结果评估代理的最终输出。这是最常见的评估类型，检查代理的最终响应是否符合质量标准并正确回答用户的问题。
    </Accordion>

    <Accordion title="单步评估" icon="player-skip-forward">
      测试 LangGraph 工作流中的单个步骤或节点。这允许您单独验证代理逻辑的特定组件，确保每个步骤在测试完整管道之前都能正常工作。
    </Accordion>

    <Accordion title="代理轨迹评估" icon="route">
      分析代理在图中采取的完整路径，包括所有中间步骤和决策点。这有助于识别代理工作流中的瓶颈、不必要的步骤或次优路由。它还评估您的代理是否在正确的时间以正确的顺序调用了正确的工具。
    </Accordion>

    <Accordion title="多轮评估" icon="messages">
      测试代理在多次交互中保持上下文的对话流程。这对于处理后续问题、澄清或与用户进行扩展对话的代理至关重要。
    </Accordion>
  </AccordionGroup>

  有关具体的测试方法，请参阅 [LangGraph 测试文档](/oss/python/langgraph/test)，有关离线评估的全面概述，请参阅[评估方法指南](/langsmith/evaluation-approaches)。

### 先决条件

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

* <Icon icon="robot" /> 一个 AI 代理应用程序（在本例中使用 [LangGraph](/oss/python/langgraph/overview) 构建）
* <Icon icon="user" /> 一个 [LangSmith 帐户](https://smith.langchain.com/)
* <Icon icon="key" /> 一个 [LangSmith API 密钥](/langsmith/create-account-api-key)，用于部署代理和检索实验结果
* <Icon icon="settings" /> 在您的仓库密钥中配置的项目特定环境变量（例如，LLM 模型 API 密钥、向量存储凭据、数据库连接）

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

## 部署选项

LangSmith 支持多种部署方法，具体取决于您的 [LangSmith 实例的托管方式](/langsmith/platform-setup)：

* <Icon icon="cloud" /> **云 LangSmith**：直接 GitHub 集成。
* <Icon icon="server" /> **自托管/混合**：基于容器注册表的部署。

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

```mermaid actions={false} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
graph TD
    A[代理实现] --> B[langgraph.json + 依赖项]
    B --> C[使用 langgraph dev 在本地测试]
    C --> D{有错误？}
    D -->|是| E[修复问题]
    E --> C
    D -->|否| F[选择 LangSmith 实例]

    F --> G[云 LangSmith]
    F --> H[自托管/混合 LangSmith]

    subgraph "云 LangSmith"
        G --> I[方法 1：在 UI 中连接 GitHub 仓库]
        G --> J[方法 2：使用 GitHub 仓库的控制平面 API]
        I --> K[通过 LangSmith UI 部署]
        J --> L[通过控制平面 API 部署]
    end

    subgraph "自托管/混合 LangSmith"
        H --> S[构建 Docker 镜像 langgraph build]
        S --> T[推送到容器注册表]
        T --> U{通过什么部署？}
        U -->|UI| V[在 UI 中指定镜像 URI]
        U -->|API| W[使用控制平面 API]
        V --> X[通过 LangSmith UI 部署]
        W --> Y[通过控制平面 API 部署]
    end

    K --> AA[代理准备就绪]
    L --> AA
    X --> AA
    Y --> AA

    AA --> BB{通过什么连接？}
    BB -->|LangGraph SDK| CC[使用 LangGraph SDK]
    BB -->|RemoteGraph| DD[使用 RemoteGraph]
    BB -->|REST API| EE[使用 REST API]
    BB -->|LangGraph Studio UI| FF[使用 LangGraph Studio UI]

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33

    class A trigger
    class B,C process
    class D,U,BB decision
    class E process
    class F decision
    class G,H process
    class I,J,S,T process
    class K,L,V,W process
    class X,Y,AA output
    class CC,DD,EE,FF output
```

### 手动部署的先决条件

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

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

示例 `langgraph.json`：

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
    "graphs": {
        "simple_text2sql": "./agents/simple_text2sql.py:agent"
    },
    "env": ".env",
    "python_version": "3.11",
    "dependencies": ["."],
    "image_distro": "wolfi"
}
```

### 本地开发和测试

<img src="https://mintcdn.com/other-405835d4/U_V3brHb6y_62TSF/langsmith/images/cicd-studio-cli.png?fit=max&auto=format&n=U_V3brHb6y_62TSF&q=85&s=9bf6d7261db8a3e76279967fc5d58dda" alt="Studio CLI 界面" width="2972" height="1354" data-path="langsmith/images/cicd-studio-cli.png" />

首先，使用 [Studio](/langsmith/studio) 在本地测试您的代理：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 使用 Studio 启动本地开发服务器
langgraph dev
```

这将：

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

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

有关更多详细信息，请参阅 [LangGraph CLI 文档](/langsmith/cli#dev)。

### 方法 1：LangSmith 部署 UI

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

1. 转到您的 [LangSmith 仪表板](https://smith.langchain.com)。
2. 导航到 **Deployments** 部分。
3. 单击右上角的 **+ New Deployment** 按钮。
4. 从下拉菜单中选择包含您的 LangGraph 代理的 GitHub 仓库。

**支持的部署：**

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

<Info>
  **优点：**

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

### 方法 2：控制平面 API

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

**对于云 LangSmith：**

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

**对于自托管/混合 LangSmith：**

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 构建 Docker 镜像
langgraph build -t my-agent:latest

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

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

**支持的部署：**

* <Icon icon="cloud" /> **云 LangSmith**：使用控制平面 API 从您的 GitHub 仓库创建部署
* <Icon icon="server" /> **自托管/混合 LangSmith**：使用控制平面 API 从您的容器注册表创建部署

有关更多详细信息，请参阅 [LangGraph CLI 构建文档](/langsmith/cli#build)。

### 连接到已部署的代理

* <Icon icon="code" /> **[LangGraph SDK](https://langchain-ai.github.io/langgraph/cloud/reference/sdk/python_sdk_ref/#langgraph-sdk-python)**：使用 LangGraph SDK 进行编程集成。
* <Icon icon="sitemap" /> **[RemoteGraph](/langsmith/use-remote-graph)**：使用 RemoteGraph 进行远程图连接（以便在其他图中使用您的图）。
* <Icon icon="globe" /> **[REST API](/langsmith/server-api-ref)**：使用基于 HTTP 的交互与您的已部署代理进行交互。
* <Icon icon="device-desktop" /> **[Studio](/langsmith/studio)**：访问用于测试和调试的可视化界面。

### 环境配置

#### 数据库和缓存配置

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 为外部服务设置环境变量
export POSTGRES_URI_CUSTOM="postgresql://user:pass@host:5432/db"
export REDIS_URI_CUSTOM="redis://host:6379/0"
```

有关更多详细信息，请参阅[环境变量文档](/langsmith/env-var#postgres_uri_custom)。

## 故障排除

### 错误的 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。

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

#### 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。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/cicd-pipeline-example.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>