在 Kubernetes 上自托管 LangSmith

INFO

自托管 LangSmith 是企业方案（Enterprise Plan）的一个附加组件，专为最大的、最注重安全的客户设计。更多细节见我们的定价页，如果你想获取一个许可密钥在你的环境中试用 LangSmith，请联系我们的销售团队。

本页描述如何在一个 Kubernetes 集群中搭建 LangSmith（可观测性、追踪和评估）。你会用 Helm 安装 LangSmith 及其依赖。

完成本页后，你将拥有：

LangSmith UI 和 API：用于可观测性、追踪和评估。
后端服务：（queue、playground、ACE）。
数据存储：（PostgreSQL、Redis、ClickHouse、可选 blob 存储）。

关于 agent 部署：要增加部署能力，先完成本指南，然后遵循启用 LangSmith Deployment。

LangChain 已在以下 Kubernetes 发行版上成功测试过 LangSmith：

Google Kubernetes Engine (GKE)
Amazon Elastic Kubernetes Service (EKS)：有关架构模式和最佳实践，参阅在 AWS 上自托管。
Azure Kubernetes Service (AKS)：有关架构模式和最佳实践，参阅在 AKS 上自托管。
OpenShift（4.14+）
Minikube 和 Kind（用于开发目的）

TIP

更偏好基础设施即代码？ 用 Terraform 部署把集群预配、机密接线和 Helm release 为 AWS、Azure 和 GCP 打包进一个工作流。下面这页涵盖的是针对你已管理的任何兼容集群、仅用 Helm 的路径。

前置条件

确保你已备好以下工具/项。有些项标为可选：

LangSmith 许可密钥
1. 你可以从你的 LangChain 代表处获取它。更多信息请联系我们的销售团队。
API 密钥盐（Api Key Salt）
1. 这是一个你可以生成的秘密密钥。它应当是一串随机字符。
2. 你可以用以下命令生成它：
bash
```
openssl rand -base64 32
```
1
JWT 密钥（可选，但用于基本身份验证）
1. 这是一个你可以生成的秘密密钥。它应当是一串随机字符。
2. 你可以用以下命令生成它：
bash
```
openssl rand -base64 32
```
1

数据库

LangSmith 用一个 PostgreSQL 数据库、一个 Redis 缓存和一个 ClickHouse 数据库来存储追踪。默认情况下，这些服务安装在你的 Kubernetes 集群内部。不过，我们强烈建议使用外部数据库。对于 PostgreSQL 和 Redis，最好的选择是你云提供商的托管服务。

更多信息，参阅以下外部服务的设置指南：

每个数据存储的最低受支持版本，参阅自托管依赖的最低版本。

Kubernetes 集群要求

你需要一个能通过 kubectl 访问的、可用的 Kubernetes 集群。你的集群应满足以下最低要求：
1. 推荐：至少 16 vCPU、64GB 可用内存
  - 你可能需要根据组织规模/用法，为我们各个不同服务调优资源请求/限制。你可以在自托管规模指南中找到我们的建议。
  - 我们建议使用集群自动伸缩器，以根据资源使用量处理节点的扩缩。
  - 我们建议设置 metrics server，以便能开启自动缩放。
  - 如果你在集群内运行 Clickhouse，你必须有一个至少 4 vCPU、16GB 内存**可分配（allocatable）**的节点，因为 ClickHouse 默认会请求这么多资源。
2. 有效的动态 PV 预配器，或你的集群上可用的 PV（仅当你在集群内运行数据库时必需）
  - 为启用持久化，我们会尝试为任何在集群内运行的数据库预配卷。
  - 如果在你的集群中使用 PV，我们强烈建议在生产环境中设置备份。
  - 我们强烈鼓励使用由 SSD 支撑的存储类以获得更好性能。我们建议 7000 IOPS 和 1000 MiB/s 吞吐。
  - 在 EKS 上，你可能需要确保已安装并配置 ebs-csi-driver 以做动态预配。更多信息参阅 EBS CSI Driver 文档。
  你可以通过运行以下命令来验证这一点：
  bash
```
kubectl get storageclass
```
  1
  输出应至少显示一个带支持动态预配的 provisioner 的存储类。例如：
  bash
```
NAME            PROVISIONER                 RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
gp2 (default)   ebs.csi.eks.amazonaws.com   Delete          WaitForFirstConsumer   true                   161d
```
  1
  2

NOTE

  我们强烈建议使用支持卷扩展的存储类。这是因为追踪可能需要大量磁盘空间，你的卷可能需要随时间调整大小。

  有关存储类的更多信息，参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/storage/storage-classes/)。

Helm
1. 要安装 helm，参阅 Helm 文档
到 https://beacon.langchain.com 的出口（若不在离线模式下运行）
1. LangSmith 需要到 https://beacon.langchain.com 的出口来做许可验证和用量报告。这是 LangSmith 正常运作所必需的。你可以在 Egress 一节找到关于出口要求的更多信息。

NOTE

从 0.14.0 起，LangSmith 服务默认同时监听 IPv4 和 IPv6。对于仅 IPv4、仅 IPv6 或双栈集群，无需额外配置。

配置你的 Helm chart：

创建一个名为 langsmith_config.yaml 的新文件，含上一步的配置选项。
1. 你可以在 langsmith_config.yaml 文件中设置若干配置选项。特定配置选项的更多信息，你可以在 Configuration 一节找到。
2. 如果你是 Kubernetes 或 Helm 新手，我们建议从 Helm Chart 仓库 examples 目录中的示例配置之一开始，在这里：LangSmith helm chart 示例。
3. 你可以在 Helm Chart 仓库的 values.yaml 文件中看到完整的配置选项列表，在这里：LangSmith Helm Chart

WARNING

只在 langsmith_config.yaml 中覆盖你需要的那些设置；不要复制整个 values.yaml。让你的配置保持精简，能确保你继续继承 Helm chart 的新默认值和升级。

TIP

如果你的集群强制非 root 或只读容器策略，请从只读 Helm 配置示例开始。LangSmith 容器不需要 root 权限。该示例展示了如何设置 runAsNonRoot、各服务的 UID 和 GID、fsGroup、RuntimeDefault seccomp 配置、丢弃的 capabilities、禁用的权限提升，以及为需要临时存储的服务设置可写的 emptyDir 挂载。

至少，你需要设置以下配置选项（使用基本身份验证）：

WARNING

一次性设置 apiKeySalt 并不要更改它。这个值用于对静态存储的所有 API 密钥做哈希。轮换它将永久使无效你组织中每一个现有的 API 密钥，要求所有用户重新生成他们的密钥。

yaml

config:
  langsmithLicenseKey: "<your license key>"
  apiKeySalt: "<your api key salt>"
  authType: mixed
  basicAuth:
    enabled: true
    initialOrgAdminEmail: "admin@example.com" # Change this to your admin email address
    initialOrgAdminPassword: "secure-password" # Must be at least 12 characters long and have at least one lowercase, uppercase, and symbol
    jwtSecret: <your jwt salt> # A random string of characters used to sign JWT tokens for basic auth.

insights:
  enabled: true
  encryptionKey: "<insights-encryption-key>"

polly:
  enabled: true
  encryptionKey: "<chat-encryption-key>"

Insights（AI 驱动的追踪分析）和 Polly（工作区内聊天）在较新的 chart 版本中默认启用，且在安装时需要加密密钥。用类似 openssl rand -hex 32 的命令生成每个密钥。

你还需要为你使用的任何外部数据库指定连接详情。

部署到 Kubernetes：

验证你能连接到你的 Kubernetes 集群（注意：我们强烈建议安装到一个空的命名空间）
1. 运行 kubectl get pods
  输出看起来应类似：
  bash
```
  langsmith-eks-2vauP7wf 21:07:46 No resources found in default namespace.
```
  1

NOTE

如果你使用的不是默认命名空间，你需要用 -n <namespace> 标志，在 helm 和 kubectl 命令中指定命名空间。

确保你已添加 LangChain Helm 仓库（若你使用本地 chart，跳过此步）。
bash
```
helm repo add langchain https://langchain-ai.github.io/helm
```
1

找到该 chart 的最新版本。你可以在 Helm Chart 仓库中找到可用版本。

我们通常建议使用最新版本。
你也可以运行 helm search repo langchain/langsmith --versions 查看可用版本。输出看起来会像这样：

 langchain/langsmith              	0.13.0      	0.13.1    	Helm chart to deploy the langsmith application ...
 langchain/langsmith              	0.12.34      	0.12.73    	Helm chart to deploy the langsmith application ...
 langchain/langsmith              	0.12.33      	0.12.72    	Helm chart to deploy the langsmith application ...
 langchain/langsmith              	0.12.32      	0.12.70    	Helm chart to deploy the langsmith application ...
 langchain/langsmith              	0.12.31      	0.12.69    	Helm chart to deploy the langsmith application ...

运行 helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
- 把 <namespace> 替换为你想部署 LangSmith 到的命名空间。
- 把 <version> 替换为你想从上一步安装的 LangSmith 版本。多数用户应安装可用的最新版本。

NOTE

用 -n <namespace> 指定的命名空间必须在运行此命令之前就已存在。如果它不存在，你可以先用 kubectl create namespace <namespace> 创建它，或在上面的 helm 命令中加上 --create-namespace 标志。

一旦 helm install 命令运行并成功完成，你会看到类似这样的输出：

NAME: langsmith
LAST DEPLOYED: Fri Sep 17 21:08:47 2021
NAMESPACE: langsmith
STATUS: deployed
REVISION: 1
TEST SUITE: None

这可能需要几分钟完成，因为它会创建若干 Kubernetes 资源并运行若干作业来初始化数据库和其他服务。

运行 kubectl get pods 输出现在看起来应像这样（注意确切的 pod 名可能因你使用的版本和配置而异）：

 langsmith-ace-backend-98fbd468c-x9gjl         1/1     Running   0
 langsmith-backend-84999bbcb7-dfhml            1/1     Running   0
 langsmith-clickhouse-0                        1/1     Running   0
 langsmith-frontend-79bdcbccc6-r7pt7           1/1     Running   0
 langsmith-ingest-queue-cbb67748-8rl8x         1/1     Running   0
 langsmith-platform-backend-586bd9d97c-2g5mv   1/1     Running   0
 langsmith-playground-859d44b46c-fjqjh         1/1     Running   0
 langsmith-postgres-0                          1/1     Running   0
 langsmith-queue-7bd6cb8b9b-bmvxm              1/1     Running   0
 langsmith-redis-0                             1/1     Running   0

验证你的部署：

运行 kubectl get services

输出看起来应类似：

 NAME                         TYPE           CLUSTER-IP       EXTERNAL-IP                                                                   PORT(S)                      AGE
 langsmith-ace-backend        ClusterIP      172.20.92.210    <none>                                                                        1987/TCP                     1m
 langsmith-backend            ClusterIP      172.20.156.146   <none>                                                                        1984/TCP                     1m
 langsmith-clickhouse         ClusterIP      172.20.250.160   <none>                                                                        8123/TCP,9000/TCP,9363/TCP   1m
 langsmith-frontend           LoadBalancer   172.20.18.173    <external-ip>                                                                 80:30879/TCP,443:31364/TCP   1m
 langsmith-platform-backend   ClusterIP      172.20.95.187    <none>                                                                        1986/TCP                     1m
 langsmith-playground         ClusterIP      172.20.142.121   <none>                                                                        1988/TCP                     1m
 langsmith-postgres           ClusterIP      172.20.226.128   <none>                                                                        5432/TCP                     1m
 langsmith-redis              ClusterIP      172.20.57.248    <none>                                                                        6379/TCP                     1m

对 langsmith-frontend 服务的外部 IP 执行 curl：

bash

curl <external ip>/api/tenants

预期输出：

json

[{"id":"00000000-0000-0000-0000-000000000000","has_waitlist_access":true,"created_at":"2023-09-13T18:25:10.488407","display_name":"Personal","config":{"is_personal":true,"max_identities":1},"tenant_handle":"default"}]

在你的浏览器上访问 langsmith-frontend 服务的外部 IP
LangSmith UI 应当可见/可运作

使用 LangSmith

现在 LangSmith 正在运行，你可以开始用它来追踪你的代码。有关如何使用自托管 LangSmith 的更多信息，参阅自托管使用指南。

你的 LangSmith 实例现在正在运行，但可能尚未完全设置好。

如果你用了某个基本配置，会为你创建一个默认 admin 用户账户。你可以用你在 langsmith_config.yaml 文件中指定的邮箱地址和密码登录。

作为下一步，我们强烈建议与你的基础设施管理员协作来：

为你的 LangSmith 实例设置 DNS 以实现更便捷的访问
配置 SSL 以确保提交到 LangSmith 的追踪的传输中加密
用单点登录配置 LangSmith 以保护你的 LangSmith 实例
把 LangSmith 连接到外部 Postgres 和 Redis 实例
设置 Blob 存储以存储大文件

查阅我们的配置一节了解如何配置这些选项的更多信息。

启用 LangSmith Deployment、Fleet、Insights、Chat 和沙箱

要超越可观测性、追踪和评估，你可以在你的自托管实例上启用以下功能：

LangSmith Deployment：通过 LangSmith UI 部署、扩展和管理 agent。
Fleet：无需编写代码地创建和管理 AI agent。
Insights：获取对你的追踪和应用数据的 AI 驱动分析。
Chat：一个横跨 LangSmith 的工作区内聊天体验，帮你分析追踪、线程、提示和实验结果。
沙箱：从 LangSmith 运行代码、暴露临时服务并创建内存快照。

遵循启用附加功能指南来设置这些组件。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织