使用控制平面部署

构建 Docker 镜像，并使用控制平面 UI 将应用程序部署到自托管 LangSmith 实例。

INFO

本指南面向自托管 LangSmith 客户，这些客户已在其实例上启用 LangSmith Deployment。Cloud 客户请参阅在 Cloud 上部署。没有控制平面的独立 Agent Servers，请参阅自托管独立服务器。

本指南展示如何将应用程序部署到自托管 LangSmith 实例，并使用控制平面。使用控制平面时，你在本地构建 Docker 镜像，将其推送到 Kubernetes 集群可访问的注册表，然后使用 LangSmith UI 进行部署。

拓扑

在现有自托管 LangSmith 实例上启用 LangSmith Deployment 会添加控制平面、数据平面监听器，以及一个在集群中预配 Agent Servers 的 operator。基础 LangSmith 平台继续处理可观测性、评估和提示；部署的 Agent Servers 会将追踪发送回该平台。

有关启用 LangSmith Deployment 所添加组件的详情，请参阅启用 LangSmith Deployment。

概述

部署到带控制平面的自托管 LangSmith 实例的应用程序使用 Docker 镜像。在本指南中，应用程序部署工作流为：

1. 使用 langgraph dev 或 Studio 在本地测试应用程序。
2. 使用 langgraph build 命令构建 Docker 镜像。
3. 将镜像推送到你的基础设施可访问的容器注册表。
4. 在控制平面 UI中指定镜像 URL 进行部署。

前置条件

完成本指南前，你需要以下内容：

• 在你的自托管 LangSmith 实例上启用 LangSmith Deployment。
• 有权访问已启用 LangSmith Deployment 的 LangSmith UI。
• 一个 Kubernetes 集群可访问的容器注册表。如果使用需要身份验证的私有注册表，你必须作为基础设施设置的一部分配置镜像拉取密钥。请参阅私有注册表身份验证。

步骤 1. 本地测试

部署前，请在本地测试应用程序。你可以使用 LangGraph CLI 以开发模式运行 Agent 服务器：

langgraph dev

有关本地测试的完整指南，请参阅本地服务器快速开始。

步骤 2. 构建 Docker 镜像

使用 langgraph build 命令构建应用程序的 Docker 镜像：

langgraph build -t my-image

构建命令选项包括：

选项	默认值	描述
-t, --tag TEXT	必填	Docker 镜像的标签
--platform TEXT		构建的目标平台（例如 linux/amd64,linux/arm64）
--pull / --no-pull	--pull	使用最新的远程 Docker 镜像构建
-c, --config FILE	langgraph.json	配置文件路径

带平台规格的示例：

langgraph build --platform linux/amd64 -t my-image:v1.0.0

有关完整详情，请参阅 CLI 参考。

步骤 3. 推送到容器注册表

将镜像推送到 Kubernetes 集群可访问的容器注册表。具体命令取决于你的注册表提供商。

TIP

请为镜像打上版本信息标签（例如 my-registry.com/my-app:v1.0.0），以便更轻松地回滚。

步骤 4. 使用控制平面 UI 部署

通过控制平面 UI，你可以创建和管理部署、查看日志和指标，并更新配置。要在 LangSmith UI 中创建新部署：

1. 在左侧导航面板中，选择 Deployments。
2. 在右上角，选择 + New Deployment。
3. 在部署配置面板中，提供：
   • Image URL：你在步骤 3中推送的完整镜像 URL。
   • Listener/Compute ID：选择为你的基础设施配置的监听器。
   • Namespace：要部署到的 Kubernetes 命名空间。
   • Environment variables：任何必需的配置（API 密钥等）。
   • 其他所需的部署设置。
4. 选择 Submit。

控制平面将与你的数据平面监听器协调以部署应用程序。

创建部署后，基础设施会异步预配。部署可能需要几分钟，首次部署由于需要创建数据库而耗时更长。

在控制平面 UI 中，你可以查看构建日志、服务器日志和部署指标，包括 CPU/内存使用率、副本数和 API 性能。有关更多详情，请参阅控制平面监控文档。

NOTE

每次部署都会自动创建一个同名的 LangSmith Observability 追踪项目。追踪环境变量由控制平面自动设置。

更新部署

要部署应用程序的新版本，请创建新修订版：

从 LangSmith UI 开始：

1. 在左侧导航面板中，选择 Deployments。
2. 选择一个现有部署。
3. 在 Deployment 视图中，选择右上角的 + New Revision。
4. 更新配置：
   • 将 Image URL 更新为新的镜像版本。
   • 根据需要更新环境变量。
   • 根据需要调整其他设置。
5. 选择 Submit。

私有注册表身份验证

如果你的容器注册表需要身份验证（例如 AWS ECR、Azure ACR、GCP Artifact Registry、私有 Docker 注册表），则必须在部署应用程序前配置 Kubernetes 镜像拉取密钥。这是一次性基础设施配置。

NOTE

此配置在基础设施层面完成，而不是按部署进行。 配置后，所有部署都会自动继承注册表凭据。

在 LangSmith Helm chart 的 values.yaml 文件中配置 imagePullSecrets。请参阅启用 LangSmith Deployment 指南中的详细步骤。

有关为不同注册表提供商创建镜像拉取密钥的详细步骤，请参阅 Kubernetes 从私有注册表拉取镜像的文档。

后续步骤

• 控制平面：详细了解控制平面功能。
• 数据平面：了解数据平面架构。
• 可观测性：通过自动追踪监控部署。
• Studio：测试和调试已部署的应用程序。
• LangGraph CLI：完整的 CLI 参考文档。

---