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

# 使用 LangSmith 部署和评估实现 CI/CD 流水线

本指南演示了如何为部署在 LangSmith Deployment 中的 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/prebuilt-evaluators#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:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#14532D
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A8A
    classDef decision fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#78350F
    classDef output fill:#F3E8FF,stroke:#9333EA,stroke-width:2px,color:#581C87
    classDef alert fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#7F1D1D
    classDef neutral fill:#F3F4F6,stroke:#9CA3AF,stroke-width:2px,color:#374151

    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 Deployment 中创建一个新的预览部署。这允许你在提升到生产环境之前在暂存环境中测试智能体。

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

  <img src="https://mintcdn.com/hhh-8c10bf0c/dGi5Qyx6ZNfUuqyP/langsmith/images/cicd-new-lgp-revision.png?fit=max&auto=format&n=dGi5Qyx6ZNfUuqyP&q=85&s=975173890932dafeaf0235d3df9a7ebc" 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/hhh-8c10bf0c/dGi5Qyx6ZNfUuqyP/langsmith/images/cicd-test-with-results.png?fit=max&auto=format&n=dGi5Qyx6ZNfUuqyP&q=85&s=c07469ec207f3635350911bb9457053f" 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 Deployment 时，部署将会成功。

```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:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#14532D
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A8A
    classDef decision fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#78350F
    classDef output fill:#F3E8FF,stroke:#9333EA,stroke-width:2px,color:#581C87

    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/hhh-8c10bf0c/dGi5Qyx6ZNfUuqyP/langsmith/images/cicd-studio-cli.png?fit=max&auto=format&n=dGi5Qyx6ZNfUuqyP&q=85&s=e2fe20eba3596609b33350391cafca19" 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 Deployment 会为你创建 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 操作（追踪记录、评估、数据集）：

| 区域 | 端点                                   |
| -- | ------------------------------------ |
| 美国 | `https://api.smith.langchain.com`    |
| 欧盟 | `https://eu.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 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。

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\cicd-pipeline-example.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>