Self-hosted 上的 LangSmith Engine

在一个自托管 LangSmith 实例上安装 LangSmith Engine，并理解它在你环境之外依赖什么、以及它如何处理你的数据。

INFO

自托管 Engine 需要 LangSmith Helm chart 0.16.0 或更高，以及一份含 Engine 权限的许可证。它在较早的 chart 版本上不可用。联系我们的销售团队把该权限加入你的订单。

LangSmith Engine 是 LangSmith 内的一个 agent，它监控你的生产追踪、把它们聚成问题、针对你的源码诊断每个问题、以一个 PR 提出修复，并识别要加入你数据集的真实评估。产品概览见 Engine。

在自托管 LangSmith 中，Engine 的编排（包括它的检测、修复、验证循环）作为 LangSmith 的一部分在你的 VPC 内运行。模型工作无法完全在你的 VPC 内运行：Engine 把它需要的内容发送到 LangSmith Intelligence（LSI），一个 LangChain 管理的零数据保留（ZDR）服务。

本页讲述两半：Engine 在你环境之外依赖什么，以及如何在你的实例上安装 Engine。要把 Engine 连到你的源码，按把 Engine 连到 GitHub所述创建并配置你自己的 GitHub App。

Engine 处理三类数据：

• 代码（可选）： 你 agent 的源码，Engine 读它来诊断问题并提出修复。
• 追踪： 来自你 agent 的运行时数据，可能包含用户消息、工具输出和 PII。
• 模型： Engine 为运行诊断、生成修复、编写评估器而做的 LLM 调用。

按云和区域的可用性

Engine 在 LSI 可用之处可用：

云	区域	状态
AWS	美国	可用
GCP	美国	可用

其他区域的可用性，联系我们的销售团队。

工作原理

LSI 是驱动 Engine 的 LangChain 管理服务。

流程：

• 你自托管的 Engine 为它的云向 LSI 网关发一个 HTTPS 请求，网关列在本页的按云小节中。
• Engine 用 LangSmith 许可验证期间获得的一个短生命周期许可 JWT 进行身份验证。你不提供单独的模型提供商凭据。
• LSI 验证 JWT，并在 LangChain 环境内通过私有网络把请求路由到模型提供商。
• LSI 把响应返回给你自托管的 Engine。

每个请求携带 Engine 完成其工作所需的追踪内容、代码和中间输出。LSI 和模型提供商处理那内容以服务该请求。

你的集群必须允许向那个网关的出站 HTTPS。连接可用公共出口或私有连接。在 AWS 上，遵循用 AWS PrivateLink 连接把 Engine 流量保持在私有网络上。

如果到 LSI 的连接不可用，Engine 会停止并返回一个错误，而非降级到更低质量的输出。没有集群内模型，也没有可退回的次级提供商。你 LangSmith 部署的其余部分不受影响，Engine 会在它下次计划扫描时再试。

LangSmith Intelligence 保留什么

LSI 不持久化提示或模型响应的内容。它为用量归属和计费保留以下元数据：

• 用于归属用量的账户、工作区和项目标识符。
• 用于计费的模型和 token 用量元数据。

有关模型提供商的保留和训练承诺，见 Engine 安全。

按云连接

AWS（在美国可用）

网关主机是 beacon.aws.langchain.com。LSI 在 LangChain 的 AWS 环境中把请求路由到 AWS Bedrock。

用 AWS PrivateLink 连接

在配置 PrivateLink 之前，完成安装 Engine，包括其 Helm 和出口配置。

AWS PrivateLink 把 Engine 流量从你的 VPC 路由到 LSI，而不把该流量暴露给公共互联网。LSI 端点服务托管在 us-east-2，AWS 支持从其他区域的 VPC 访问。

开始之前，收集你的 AWS 账户 ID、VPC ID、私有子网 ID，以及给接口端点的一个安全组。把那个端点安全组配置为只允许来自运行 Engine 的节点或工作负载所附安全组、或包含它们的最小私有 CIDR 的入站 TCP 443 端口流量。不要允许 0.0.0.0/0。

要把你的 VPC 连到 LSI：

Request access

带上你的 AWS 账户 ID 联系你的客户代表或 sales@langchain.dev。LangChain 把你的账户加入端点服务的允许主体列表。

Create the interface VPC endpoint

为包含你 VPC 的区域配置 AWS 提供商。把 service_region 保持设为 us-east-2，即使你的 VPC 在另一个区域。每个可用区选一个私有子网。

NOTE

service_region 参数需要 HashiCorp AWS 提供商 5.82.0 或更高。

resource "aws_vpc_endpoint" "langsmith_intelligence" {
  vpc_id              = var.vpc_id
  service_name        = "com.amazonaws.vpce.us-east-2.vpce-svc-054f37092752bff6b"
  service_region      = "us-east-2"
  vpc_endpoint_type   = "Interface"
  subnet_ids          = var.private_subnet_ids
  security_group_ids  = [var.security_group_id]
  private_dns_enabled = false
}

Wait for LangChain to accept the connection

端点状态在 LangChain 接受连接后从 pendingAcceptance 变为 available。在测试连通性之前，允许几分钟让该变化传播。

Route the LSI hostname to the endpoint

为你的 VPC 启用 DNS 解析和 DNS 主机名。然后，创建一个 Route 53 私有托管区和别名记录，使 beacon.aws.langchain.com 在你的 VPC 内解析到 VPC 端点。保持这个主机名不变，以便 TLS 证书验证成功。私有托管区还能在端点不可用时防止回退到公共 DNS。

resource "aws_route53_zone" "langsmith_intelligence" {
  name = "beacon.aws.langchain.com"

  vpc {
    vpc_id = var.vpc_id
  }
}

resource "aws_route53_record" "langsmith_intelligence" {
  zone_id = aws_route53_zone.langsmith_intelligence.zone_id
  name    = "beacon.aws.langchain.com"
  type    = "A"

  alias {
    name                   = aws_vpc_endpoint.langsmith_intelligence.dns_entry[0].dns_name
    zone_id                = aws_vpc_endpoint.langsmith_intelligence.dns_entry[0].hosted_zone_id
    evaluate_target_health = true
  }
}

如果工作负载用一个企业 DNS 解析器而非 Amazon 提供的解析器，配置到 Route 53 Resolver 的条件转发，或为 beacon.aws.langchain.com 创建一个指向端点 DNS 名的等价私有 DNS 覆盖。

Verify private connectivity

从一个运行 Engine 的节点或容器，解析网关主机名：

getent ahostsv4 beacon.aws.langchain.com

确认结果包含分配给端点网络接口的私有 IP 地址。然后启动一次分析并确认它成功完成。如果分析没完成，审阅 Engine 的安装和出口配置。

AWS: LangSmith and Engine run in your VPC; LSI and Bedrock run in LangChain's AWS environment.

GCP（在美国可用）

网关主机是 beacon.langchain.com。LSI 在 LangChain 的 GCP 环境中把请求路由到 Vertex。

NOTE

这与自托管 LangSmith 用于许可验证和计费遥测的同一主机，所以一个 GCP 部署添加的是一个路径而非一个新的出口目的地。见配置出口。

GCP: LangSmith and Engine run in your project; LSI and Vertex run in LangChain's GCP environment.

模型选择与质量

Engine 通过 LSI 使用你那个云的模型提供商：AWS 上的 Amazon Bedrock，GCP 上的 Vertex AI。

Engine 使用不同的模型，各自为其角色调优，来聚问题、针对你的代码诊断根因、生成修复，并编写验证它们的评估器。LangChain 为质量和 token 效率调优这些模型，并在有更好模型可用时更新它们。

Engine 使用托管推理，而非自带密钥的设置。这让 Engine 行为保持一致，并随 LangChain 更新模型而改进。在自带密钥的设置下，模型选择、调优和 token 效率可能因请求而异。

Engine 在何处处理数据

在自托管部署中，Engine 在你的环境和 LangChain 的环境之间分离数据处理：

• 你的环境： Engine 编排和 LangSmith 存储的追踪留在你自托管的环境中。
• LangChain 的环境： LSI 和模型提供商处理 Engine 发送的内容。LSI 保留上面所述的计费元数据。

Engine 与部署无关的数据处理，包括对每个模型提供商的零数据保留、以及不使用客户数据来训练或微调模型，在 Engine 安全中描述。

安装 Engine

Engine 默认禁用。它需要沙箱、一个到 LangSmith Intelligence的连接、一个外部可达的 config.hostname，以及一个 Engine 加密密钥。在启用 Engine 之前完成前置条件。

Engine 和 Insights 从同一镜像运行并共享一个部署。Engine 不需要 Insights。如果你的安装已经运行 Insights，启用 Engine 只是添加配置而非新 pod。

组件

启用 Engine 会预配或复用：

• standalone-insights-api-server：同时服务 engine 和 insights 图。
• standalone-insights-queue：Engine 和 Insights 的后台运行处理。
• 给共享部署的一个专属 PostgreSQL 和 Redis 实例，各可用一个外部实例替代。
• 启用沙箱下描述的沙箱组件。

Engine 还给 platform-backend 和 ingest-queue 添加配置，它们分发并调度其运行。

前提条件

Enable Sandboxes

先完成启用沙箱，包括带 KVM 能力的节点池和 JuiceFS 存储。

Engine 的沙箱与一个工作区关联。一个带 Engine 的安装必须有一个共享组织。如果共享组织恰好有一个工作区，LangSmith 用那个工作区。如果共享组织有不止一个工作区，LangSmith 不会自动选一个。你必须把 engine.sandboxTenantId 设为工作区 ID。

WARNING

使用一个为 Engine 保留的工作区：

• Engine 的沙箱不在沙箱产品上计费，因为 Engine 用 LCU 自行计其用量。
• Engine 的沙箱使用与工作区中其他沙箱相同的并发沙箱、CPU 和内存配额。如果工作区接近其上限，Engine 运行可能失败或给交互式沙箱留下更少容量。
• Engine 的沙箱列在那个工作区中，并可被任何有它访问权的人停止。
• 每个沙箱运行 agent 生成的代码。
• 仓库凭据留在沙箱 auth 代理中，对沙箱内运行的代码不可用。

Confirm the license entitlement

Engine 单独授权许可，方式与沙箱相同。你的许可证必须携带 Engine 权限。LangSmith 在启动时并此后周期性地对照 https://beacon.langchain.com 验证你的许可密钥，所以一旦权限被加入你的订单，它就生效而无需你更改任何配置。

Allow egress to LangSmith Intelligence

允许从集群到那个云的 LangSmith Intelligence 网关 URL 的出站 HTTPS。把这个 URL 用作 engine.intelligenceBaseUrl 的值。

云	engine.intelligenceBaseUrl
AWS	https://beacon.aws.langchain.com/intelligence
GCP	https://beacon.langchain.com/intelligence

在 GCP 上，这使用 LangSmith 已用于许可验证和计费遥测的同一主机，所以 Engine 添加的是一个路径而非一个新的出口目的地。

NOTE

Engine 对位于 AWS 美国和 GCP 美国的自托管部署可用。在规划一次推出之前，查按云和区域的可用性并向我们的销售团队确认覆盖。

把网关添加为一个具体的允许列表条目，而非开放常规出口。要把 AWS 流量保持在私有网络上，用 AWS PrivateLink 连到 LangSmith Intelligence。请求使用 LangSmith 许可验证期间获得的一个短生命周期许可 JWT。Engine 的流量与配置出口中描述的计费和运营遥测分开，即使它在共享同一主机的地方也是如此。

NOTE

离线（气隙）安装无法运行 Engine。没有可供它退回的集群内模型。

Verify your hostname is externally reachable

Engine 的沙箱用 langsmith CLI 调用你的 LangSmith 安装，所以 config.hostname 必须从沙箱网络可达。Helm 验证会拒绝 localhost 和集群内 *.svc 地址。

通过你的 ingress 带 TLS 服务那个主机名，如设置一个 ingress所述。Engine 不要求你暴露超出你自己用户已经能访问的地址之外的任何东西。沙箱出口被允许列表限定为你的 LangSmith 主机名、github.com、api.github.com 和 Python 包仓库。按运行的凭据由沙箱之外的一个代理注入，而非在沙箱内可读。

Generate the Engine encryption key

Engine 用它自己的 Fernet 密钥加密 LangSmith 传给它的运行载荷，这些载荷携带短生命周期凭据。生成一个：

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

把它作为 engine_encryption_key 存在你预定义的 Kubernetes Secret 中，而非在你的配置文件里。见使用现有 secret。

要以后轮换该密钥，把当前值复制到 engine_encryption_key_previous 并把新密钥设为 engine_encryption_key。前一个密钥只被接受用于解密，所以就在切换前被加密的运行仍能完成。

用 Helm 启用

把以下内容添加到你的 langsmith_config.yaml，连同启用沙箱的完整沙箱 values。这些例子只展示 Engine 专属的值和 sandboxes.enabled 标志。

按名字引用你现有的 Secret。chart 会自动从中读取 engine_encryption_key。

config:
  existingSecretName: "<your-secret-name>"
  # Must be reachable from the sandbox network.
  hostname: "https://langsmith.example.com"

engine:
  enabled: true
  intelligenceBaseUrl: "https://beacon.aws.langchain.com/intelligence"

sandboxes:
  enabled: true

NOTE

如果你的安装有一个含不止一个工作区的共享组织，设置那个拥有 Engine 沙箱的工作区：

engine:
  sandboxTenantId: "<workspace-id>"

WARNING

从较早 Insights 镜像锁定的升级需要一项额外检查：如果你的 values 把 images.engineInsightsAgentImage.repository 锁到已退役的 langsmith-clio 镜像，请移除或更新那个锁定。Engine 和 Insights 现在在 langsmith-insights-engine 上运行，chart 会拒绝 langsmith-clio。更多信息，见为你的 LangSmith 安装镜像。

在应用更新后的 chart 之前验证它：

helm template langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version <version> \
  --namespace <namespace>

chart 在渲染时验证 Engine 配置，并带着一个点名缺失值的消息失败，所以这条命令能在错误配置到达你的集群之前捕获它。

应用更新后的 chart：

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

验证安装

确认共享的 Engine 和 Insights 部署正在运行：

kubectl get pods -n <namespace> | grep standalone-insights

API 服务器和队列 pod 都应为 Running。然后，确认 platform-backend 健康，因为它分发 Engine 运行：

kubectl rollout status deployment/langsmith-platform-backend -n <namespace>

如果这之后 Engine 没出现在 LangSmith UI 中，最常见的原因是一个没有 Engine 权限的许可证，以及在 LangSmith 中打开 Engine中描述的组织级开关。

在 LangSmith UI 中启用并配置 Engine之后，启动一次 Engine 分析并确认结果出现在那个追踪项目上。这验证了跨 Engine、沙箱和 LangSmith Intelligence 的完整路径。仅运行中的 pod 并不验证那条路径。

如果分析没完成，检查 Engine pod 是否在运行、沙箱工作区是否有可用配额，以及集群能否到达 engine.intelligenceBaseUrl 中配置的 LangSmith Intelligence 网关 URL。

在 LangSmith 中打开 Engine

在 Helm 中启用 Engine 使该功能可用；它不启动任何扫描。启用 chart 值之后，在 LangSmith 中完成设置：

1. 一个 Organization Admin在 Settings > Engine enablement 下为该组织打开 Engine。更多信息，见发现并修复问题。
2. 任何用户都能从某追踪项目的 Engine 标签为该项目打开 Engine。更多信息，见为一个追踪项目打开 Engine。

连接一个 GitHub 仓库是可选的，并会改善 Engine 的诊断和修复。没有它，Engine 无法读你的源码或开拉取请求。要创建 GitHub App 并配置 host-backend，见把 Engine 连到 GitHub。

禁用 Engine

把 engine.enabled 设为 false 并重新 apply：

engine:
  enabled: false

Engine 停止分发运行。Insights 共享同一部署，所以当 insights.enabled 为 true 时 standalone-insights pod 继续运行。

另请参阅

• Engine
• 配置 Engine
• 把 Engine 连到 GitHub
• Engine 安全
• Engine 通知
• 启用额外的 LangSmith 功能

---