BytesRouter

主题

LangSmith 文档版本 跟随上游 源快照 1c0c3592 更新于 2026-10-18

使用 LangSmith Deployment 和评估实现 CI/CD 流水线

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

概述

该 CI/CD 流水线提供：

自动化测试：单元测试、集成测试和端到端测试。 *

离线评估：使用 AgentEvals、OpenEvals 和 LangSmith 进行性能评估。 *

预览和生产部署：使用 Control Plane API 进行自动化的预发和质量门控的生产发布。 *

监控：持续评估和告警。

流水线架构

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

graph TD
    A1[Code or Graph Change] --> B1[Trigger CI Pipeline]
    A2[Prompt Commit in PromptHub] --> B1
    A3[Online Evaluation Alert] --> B1
    A4[PR Opened] --> B1

    subgraph "Testing"
        B1 --> C1[Run Unit Tests]
        B1 --> C2[Run Integration Tests]
        B1 --> C3[Run End to End Tests]
        B1 --> C4[Run Offline Evaluations]

        C4 --> D1[Evaluate with OpenEvals or AgentEvals]
        C4 --> D2[Assertions: Hard and Soft]

        C1 --> E1[Run LangGraph Dev Server Test]
        C2 --> E1
        C3 --> E1
        D1 --> E1
        D2 --> E1
    end

    E1 --> F1[Push to Staging Deployment - Deploy to LangSmith as Development Type]

    F1 --> G1[Run Online Evaluations on Live Data]
    G1 --> H1[Attach Scores to Traces]

    H1 --> I1[If Quality Below Threshold]
    I1 --> J1[Send to Annotation Queue]
    I1 --> J2[Trigger Alert via Webhook]
    I1 --> J3[Push Trace to Golden Dataset]

    F1 --> K1[Promote to Production if All Pass - Deploy to LangSmith Production]

    J2 --> L1[Slack or PagerDuty Notification]

    subgraph Manual Review
        J1 --> M1[Human Labeling]
        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

触发来源

无论你是在开发期间还是在应用程序已经上线时，都可以通过多种方式触发该流水线。该流水线可由以下方式触发：

代码变更：推送到 main/development 分支，你可以在这些分支中修改 LangGraph 架构、尝试不同的模型、更新智能体逻辑或进行任何代码改进。 *

PromptHub 更新：对存储在 LangSmith PromptHub 中的提示词模板的更改——每当有新的提示词提交，系统就会触发一个 webhook 来运行流水线。 *

在线评估告警：来自线上部署的性能下降通知 *

LangSmith 追踪 webhook：基于追踪分析和性能指标的自动触发。 *

手动触发：为测试或紧急部署手动启动流水线。

测试层

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

单元测试：单个节点和实用函数的测试。 2.

集成测试：组件交互测试。 3.

端到端测试：完整图执行测试。 4.

离线评估：使用真实场景进行性能评估，包括端到端评估、单步评估、智能体轨迹分析和多轮模拟。 5.

LangGraph 开发服务器测试：使用 langgraph-cli 工具（在 GitHub Action 内）启动一个本地服务器来运行 LangGraph 智能体。它会轮询 /ok 服务器 API 端点，直到其可用，持续 30 秒，之后会抛出错误。

GitHub actions 工作流

该 CI/CD 流水线使用 GitHub Actions，配合 Control Plane API 和 LangSmith API 来自动化部署。一个辅助脚本管理 API 交互和部署：https://github.com/langchain-ai/cicd-pipeline-example/blob/main/.github/scripts/langgraph_api.py。

该工作流包括：

  • 新智能体部署：当新 PR 被打开且测试通过时，会使用 Control Plane API 在 LangSmith Deployment 中创建一个新的预览部署。这让你可以在预发环境中测试智能体，然后再推广到生产环境。

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

    智能体部署修订工作流

  • 测试与评估工作流：除了更传统的测试阶段（单元测试、集成测试、端到端测试等），该流水线还包含离线评估和智能体开发服务器测试，因为你需要检验智能体的质量。这些评估会使用真实场景和数据，对智能体的表现进行全面评估。

    带结果的测试工作流
最终响应评估
根据预期结果评估智能体的最终输出。这是最常见的评估类型，用于检查智能体的最终响应是否达到质量标准，并正确回答用户的问题。
单步评估
测试 LangGraph 工作流中的单个步骤或节点。这让你能够单独验证智能体逻辑的特定组件，确保在测试完整流水线之前每个步骤都能正常工作。
智能体轨迹评估
分析智能体在图中走过的完整路径，包括所有中间步骤和决策点。这有助于发现智能体工作流中的瓶颈、不必要的步骤或次优路由。它还会评估智能体是否以正确的顺序或在正确的时机调用了正确的工具。
多轮评估
测试对话流程，其中智能体需要在多次交互中保持上下文。这对于处理追问、澄清或与用户进行长时间对话的智能体至关重要。

有关具体的测试方法，请参阅 LangGraph 测试文档；有关离线评估的全面概述，请参阅评估方法指南。

前提条件

在设置 CI/CD 流水线之前，请确保你已具备：

一个 AI 智能体应用（本例使用 LangGraph 构建） *

一个 LangSmith 账户 *

部署智能体和获取实验结果所需的 LangSmith API key *

在你的仓库密钥中配置的项目专属环境变量（例如 LLM 模型 API key、向量存储凭证、数据库连接）

NOTE

虽然本示例使用 GitHub，但该 CI/CD 流水线同样适用于其他 Git 托管平台，包括 GitLab、Bitbucket 等。

部署选项

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

云版 LangSmith：直接 GitHub 集成。 *

自托管/混合：基于容器镜像仓库的部署。

部署流程从修改你的智能体实现开始。至少，你的项目中必须包含 langgraph.json 和依赖文件（requirements.txt 或 pyproject.toml）。使用 langgraph dev CLI 工具检查错误——请修复所有错误；修复后，部署到 LangSmith Deployment 时即可成功。

graph TD
    A[Agent Implementation] --> B[langgraph.json + dependencies]
    B --> C[Test Locally with langgraph dev]
    C --> D{Errors?}
    D -->|Yes| E[Fix Issues]
    E --> C
    D -->|No| F[Choose LangSmith Instance]

    F --> G[Cloud LangSmith]
    F --> H[Self-Hosted/Hybrid LangSmith]

    subgraph "Cloud LangSmith"
        G --> I[Method 1: Connect GitHub Repo in UI]
        G --> J[Method 2: Control Plane API with GitHub Repo]
        I --> K[Deploy via LangSmith UI]
        J --> L[Deploy via Control Plane API]
    end

    subgraph "Self-Hosted/Hybrid LangSmith"
        H --> S[Build Docker Image langgraph build]
        S --> T[Push to Container Registry]
        T --> U{Deploy via?}
        U -->|UI| V[Specify Image URI in UI]
        U -->|API| W[Use Control Plane API]
        V --> X[Deploy via LangSmith UI]
        W --> Y[Deploy via Control Plane API]
    end

    K --> AA[Agent Ready for Use]
    L --> AA
    X --> AA
    Y --> AA

    AA --> BB{Connect via?}
    BB -->|LangGraph SDK| CC[Use LangGraph SDK]
    BB -->|RemoteGraph| DD[Use RemoteGraph]
    BB -->|REST API| EE[Use REST API]
    BB -->|LangGraph Studio UI| FF[Use 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

手动部署的前置条件

在部署智能体之前，请确保你已具备：

LangGraph 图：你的智能体实现（例如 ./agents/simple_text2sql.py:agent）。 2.

依赖项：requirements.txt 或 pyproject.toml，其中包含所有必需的包。 3.

配置：langgraph.json 文件，用于指定：

  • 智能体图的路径
  • 依赖项位置
  • 环境变量
  • Python 版本

示例 langgraph.json：

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

本地开发与测试

Studio CLI 界面

首先，使用 Studio 在本地测试你的智能体：

bash
# Start local development server with Studio
langgraph dev

这将：

  • 启动一个带 Studio 的本地服务器。
  • 让你可视化并与图交互。
  • 在部署前验证智能体能正常工作。

NOTE

如果你的智能体在本地运行时没有任何错误，就意味着部署到 LangSmith 很可能也会成功。这种本地测试有助于在尝试部署之前发现配置问题、依赖问题以及智能体逻辑错误。

更多详情请参阅 LangGraph CLI 文档。

方式 1：LangSmith 部署界面

使用 LangSmith 部署界面部署你的智能体：

  1. 前往你的 LangSmith 仪表盘。
  2. 前往 Deployments 部分。
  3. 点击右上角的 + New Deployment 按钮。
  4. 从下拉菜单中选择包含你的 LangGraph 智能体的 GitHub 仓库。

支持的部署：

云版 LangSmith：通过下拉菜单直接进行 GitHub 集成 *

自托管/混合 LangSmith：在 Image Path 字段中指定你的镜像 URI（例如 docker.io/username/my-agent:latest）

INFO

优势：

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

方式 2：控制平面 API

使用 Control Plane API 进行部署，针对不同部署类型采用不同的方式：

对于云版 LangSmith：

  • 使用 Control Plane API，通过指向你的 GitHub 仓库来创建部署
  • 云部署无需构建 Docker 镜像

对于自托管/混合 LangSmith：

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

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

你可以推送到部署环境可访问的任何容器镜像仓库（Docker Hub、AWS ECR、Azure ACR、Google GCR 等）。

支持的部署：

云版 LangSmith：使用 Control Plane API 从你的 GitHub 仓库创建部署 *

自托管/混合 LangSmith：使用 Control Plane API 从你的容器镜像仓库创建部署

更多详情请参阅 LangGraph CLI build 文档。

连接到你已部署的智能体

**LangGraph SDK：使用 LangGraph SDK 进行编程式集成。 *

**RemoteGraph：使用 RemoteGraph 进行远程图连接（以便在其他图中使用你的图）。 *

**REST API：通过 HTTP 与你已部署的智能体交互。 *

**Studio：访问用于测试和调试的可视化界面。

环境配置

数据库与缓存配置

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

bash
# 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（追踪、数据摄取等）

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

区域 主机 / URL
GCP US {`$ / https://${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
GCP EU {`$ / https://eu.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
GCP APAC {`$ / https://apac.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
AWS US {`$ / https://aws.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}

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

NOTE

如果你要在 LANGSMITH_ENDPOINT 环境变量中设置端点，请使用不带尾部斜杠的完整 API URL（例如 https://api.smith.langchain.com，自托管则为 http(s)://<langsmith-url>/api）。尾部斜杠可能导致某些端点出现身份认证错误。

LangSmith Deployment API（部署）

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

区域 主机 / URL
GCP US {`$ / https://${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}
GCP EU {`$ / https://eu.${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}
GCP APAC {`$ / https://apac.${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}
AWS US {`$ / https://aws.${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}

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

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可