启用额外的 LangSmith 功能

在一个自托管 LangSmith 实例上启用 LangSmith Deployment、Fleet、Insights、Chat、沙箱和 Engine。

在基础 LangSmith 平台之外，你能在 LangSmith Self-hosted 上启用以下功能：

LangSmith Deployment 增加一个控制平面和一个数据平面，让你能通过 LangSmith UI 直接部署、扩缩和管理 agent 与应用。如果你不需要完整的基于 UI 的设置，关于轻量替代方案参阅独立服务器。
Fleet 让你能在 LangSmith 内无代码地创建、部署和管理 AI agent。
Insights 在 LangSmith 内提供对你追踪和应用数据的 AI 驱动分析。
Chat 提供一个工作区内的聊天体验，帮你分析追踪、线程、提示和实验结果。
沙箱让用户从 LangSmith 运行代码、暴露临时服务并创建内存快照。
Engine 在一个追踪项目中发现反复出现的问题、针对你的源码诊断它们并提出修复。Engine 需要沙箱，并从 Self-hosted 上的 Engine 安装。

INFO

这些功能需要 Enterprise 方案。获取一次演示以了解更多。

前置条件

Install the base LangSmith platform

在继续之前，遵循 Kubernetes 安装指南安装基础的 LangSmith 平台。

Install KEDA

运行以下命令在你的集群上安装 KEDA：

bash

helm repo add kedacore https://kedacore.github.io/charts
helm upgrade --install keda kedacore/keda --namespace keda --create-namespace

INFO

KEDA 会基于队列大小自动伸缩部署系统。

Configure an ingress

为你的 LangSmith 实例配置一个 ingress、网关或 Istio。所有 agent 都会作为该 ingress 之后的 Kubernetes 服务部署。见设置一个 ingress。你必须在你的 langsmith_config.yaml 中提供一个 hostname。

Verify cluster capacity

确保你的集群有多个部署可用的容量。推荐一个集群自动伸缩器。

Verify storage

确保你的集群上有一个有效的动态 PV 预配器或 PV 可用。

bash

kubectl get storageclass

至少一个 StorageClass 应有一个 PROVISIONER 值（不是 kubernetes.io/no-provisioner）并被标为 (default)，或者你必须在继续之前配置一个。

Verify egress

确保到 https://beacon.langchain.com 的出口可用。见出口文档。

启用 LangSmith Deployment

组件

启用 LangSmith Deployment 会在你的集群中预配以下资源：

listener：监听控制平面对你部署的更改，并创建或更新下游 CRD。
LangGraphPlatform CRD：管理 LangSmith Deployment 的实例。
operator：处理你 LangSmith CRD 的更改。
host-backend：控制平面。

启用该功能

要启用 LangSmith Deployment，更新你的 langsmith_config.yaml：

Enable deployment in your config

在你的 langsmith_config.yaml 中，启用 deployment 选项。你也必须配置一个有效的 ingress。

yaml

config:
  deployment:
    enabled: true

NOTE

从 v0.12.0 起，langgraphPlatform 选项已弃用。对 v0.12.0 之后的任何版本用 config.deployment。

(Optional) Configure image mirroring

如果你需要把镜像镜像到一个私有仓库，在你的 langsmith_config.yaml 中配置 hostBackendImage 和 operatorImage 选项。用最新 LangSmith Helm chart 发布中所指定的镜像标签。

yaml

hostBackendImage:
  repository: "docker.io/langchain/hosted-langserve-backend"
  pullPolicy: IfNotPresent
operatorImage:
  repository: "docker.io/langchain/langgraph-operator"
  pullPolicy: IfNotPresent

(Optional) Configure base agent templates

如果你需要自定义 operator 如何创建 agent 的 Kubernetes 资源，覆盖values.yaml 中的基础 agent 模板。最常见的用例是添加 imagePullSecrets 以用一个私有容器仓库身份验证。详情见为私有仓库配置身份验证。

Apply the changes

运行以下命令应用更改。每当你被要求应用更改时，本指南各处都用这条命令。把 <version> 和 <namespace> 替换为你的值：

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

在继续之前验证新 pod 正在运行：

bash

kubectl get pods -n <namespace>

你的实例现在可以创建部署了。

启用 Fleet、Insights 和 Chat

INFO

Fleet 需要 LangSmith Self-Hosted v0.13 或更高。下面所述的独立部署模型需要 v0.15 或更高。

每个功能都需要一个 Fernet 加密密钥。你能在一个单独的 Helm 配置里启用全部三个功能。

组件

启用这些功能会为每个功能（Fleet、Insights、Chat）在你的集群中预配以下组件：

api-server：处理该功能请求的主 API 服务器。
queue：后台任务处理队列。
postgres：该功能数据的专属 PostgreSQL 实例。可被一个外部 PostgreSQL 实例替代。
redis：该功能缓存和 pub/sub 的专属 Redis 实例。可被一个外部 Redis 实例替代。

Fleet 还额外预配：

toolServer：为 agent 提供 MCP 工具执行。
triggerServer：处理 webhook 和计划触发器。

WARNING

从 chart 0.16.0 起，Insights 在 langsmith-insights-engine 上运行——一个同时服务 insights 和 engine 图的组合镜像，chart 默认使用它。此前仅 Insights 的镜像 langsmith-clio 已退役。

如果你的 values 把 images.engineInsightsAgentImage.repository 锁到 langsmith-clio，在升级前移除或更新该锁定。chart 会拒绝它。如果你把镜像镜像到私有仓库，请镜像 langsmith-insights-engine 并把 repository 指向你的副本。见镜像镜像。

生成加密密钥

每个功能用它自己的 Fernet 加密密钥来加密功能专属机密，如凭据和令牌。分开的密钥允许独立轮换，并在某个密钥被泄露时限制暴露。用 Python 为每个功能生成一个密钥：

bash

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

我们推荐把每个密钥存在一个预定义的 Kubernetes secret 中，而非在你的配置文件里直接设置它们。相关参数见使用现有 secret：agent_builder_encryption_key、insights_encryption_key 和 polly_encryption_key。

启用功能

Add the configuration to your langsmith_config.yaml

按名字引用你现有的 secret。chart 会自动从中读取 agent_builder_encryption_key、insights_encryption_key 和 polly_encryption_key。

yaml

config:
  existingSecretName: "<your-secret-name>"

fleet:
  enabled: true

insights:
  enabled: true

# Chat (formerly Polly)
polly:
  enabled: true

fleetToolServer:
  enabled: true

fleetTriggerServer:
  enabled: true

WARNING

如果你从遗留的 agentBootstrap 部署模型迁移，请禁用 backend.agentBootstrap 以及旧的 config.agentBuilder、config.insights 和 config.polly 标志。这些是 config 节下的标志，而非上面展示的顶层 fleet、insights 和 polly 标志。

你还必须通过 LangSmith Deployments UI 手动删除现有的 Fleet、Insights 和 Chat 部署。如果你在用遗留 agentBootstrap 模型时没为 Fleet 使用外部 PostgreSQL 数据库、且想保留现有的 Fleet agent，请在应用此配置之前通过 Support Portal 联系技术支持。

NOTE

fleetToolServer 和 fleetTriggerServer 对 Fleet 是必需的。从 Helm chart 的 v15 起，它们取代了已弃用的 agentBuilderToolServer 和 agentBuilderTriggerServer 键。

每个功能默认部署它自己专属的 PostgreSQL 和 Redis 实例。要改用外部数据库，在每个功能下配置 postgres.external 和 redis.external 节。例如：

yaml

fleet:
  enabled: true
  encryptionKey: "<fleet-encryption-key>"
  postgres:
    external:
      enabled: true
      connectionUrl: "<fleet-postgres-connection-url>"
  redis:
    external:
      enabled: true
      connectionUrl: "<fleet-redis-connection-url>"

Apply the changes

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

验证 Fleet、Insights 和 Chat pod 正在运行：

bash

kubectl get pods -n <namespace>

（可选）为 Fleet 启用 OAuth 工具和触发器

要在 Fleet 中启用像 Gmail、Slack 或 Linear 这样的基于 OAuth 的工具，配置 providerOrgId 并为你想用的每个集成添加提供商 ID。你能启用任意提供商组合。

可用提供商

提供商	启用的工具	启用的触发器
`googleOAuthProvider` 设置指南	Gmail、Google Calendar、 Google Sheets、BigQuery	Gmail
`linearOAuthProvider` 设置指南	Linear	-
`linkedinOAuthProvider` 设置指南	LinkedIn	-
`microsoftOAuthProvider` 设置指南	Outlook、Calendar、Teams、SharePoint、 Word、Excel、PowerPoint	Outlook
`salesforceOAuthProvider` 设置指南	Salesforce	-
`slackOAuthProvider` 设置指南	Slack	Slack

通用配置

把以下内容添加到你的 langsmith_config.yaml。只包含你需要的提供商。

yaml

fleet:
  oauth:
    # Organization ID where OAuth providers are configured
    providerOrgId: "<your-org-id>"
    # Add provider IDs for integrations you want to enable.
    slackOAuthProvider: "<provider-id>"
    googleOAuthProvider: "<provider-id>"
    linkedinOAuthProvider: "<provider-id>"
    linearOAuthProvider: "<provider-id>"
    microsoftOAuthProvider: "<provider-id>"
    salesforceOAuthProvider: "<provider-id>"

WARNING

提供商 ID 必须唯一且不能以 -agent-builder 或 -oauth-provider 结尾。

提供商设置指南

Google OAuth provider

To enable Google OAuth for Fleet, create an OAuth client in GCP and configure it with the required URLs and credentials.

Create OAuth client in GCP

Create a new OAuth client app (Web application) in Google Cloud Console.

Add URLs to GCP

Add the following URLs to your OAuth client, replacing <hostname> with your LangSmith hostname and <provider-id> with the provider ID you'll use (for example, google):

Authorized JavaScript origins:

https://<hostname>

Authorized redirect URIs:

https://<hostname>/api-host/v2/auth/callback/<provider-id>
https://<hostname>/host-oauth-callback/<provider-id>

Copy credentials

Copy the Client ID and Client Secret from the GCP OAuth app.

Configure OAuth provider in LangSmith

In LangSmith, go to Settings > OAuth Providers and add a new provider:

Client ID: from GCP
Client Secret: from GCP
Authorization URL: https://accounts.google.com/o/oauth2/auth
Token URL: https://oauth2.googleapis.com/token
Provider ID: Unique string, for example: google

Apply the changes

Add the LangSmith OAuth provider ID to your langsmith_config.yaml and deploy:

yaml

fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    googleOAuthProvider: "<provider-id>"

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Microsoft OAuth provider

To enable Microsoft OAuth for Fleet, create an Azure app registration, add the required Microsoft Graph delegated permissions, and configure a Microsoft OAuth provider in LangSmith.

Create an Azure app registration

In the Microsoft Entra admin center, go to Applications > App registrations and create a new registration.

Choose supported account types

Select the account type that matches your deployment. If you need users from multiple Microsoft Entra tenants to authenticate, choose a multi-tenant option. If your deployment is limited to one tenant, you can use a single-tenant app registration.

Add the redirect URI

Add the following web redirect URI, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID:

https://<hostname>/host-oauth-callback/<provider-id>

Create a client secret

In Certificates & secrets, create a new client secret. Copy the Application (client) ID and the generated client secret value.

Add Microsoft Graph delegated permissions

In API permissions, add the following Microsoft Graph delegated permissions:

Mail.ReadWrite
Mail.Send
Calendars.ReadWrite
Team.ReadBasic.All
Channel.ReadBasic.All
Channel.Create
ChannelMessage.Send
ChannelMessage.Read.All
Chat.Create
Chat.ReadWrite
User.ReadBasic.All
Files.ReadWrite.All
Sites.ReadWrite.All

NOTE

LangSmith automatically requests offline_access for Microsoft providers so users can receive refresh tokens.

Grant tenant consent

Grant admin consent for the tenant if your Microsoft 365 policies require it for these delegated permissions.

Configure OAuth provider in LangSmith

In LangSmith, go to Settings > OAuth Providers and add a new provider:

Name: For example, Microsoft
Provider ID: Unique string, for example: microsoft-oauth-provider
Client ID: Application (client) ID from Azure
Client Secret: Client secret value from Azure
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
Provider Type: microsoft
Token endpoint auth method: client_secret_post

NOTE

If you created a single-tenant app registration, replace common in the authorization and token URLs with your tenant ID.

Apply the changes

Add the following to your langsmith_config.yaml and deploy:

yaml

fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    microsoftOAuthProvider: "<provider-id>"

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Linear OAuth provider

To enable Linear OAuth for Fleet, create a Linear OAuth app and configure it with the required credentials.

Create a Linear OAuth app

Go to Linear Settings > API > Applications and create a new OAuth application.

Add callback URL

Set the callback URL, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID:

https://<hostname>/host-oauth-callback/<provider-id>

Copy credentials

After creating the app, copy the Client ID and Client Secret.

Configure OAuth provider in LangSmith

In LangSmith, go to Settings > OAuth Providers and add a new provider:

Client ID: from Linear app
Client Secret: from Linear app
Authorization URL: https://linear.app/oauth/authorize
Token URL: https://api.linear.app/oauth/token
Provider ID: Unique string, for example: linear

Apply the changes

Add the following to your langsmith_config.yaml and deploy:

yaml

fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    linearOAuthProvider: "<provider-id>"

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

LinkedIn OAuth provider

To enable LinkedIn OAuth for Fleet, create a LinkedIn OAuth app and configure it with the required credentials.

Create a LinkedIn OAuth app

Go to linkedin.com/developers/apps and create a new app.

Add redirect URI

In your app settings, go to the Auth tab. Add the following redirect URI, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID:

https://<hostname>/host-oauth-callback/<provider-id>

Copy credentials

Copy the Client ID and Client Secret from the Auth tab.

Configure OAuth provider in LangSmith

In LangSmith, go to Settings > OAuth Providers and add a new provider:

Client ID: from LinkedIn app
Client Secret: from LinkedIn app
Authorization URL: https://www.linkedin.com/oauth/v2/authorization
Token URL: https://www.linkedin.com/oauth/v2/accessToken
Provider ID: Unique string, for example: linkedin

Apply the changes

Add the following to your langsmith_config.yaml and deploy:

yaml

fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    linkedinOAuthProvider: "<provider-id>"

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Salesforce OAuth provider

To enable Salesforce OAuth for Fleet, create a Salesforce External Client App, configure its OAuth settings and policies, retrieve its credentials, then configure a Salesforce OAuth provider in LangSmith.

Create an External Client App

In Salesforce Setup, use Quick Find to open External Client App Manager, then click New External Client App.

Under Basic Information, set:

External Client App Name: for example, LangSmith Fleet
Contact Email: an admin email address
Distribution State: Local

NOTE

External Client Apps are the current framework Salesforce uses for OAuth integrations. If New External Client App is unavailable, confirm that app creation is enabled for your org under Setup > External Client App Settings.

Enable OAuth and configure the OAuth settings

Expand API (Enable OAuth Settings) and select Enable OAuth. Then configure:

Callback URL, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID:

https://<hostname>/host-oauth-callback/<provider-id>

Selected OAuth Scopes: add Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access).
Keep Require Secret for the Web Server Flow selected.
Leave Enable Authorization Code and Credentials Flow and Enable Client Credentials Flow unselected. Fleet uses the standard web server (authorization code) flow.

Click Create.

Set the OAuth policies

Open the app, select the Policies tab, and click Edit:

Refresh Token Policy: select Refresh token is valid until revoked.
Permitted Users: leave All users may self-authorize. If you choose Admin approved users are pre-authorized instead, you must first assign the app to a permission set or profile, or authorization fails.

Click Save.

NOTE

An External Client App is configured in two places: Settings (the OAuth definition from the previous step) and Policies (this step). Both must be saved.

Copy the credentials

On the Settings tab, under OAuth Settings, select Consumer Key and Secret. The Consumer Key is your Client ID and the Consumer Secret is your Client Secret.

NOTE

After you create the app, allow up to 30 minutes for it to propagate before the first connection attempt.

Configure OAuth provider in LangSmith

In LangSmith, go to Settings > OAuth Providers, click OAuth Provider, and fill in:

Provider ID: Unique string, for example: salesforce-oauth-provider. Use this same value for salesforceOAuthProvider in the next step.
Display Name: For example, Salesforce
Client ID: Consumer Key from Salesforce
Client Secret: Consumer Secret from Salesforce
Authorization URL: https://<MyDomain>.my.salesforce.com/services/oauth2/authorize
Token URL: https://<MyDomain>.my.salesforce.com/services/oauth2/token

LangSmith recognizes Salesforce automatically from the Token URL, so there is no provider-type or token-auth-method field to set. Leave Enable PKCE off to match the web server flow configured above.

NOTE

Replace <MyDomain> with your org's My Domain, found under Setup > My Domain. For a sandbox, use https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com/services/oauth2/authorize and the matching token URL.

Apply the changes

Add the following to your langsmith_config.yaml and deploy:

yaml

fleet:
  oauth:
    providerOrgId: "<your-langsmith-org-id>"
    salesforceOAuthProvider: "<provider-id>"

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

WARNING

If sign-in fails: confirm the Callback URL in Salesforce exactly matches https://<hostname>/host-oauth-callback/<provider-id> (HTTPS, no trailing slash); if you selected Admin approved users are pre-authorized, assign the app via a permission set; and if your org enforces login IP ranges, allowlist your Fleet server's egress IPs on the user's profile or set IP Relaxation to Relax IP restrictions in the app's policies.

Slack OAuth 提供商

一个 Slack OAuth 提供商同时驱动 Slack 工具和你添加到各个 agent 的 Slack 应用，所以 Slack 设置与其余 Slack 集成放在一起。

完整演练，见在 Self-hosted 上设置 Slack。它涵盖创建 Slack 应用、添加 bot 作用域、注册提供商、设置重定向 URI 和配置 Helm 值。

（可选）为 Fleet 启用 GitHub App

Fleet 通过一个专属 GitHub App（而非 OAuth 应用）与 GitHub 集成。这个 GitHub App 为 Fleet 的 GitHub 工具提供仓库访问，并支持私有仓库访问所需的用户授权流程。

设置涉及创建一个 GitHub App、收集其凭据、把它们存为 Kubernetes secret，并从你的 langsmith_config.yaml 引用它们。

Create a GitHub App

转到 GitHub Settings > Developer settings > GitHub Apps 并点击 New GitHub App。

NOTE

你能在个人账户或组织下创建该应用。如果将有多人管理该集成，推荐一个组织所有的应用。

Fill in basic details

GitHub App name：任何唯一名字，例如 acme-langsmith-fleet。记下 GitHub 生成的 slug（名字的小写连字符形式），因为这就是你给 FLEET_GITHUB_APP_SLUG 用的值。
Homepage URL：你的 LangSmith 主机名，例如 https://langsmith.acme.com。
暂时在 Webhook 下取消勾选 Active。你会在生成一个 webhook 机密之后的某一步启用它。

Set callback URLs

在 Identifying and authorizing users 下，添加以下 Callback URL，把 <hostname> 替换为你的 LangSmith 主机名：

https://<hostname>/api/v1/platform/fleet/providers/github-app/auth/callback

选择 Redirect on update。

在 Post installation 下，添加以下 Setup URL：

https://<hostname>/api/v1/platform/fleet/providers/github-app/callback

选择 Redirect on update。

Set webhook URL and generate a webhook secret

生成一个随机的 webhook 机密：

bash

python3 -c "import secrets; print(secrets.token_urlsafe(48))"

在 Webhook 下：

选择 Active。

把 Webhook URL 设为：

https://<hostname>/api/v1/platform/fleet/providers/github-app/webhooks

把生成的值粘贴进 Webhook secret。保存它，因为在你以后创建 Kubernetes secret 时会需要同一个值。

Set repository permissions

在 Permissions > Repository permissions 下，授予以下权限：

Contents：读写
Issues：读写
Pull requests：读写
Metadata：只读（自动选中）

在 Permissions > Account permissions 下，授予 Email addresses: Read-only。

NOTE

这些是 Fleet 内置 GitHub 工具（issue 管理、拉取请求创建、仓库内容访问）所需的最小权限。若你需要额外工具能力，请调整。

Choose install visibility

在 Where can this GitHub App be installed? 下，选择匹配你分发需求的选项。对多数自托管部署，Only on this account 是正确的。

Create the app

点击 Create GitHub App。在应用设置页，记下以下值：

值	在哪找	环境变量
App ID	数字，在页面顶部	`FLEET_GITHUB_APP_ID`
Public link	例如 `https://github.com/apps/acme-langsmith-fleet`	`FLEET_GITHUB_APP_PUBLIC_LINK`
应用 slug	公共链接的最后一个路径段	`FLEET_GITHUB_APP_SLUG`
Client ID	在 About 下	`FLEET_GITHUB_APP_CLIENT_ID`

Generate a client secret

在 Client secrets 下，点击 Generate a new client secret 并复制该值。这是 FLEET_GITHUB_APP_CLIENT_SECRET。GitHub 只显示它一次。

Generate a private key

滚到 Private keys 并点击 Generate a private key。GitHub 会下载一个 .pem 文件。把该文件保管好，因为它授予对 GitHub App 的完全访问。PEM 内容就是 FLEET_GITHUB_APP_PRIVATE_KEY。

Generate a state JWT secret

LangSmith 用一个 HMAC 密钥签名短生命周期的 OAuth 状态令牌。生成一个：

bash

python3 -c "import secrets; print(secrets.token_urlsafe(48))"

这是 FLEET_GITHUB_APP_STATE_JWT_SECRET。

Create a Kubernetes secret

把敏感值存在一个 Kubernetes secret 中：

bash

kubectl create secret generic fleet-github-app \
  --namespace <your-langsmith-namespace> \
  --from-literal=client_secret="<client-secret>" \
  --from-literal=webhook_secret="<webhook-secret>" \
  --from-literal=state_jwt_secret="<state-jwt-secret>" \
  --from-file=private_key=/path/to/fleet-app.private-key.pem

对于生产部署，通过你现有的机密工作流管理这个机密（例如 Sealed Secrets 或 External Secrets Operator）。更多见使用现有 secret。

Add the configuration to your langsmith_config.yaml

添加以下内容，用上面收集的非敏感值替换占位符：

yaml

commonEnv:
  - name: FLEET_GITHUB_APP_ID
    value: "<app-id>"
  - name: FLEET_GITHUB_APP_SLUG
    value: "<app-slug>"
  - name: FLEET_GITHUB_APP_PUBLIC_LINK
    value: "https://github.com/apps/<app-slug>"
  - name: FLEET_GITHUB_APP_CLIENT_ID
    value: "<client-id>"
  - name: FLEET_GITHUB_APP_CLIENT_SECRET
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: client_secret
  - name: FLEET_GITHUB_APP_PRIVATE_KEY
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: private_key
  - name: FLEET_GITHUB_APP_WEBHOOK_SECRET
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: webhook_secret
  - name: FLEET_GITHUB_APP_STATE_JWT_SECRET
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: state_jwt_secret

fleetToolServer:
  deployment:
    extraEnv:
      - name: FLEET_GITHUB_APP_ENABLED
        value: "true"

NOTE

FLEET_GITHUB_APP_ENABLED 必须在 tool server 上设置，GitHub 工具才会被注册。其余 FLEET_GITHUB_APP_* 变量由平台后端消费，存在于 commonEnv 下。

Deploy and install the app on repositories

运行以下命令应用更改：

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

pod 健康之后：

在 LangSmith 中，打开一个 Fleet agent 并进入 agent 编辑器里的 GitHub 集成。
点击 Connect GitHub，在 Fleet 应访问的仓库上安装该应用。
对私有仓库，你必须在安装期间显式选择每个仓库。

NOTE

每个用户也必须用 LangSmith 中的重新授权流程，针对他们自己的 GitHub 账户授权该 GitHub App。这让 Fleet 能为代表用户行动的工具解析按用户的令牌。

禁用功能

要禁用 Fleet、Insights 和 Chat 的任意组合，在你的 langsmith_config.yaml 中把对应标志设为 false：

yaml

fleet:
  enabled: false

insights:
  enabled: false

polly:
  enabled: false

启用沙箱

NOTE

Azure 上的自托管沙箱需要 LangSmith Helm chart v17（0.17.x）。

沙箱默认禁用。安装后，关于 LangSmith UI 和 API 中的用户工作流，见 LangSmith 沙箱。

受支持的平台

自托管沙箱在以下平台受支持：

Amazon Elastic Kubernetes Service（EKS）
Google Kubernetes Engine（GKE）
Azure Kubernetes Service（AKS）

组件

启用沙箱会预配以下资源：

在带 KVM 能力的节点上运行沙箱工作负载的沙箱运行时 pod。
一个由 Redis 支撑、由 S3、GCS 或 Azure Blob 存储支撑对象存储的 JuiceFS 元数据存储。
可选的通配符 ingress，用于从沙箱内暴露的服务。

前提条件

Install the base LangSmith platform

在启用沙箱之前把 LangSmith 安装在 Kubernetes 上。见在 Kubernetes 上自托管 LangSmith。

沙箱在与 LangSmith release 相同的 Kubernetes 集群和命名空间中运行。

Add KVM-capable nodes

你的集群必须包含能运行带 /dev/kvm 处可用的 Linux KVM 的嵌套工作负载的专属节点。

这些可以是裸机机器或启用了嵌套虚拟化的受支持云实例。在 AWS 和 GCP 上，使用向沙箱运行时暴露 /dev/kvm 的 x86_64 Linux 实例。

WARNING

在 EKS 上，VPC CNI 附加组件必须为 v1.21 或更高。v1.20.0 在第 8 代 Intel 实例（例如 m8i）上崩溃： aws-node 进入 CrashLoopBackOff，节点报告 cni plugin not initialized，而托管节点组最终以 NodeCreationFailure: Unhealthy nodes in the kubernetes cluster 失败。

默认 Helm 调度值期望这些节点带以下标签和污点：

yaml

label:
  sandbox.langsmith.com/host: "true"
taint:
  key: sandbox.langsmith.com/host
  value: "true"
  effect: NoSchedule

如果你的节点用不同的标签或污点，覆盖 sandboxes.sandboxHost.deployment.nodeSelector 和 sandboxes.sandboxHost.deployment.tolerations。

Configure JuiceFS storage

沙箱需要 JuiceFS 支撑的共享存储。你必须提供：

一个 Redis 兼容的元数据存储。
一个对象存储桶或桶根。
一个 JuiceFS 配置 Secret，或足够的 Helm 值让 chart 创建一个。

为 sandboxes.juicefs.storage 和 sandboxes.juicefs.bucket 使用这些对象存储后端：

平台	存储值	桶格式
AWS	`s3`	区域显式的 HTTPS S3 端点，如 `https://bucket-name.s3.us-west-2.amazonaws.com`
GCP	`gs`	GCS URL，如 `gs://bucket-name`
Azure	`wasb`	Azure Blob 存储 URL，如 `https://container-name.core.windows.net`

不要在 sandboxes.juicefs.name 中使用对象存储子路径。用一个扁平名字，如 sandbox-juicefs。JuiceFS 把对象存在所配置桶内该名字之下。

TIP

对于 Redis 元数据存储，我们建议把 maxmemory-policy 设为 noeviction。这能在内存压力下避免淘汰 JuiceFS 元数据。监控 Redis 容量并在其达到内存上限前扩容。

在 noeviction 下，实例达到最大内存时 Redis 写入可能失败，所以要为沙箱元数据增长保留足够内存余量。

Configure sandbox secrets

沙箱需要额外的机密材料，用于服务间身份验证和回调签名。

如果你用 config.existingSecretName，把沙箱键加到同一个 LangSmith 应用 Secret 中。不要在 Helm 里直接设置机密值。

yaml

stringData:
  sandbox_callback_signing_jwk: '<ed25519-private-jwk>'
  # Optional, only during service-auth secret rotation:

回调签名值必须是一个 Ed25519 私有的 JWK。跨升级保持它稳定。

Choose a proxy CA mode

沙箱出口身份验证代理用这个 CA 做 TLS 拦截和凭据注入。

chart 支持两种代理 CA 模式：

模式	何时使用
`generatedSecret`	你想让 Helm 创建一个自签名 CA Secret。这是默认。
`existingSecret`	你在 LangSmith chart 之外管理该 CA Secret。该 Secret 可手动、由 cert-manager、或由另一个外部流程创建。

在不带活动集群访问渲染清单的 GitOps 工作流中，优先用 existingSecret。generatedSecret 模式用 Helm 的活动 lookup 行为在升级时复用生成的 Secret；纯渲染工作流无法读取活动 Secret，并可能在每次渲染时产生新的证书材料。

用 Helm 启用

把以下值添加到你的 langsmith_config.yaml，连同前置条件中描述的沙箱机密值。用你部署专属的值替换占位符。

yaml

images:
  sandboxHostImage:
    tag: "<same-release-tag-as-your-langsmith-images>"

sandboxes:
  enabled: true
  juicefs:
    name: "sandbox-juicefs"
    storage: "s3"
    bucket: "https://bucket-name.s3.us-west-2.amazonaws.com"
    redis:
      metaURL: "redis://redis-host:6379/1"
  sandboxHost:
    deployment:
      nodeSelector:
        kubernetes.io/arch: "amd64"
        sandbox.langsmith.com/host: "true"
    serviceAccount:
      annotations:
        eks.amazonaws.com/role-arn: "<role_arn>"

应用更新后的 chart：

bash

helm upgrade -i langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version <version> \
  --namespace <namespace> \
  --wait

用 Terraform 启用

The LangSmith Terraform modules can provision the required AWS and GCP infrastructure and generate the corresponding Helm values.

In modules/aws/infra/terraform.tfvars, enable Sandboxes and configure the sandbox node capacity:

hcl

enable_sandboxes = true
redis_source     = "external"

sandbox_juicefs_redis_instance_type             = "cache.m6g.large"
sandbox_juicefs_redis_snapshot_retention_limit  = 7

sandbox_host_node_count               = 1
sandbox_host_instance_types           = ["m5d.metal"]
sandbox_host_configure_instance_store = true

sandbox_host_image_tag = "<same-release-tag-as-your-langsmith-images>"

AWS Sandboxes require redis_source = "external". The Terraform module:

Creates a dedicated ElastiCache Redis instance for JuiceFS sandbox metadata.
Configures that dedicated instance with the recommended noeviction policy.
Reuses the LangSmith S3 bucket for sandbox object storage.
Creates the JuiceFS configuration Secret.
Adds the expected node label and taint.

The AWS setup script generates the sandbox service-auth secret, callback signing JWK, and dedicated JuiceFS Redis auth token through the normal SSM-backed setup flow. Run the infra setup script before applying Terraform if those values do not exist yet.

If you deploy the Helm release with the Terraform app module, set the sandbox app values in modules/aws/app/terraform.tfvars as well:

hcl

enable_sandboxes      = true
chart_version          = "~0.17.0"
sandbox_host_image_tag = "<same-release-tag-as-your-langsmith-images>"

When enable_sandboxes = true, the Terraform app module requires an explicit LangSmith Helm chart v17 release and a sandbox runtime image tag.

Run the normal AWS flow:

bash

make apply
make init-values
CHART_VERSION="~0.17.0" make deploy

可选：启用服务 URL

当用户需要浏览器或程序化访问沙箱内运行的 HTTP 服务时，设 sandboxes.serviceUrlBaseUrl。

yaml

sandboxes:
  serviceUrlBaseUrl: "https://sandbox-services.example.com"

这需要对 *.sandbox-services.example.com 的通配符 DNS 和 TLS。当 ingress.enabled 为 true 时，chart 还会添加一条通配符 ingress 规则，把这些服务 URL 路由到 LangSmith 平台后端。

验证安装

升级完成后，验证沙箱运行时 pod 和 JuiceFS 卷已就绪：

bash

kubectl rollout status deployment/sandbox-host -n <namespace>
kubectl get pods,pvc -n <namespace>

然后运行一次沙箱冒烟测试：

从一个公共镜像（例如一个 Python 镜像）创建一个沙箱。
在沙箱内启动一个 Python HTTP 服务器。
启用内存地对该沙箱打快照。
从该快照创建一个新沙箱。
验证 HTTP 服务器在恢复的沙箱中仍在运行。

升级说明

沙箱运行时镜像的更改通过 sandbox-host Kubernetes Deployment 推出。chart 默认用一种不surge的滚动更新策略，所以主机逐一被替换。

在一次常规 Helm 升级期间，一个正在终止的主机会停止接受新沙箱、尝试把每个运行中沙箱的 VM 内存保存到 JuiceFS，然后在 pod 退出前停止那些 VM。这次关停以 sandbox-host pod 的终止宽限期为界，默认为 300 秒。这不是实时迁移：该主机上的沙箱会在重启期间被打断。

沙箱不会被主动重启。当用户或 API 动作启动沙箱、或某个请求路径唤醒它时，它们才再次启动。然后 LangSmith 把沙箱放到一个可用主机上，并在关停捕获完成时从已存内存镜像恢复。如果内存镜像缺失或不完整，沙箱从已存根文件系统启动。

启用 Engine

INFO

自托管部署需要 LangSmith Helm chart 0.16.0 或更高，以及一份含 Engine 权限的许可证。Engine 单独授权许可并用 LCU 自行计量其用量。联系我们的销售团队把它加入你的订单。

Engine 监视生产追踪、把反复出现的失败聚成问题、诊断每个问题并提出修复。Engine 默认禁用。

Engine 需要沙箱，并在 Insights 也启用时与它共享一个部署。与本页其他功能不同，Engine 无法完全在你的集群内运行：它用 LangSmith Intelligence——一个 LangChain 管理的零数据保留服务——来做驱动诊断和修复的模型工作。

因此，Engine 的安装、出口和数据处理在一页上一起文档化。区域可用性、前置条件、Helm 值和验证步骤，见 Self-hosted 上的 Engine。

可选配置

配置额外数据平面

WARNING

不推荐；计划弃用。 通过控制平面配置额外数据平面不是推荐做法，并会在未来版本中弃用。取而代之，部署独立 Agent Server 并配置它们追踪到你自托管的 LangSmith 实例。

除上面创建的数据平面之外，你还能在不同 Kubernetes 集群中、或同一集群下不同命名空间中创建更多数据平面。有若干种方法可实现这一点，所以实现最适合你用例的方案。

前置条件

Review cluster organization

通读混合（遗留）文档中的集群组织指南，以理解如何为你的用例组织这一点。

Verify hybrid prerequisites

为新集群验证混合一节中的前置条件。在前置条件的第 5 步，把出口配到你的自托管 LangSmith 实例，而非 https://api.host.langchain.com 和 https://api.smith.langchain.com。

Enable the feature in Postgres

针对你的 LangSmith Postgres 实例运行以下命令以启用这个功能。记下工作区 ID 供后续步骤使用。

sql

update organizations set config = config || '{"enable_lgp_listeners_page": true}' where id = '<org id here>';
update tenants set config = config || '{"langgraph_remote_reconciler_enabled": true}' where id = '<workspace id here>';

部署到一个不同的集群

Follow the hybrid setup guide

遵循混合设置指南中的第 2 到 6 步。把 config.langsmithWorkspaceId 设为上一步的工作区 ID。

(Optional) Add more data planes to the same cluster

要向同一集群添加多个数据平面，遵循在同一集群中配置额外数据平面的说明。

部署到同一集群中一个不同的命名空间

Update your config

在你的 langsmith_config.yaml 中，做以下修改：

把 operator.watchNamespaces 设为你自托管 LangSmith 实例正在运行的当前命名空间。这防止与新数据平面添加的 operator 冲突。
用 Gateway API 或一个 Istio Gateway。相应调整你的 langsmith_config.yaml。

Apply the changes

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Follow the hybrid setup guide

遵循混合设置指南中的第 2 到 6 步。把 config.langsmithWorkspaceId 设为上一步的工作区 ID。把 config.watchNamespaces 设为不同于现有数据平面所用命名空间的另一个命名空间。

(Optional) Configure log access

为新命名空间配置控制平面读取 Agent Server 部署日志的访问。见从其他命名空间读取 Agent Server 日志。

为私有仓库配置身份验证

如果你的 Agent Server 部署将使用来自私有容器仓库（例如 AWS ECR、Azure ACR 或 GCP Artifact Registry）的镜像，配置镜像拉取 secret。这个配置自动适用于所有部署，让它们能向你的私有仓库身份验证。

Create a Kubernetes image pull secret

bash

kubectl create secret docker-registry langsmith-registry-secret \
    --docker-server=myregistry.com \
    --docker-username=your-username \
    --docker-password=your-password \
    --docker-email=your-email@example.com \
    -n langsmith

用你的仓库凭据替换这些值：

myregistry.com：你的仓库 URL
your-username：你的仓库用户名
your-password：你的仓库密码或访问令牌
langsmith：LangSmith 安装在其中的 Kubernetes 命名空间

Configure the deployment template in your langsmith_config.yaml

要让 agent server 部署使用这个私有仓库 secret，把 imagePullSecrets 加到 operator 的部署模板：

yaml

operator:
  templates:
    deployment: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: ${name}
        namespace: ${namespace}
      spec:
        replicas: ${replicas}
        revisionHistoryLimit: 10
        selector:
          matchLabels:
            app: ${name}
        template:
          metadata:
            labels:
              app: ${name}
          spec:
            enableServiceLinks: false
            imagePullSecrets:
            - name: langsmith-registry-secret
            containers:
            - name: api-server
              image: ${image}
              ports:
              - name: api-server
                containerPort: 8000
                protocol: TCP
              livenessProbe:
                httpGet:
                  path: /ok
                  port: 8000
                periodSeconds: 15
                timeoutSeconds: 5
                failureThreshold: 6
              readinessProbe:
                httpGet:
                  path: /ok
                  port: 8000
                periodSeconds: 15
                timeoutSeconds: 5
                failureThreshold: 6

Apply the changes

bash

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

所有通过 LangSmith UI 创建的用户部署都会继承这些仓库凭据。

关于仓库专属的身份验证方法，参阅 Kubernetes 关于从私有仓库拉取镜像的文档。

从其他命名空间读取 Agent Server 日志

WARNING

对于控制平面（host-backend）和数据平面（listener）部署在不同 Kubernetes 集群中的自托管部署，不支持检索服务器日志。

对于控制平面和数据平面在同一集群中的部署，确保控制平面 Kubernetes 部署（host-backend）有权从 Agent Server 部署所在的命名空间对 Kubernetes deployments、pods、replicasets 和 logs 执行 get、list 和 watch。有若干种方法可实现这一点。下面的例子用 Kubernetes RBAC，但用最贴合你用例的方法：

Create a Role with the required permissions

在 Agent Server 命名空间中创建一个 Role。替换 <data_plane_namespace>：

bash

kubectl apply -n <data_plane_namespace> -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: read-agent-server-logs-role
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get","list","watch"]
- apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get","watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get","list","watch"]
- apiGroups: ["apps"]
  resources: ["replicasets"]
  verbs: ["get","list","watch"]
EOF

Get the control plane ServiceAccount

替换 <control_plane_namespace>：

bash

kubectl get serviceaccounts -n <control_plane_namespace> | grep host-backend

Bind the Role to the control plane ServiceAccount

替换 <data_plane_namespace>、<control_plane_namespace> 和 <control_plane_service_account>：

bash

kubectl apply -n <data_plane_namespace> -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-agent-server-logs-role-binding
subjects:
- kind: ServiceAccount
  name: <control_plane_service_account>
  namespace: <control_plane_namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: read-agent-server-logs-role
EOF

NOTE

在这个例子中，Role 和 RoleBinding 定义在与 Agent Server 部署相同的 Kubernetes 命名空间中。你能给 Role 和 RoleBinding 指派任何名字并按需自定义它们。

后续步骤

LangSmith Deployment 一旦启用，见用控制平面部署通过 LangSmith UI 构建并部署你的应用。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织