> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 为扩展配置 LangSmith

<Warning>
  本页面上的扩展指南和示例配置适用于 **LangSmith 版本 v0.13.0 或更高版本**。
</Warning>

自托管的 LangSmith 实例可以处理大量的追踪和用户。自托管部署的默认配置可以处理相当大的负载，并且您可以配置您的部署以实现更高的扩展性。本页面描述了扩展注意事项，并提供了一些示例来帮助您配置自托管实例。

有关示例配置，请参阅 [扩展的 LangSmith 配置示例](#example-langsmith-configurations-for-scale)。

## 概述

下表概述了针对不同负载模式（读取/写入）的不同 LangSmith 配置比较：

|                                                                       | **[低/低](#low-reads-low-writes)**     | **[低/高](#low-reads-high-writes)**    | **[高/低](#high-reads-low-writes)**                                                                                                                  | [中/中](#medium-reads-medium-writes)   | [高/高](#high-reads-high-writes)                                                                                                                     |
| :-------------------------------------------------------------------- | :----------------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Tooltip tip="在前端主动查看追踪的用户数量">并发前端用户数</Tooltip>                       | 5                                    | 5                                    | 50                                                                                                                                                 | 20                                   | 50                                                                                                                                                 |
| <Tooltip tip="通过 SDK 或 API 端点摄取的追踪数量">每秒提交的追踪数</Tooltip>              | 10                                   | 1000                                 | 10                                                                                                                                                 | 100                                  | 1000                                                                                                                                               |
| **前端副本数**<br />（每个副本 500m CPU，1Gi）                                    | 1（默认）                                | 4                                    | 2                                                                                                                                                  | 2                                    | 4                                                                                                                                                  |
| **平台后端副本数**<br />（每个副本 1 CPU，2Gi）                                     | 3（默认）                                | 20                                   | 3（默认）                                                                                                                                              | 3（默认）                                | 20                                                                                                                                                 |
| **摄取队列副本数**<br />（每个副本 1 CPU，2Gi）                                     | 3（默认）                                | 24                                   | 3（默认）                                                                                                                                              | 6                                    | 24                                                                                                                                                 |
| **后端副本数**<br />（每个副本 1 CPU，2Gi）                                       | 2（默认）                                | 5                                    | 40                                                                                                                                                 | 16                                   | 50                                                                                                                                                 |
| **Redis 资源**                                                          | 8 Gi（默认）                             | 26 Gi 外部                             | 8 Gi（默认）                                                                                                                                           | 13Gi 外部                              | 26 Gi 外部                                                                                                                                           |
| **ClickHouse 资源**                                                     | 4 CPU<br />16 Gi（默认）                 | 10 CPU<br />32Gi 内存                  | 8 CPU<br />每个副本 16 Gi                                                                                                                              | 16 CPU<br />24Gi 内存                  | 14 CPU<br />每个副本 24 Gi                                                                                                                             |
| **ClickHouse 设置**                                                     | 单实例                                  | 单实例                                  | 3 节点 <Tooltip tip="推荐用于高读取负载以防止性能下降。另一个选项是 [托管 ClickHouse](/langsmith/self-host-external-clickhouse#langsmith-managed-clickhouse)。">复制集群</Tooltip> | 单实例                                  | 3 节点 <Tooltip tip="推荐用于高读取负载以防止性能下降。另一个选项是 [托管 ClickHouse](/langsmith/self-host-external-clickhouse#langsmith-managed-clickhouse)。">复制集群</Tooltip> |
| <Tooltip tip="我们建议使用外部实例并启用磁盘自动扩展以处理不断增长的数据需求。">Postgres 资源</Tooltip> | 2 CPU<br />8 GB 内存<br />10 GB 存储（外部） | 2 CPU<br />8 GB 内存<br />10 GB 存储（外部） | 2 CPU<br />8 GB 内存<br />10 GB 存储（外部）                                                                                                               | 2 CPU<br />8 GB 内存<br />10 GB 存储（外部） | 2 CPU<br />8 GB 内存<br />10 GB 存储（外部）                                                                                                               |
| **Blob 存储**                                                           | 已禁用                                  | 已启用                                  | 已启用                                                                                                                                                | 已启用                                  | 已启用                                                                                                                                                |

下面我们将更详细地介绍读取和写入路径，并提供一个 `values.yaml` 代码片段，供您开始配置自托管 LangSmith 实例。

## 追踪摄取（写入路径）

给写入路径带来负载的常见用法：

* 通过 Python 或 JavaScript LangSmith SDK 摄取追踪
* 通过 `@traceable` 包装器摄取追踪
* 通过 `/runs/multipart` 端点提交追踪

在追踪摄取中起重要作用的服务：

* 平台后端服务：接收摄取追踪的初始请求，并将追踪放入 Redis 队列
* Redis 缓存：用于排队需要持久化的追踪
* 摄取队列服务：持久化追踪以供查询
* ClickHouse：用于追踪的持久化存储

在扩展写入路径（追踪摄取）时，监控上述四个服务/资源会很有帮助。以下是一些有助于提高追踪摄取性能的典型更改：

* 如果 ClickHouse 接近资源限制，请为其提供更多资源（CPU 和内存）。
* 如果摄取请求响应时间过长，请增加平台后端 Pod 的数量。
* 如果追踪未从 Redis 中快速处理，请增加摄取队列服务 Pod 的副本数。
* 如果您注意到当前 Redis 实例达到资源限制，请使用更大的 Redis 缓存。这也可能是摄取请求耗时较长的原因。

## 追踪查询（读取路径）

给读取路径带来负载的常见用法：

* 前端用户查看追踪项目或单个追踪
* 用于查询追踪信息的脚本
* 访问 `/runs/query` 或 `/runs/<run-id>` API 端点

在追踪查询中起重要作用的服务：

* 后端服务：接收请求并向 ClickHouse 提交查询，然后响应请求
* ClickHouse：追踪的持久化存储。这是请求追踪信息时查询的主要数据库。

在扩展读取路径（追踪查询）时，监控上述两个服务/资源会很有帮助。以下是一些有助于提高追踪查询性能的典型更改：

* 增加后端服务 Pod 的数量。如果后端服务 Pod 的 CPU 使用率达到 1 核，这将最具影响力。
* 为 ClickHouse 提供更多资源（CPU 或内存）。ClickHouse 可能非常消耗资源，但这应该会带来更好的性能。
* 迁移到 [复制 ClickHouse 集群](/langsmith/self-host-external-clickhouse#ha-replicated-clickhouse-cluster)。添加 ClickHouse 副本有助于提高读取性能，但我们建议副本数不超过 5 个（从 3 个开始）。

有关这如何转化为 Helm chart 值的更精确指导，请参阅以下[部分](#example-langsmith-configurations-for-scale)中的示例。如果您不确定为什么您的 LangSmith 实例无法处理某种负载模式，请联系 LangChain 团队。

## LangSmith 队列的 KEDA 自动扩展

<Note>
  在 LangSmith v0.13.0 及更高版本中可用。
</Note>

我们强烈建议在您的集群上安装 [KEDA](https://keda.sh/)（Kubernetes 事件驱动自动扩展）。KEDA 使 `queue` 和 `ingest-queue` 服务能够根据其队列积压大小以及 CPU 和内存自动扩展。这可以实现更高效的资源利用，并更好地处理流量高峰。

### 安装 KEDA

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
helm repo add kedacore https://kedacore.github.io/charts
helm install keda kedacore/keda --namespace keda --create-namespace
```

### 配置 KEDA 自动扩展

安装 KEDA 后，您可以在 `values.yaml` 中为 `queue` 和 `ingest-queue` 服务启用基于 KEDA 的自动扩展：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
queue:
  autoscaling:
    keda:
      enabled: true

ingestQueue:
  autoscaling:
    keda:
      enabled: true
```

启用 KEDA 后，队列服务将在其积压增长时自动扩展，并在积压被处理时自动缩减。这对于处理可变的追踪摄取负载而无需过度配置资源特别有用。

<Note>
  您也可以为其他服务（`backend`、`platformBackend` 等）启用 KEDA，但它们仍然只会根据 CPU 和内存进行扩展。
</Note>

## 扩展的 LangSmith 配置示例

下面我们提供一些基于预期读取和写入负载的 LangSmith 配置示例。

对于读取负载（追踪查询）：

* 低表示大约 5 个用户同时查看追踪（大约每秒 10 个请求）
* 中表示大约 20 个用户同时查看追踪（大约每秒 40 个请求）
* 高表示大约 50 个用户同时查看追踪（大约每秒 100 个请求）

对于写入负载（追踪摄取）：

* 低表示每秒最多提交 10 条追踪
* 中表示每秒最多提交 100 条追踪
* 高表示每秒最多提交 1000 条追踪

<Note>
  确切的最佳配置取决于您的用法和追踪负载。请将以下示例与上述信息以及您的具体用法结合使用，根据需要更新您的 LangSmith 配置。如果您有任何问题，请联系 LangChain 团队。
</Note>

### 低读取，低写入 <a name="low-reads-low-writes" />

默认的 LangSmith 配置将处理此负载。此处无需自定义资源配置。

### 低读取，高写入 <a name="low-reads-high-writes" />

您有非常高的追踪摄取规模，但前端同时查询追踪的用户数量为个位数。

为此，我们建议如下配置：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
config:
  blobStorage:
    # 请同时设置其他键以连接到您的 blob 存储。请参阅配置部分。
    enabled: true
  settings:
    redisRunsExpirySeconds: "3600"
# ttl:
#   enabled: true
#   ttl_period_seconds:
#     longlived: "7776000"  # 90 天（默认为 400 天）
#     shortlived: "604800"  # 7 天（默认为 14 天）

frontend:
  deployment:
    replicas: 4 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 2
#     maxReplicas: 4

platformBackend:
  deployment:
    replicas: 20 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 8
#     maxReplicas: 20

ingestQueue:
  deployment:
    replicas: 24 # 或启用下面的 KEDA 自动扩展
# autoscaling:
#   keda:
#     enabled: true
#     minReplicaCount: 8
#     maxReplicaCount: 24

backend:
  deployment:
    replicas: 5 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 3
#     maxReplicas: 5

## 确保您的 Redis 缓存至少为 26 GB 以支持高写入规模
redis:
  external:
    enabled: true
    existingSecretName: langsmith-redis-secret # 设置外部 Redis 实例的连接 URL（26+ GB）

clickhouse:
  statefulSet:
    persistence:
      # 这可能取决于您配置的 TTL（请参阅配置部分）。
      # 如果持续在此规模下运行，我们建议为每个短期 TTL 天配置 600Gi。
      size: 4200Gi # 这假设 7 天 TTL 并持续在此规模下运行。
    resources:
      requests:
        cpu: "10"
        memory: "32Gi"
      limits:
        cpu: "16"
        memory: "48Gi"

commonEnv:
  - name: "CLICKHOUSE_ASYNC_INSERT_WAIT_PCT_FLOAT"
    value: "0"
```

### 高读取，低写入 <a name="high-reads-low-writes" />

您有相对较低的追踪摄取规模，但有许多前端用户查询追踪和/或有脚本频繁访问 `/runs/query` 或 `/runs/<run-id>` 端点。

**为此，我们强烈建议设置复制 ClickHouse 集群，以在低延迟下实现高读取扩展。** 有关如何设置复制 ClickHouse 集群的更多指导，请参阅我们的 [外部 ClickHouse 文档](/langsmith/self-host-external-clickhouse#ha-replicated-clickhouse-cluster)。对于此负载模式，我们建议使用 3 节点复制设置，其中集群中的每个副本应具有 8+ 核和 16+ GB 内存的资源请求，以及 12 核和 32 GB 内存的资源限制。

为此，我们建议如下配置：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
config:
  blobStorage:
    # 请同时设置其他键以连接到您的 blob 存储。请参阅配置部分。
    enabled: true

frontend:
  deployment:
    replicas: 2

ingestQueue:
  deployment:
    replicas: 3 # 或启用下面的 KEDA 自动扩展
# autoscaling:
#   keda:
#     enabled: true
#     minReplicaCount: 2
#     maxReplicaCount: 3

backend:
  deployment:
    replicas: 40 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 16
#     maxReplicas: 40

# 我们强烈建议为此负载设置复制 ClickHouse 集群。
# 根据需要更新这些值以连接到您的复制 ClickHouse 集群。
clickhouse:
  external:
    # 如果使用 3 节点复制设置，集群中的每个副本应具有 8+ 核和 16+ GB 内存的资源请求，以及 12 核和 32 GB 内存的资源限制。
    enabled: true
    host: langsmith-ch-clickhouse-replicated.default.svc.cluster.local
    port: "8123"
    nativePort: "9000"
    user: "default"
    password: "password"
    database: "default"
    cluster: "replicated"
```

### 中读取，中写入 <a name="medium-reads-medium-writes" />

这是一个很好的通用配置，应该能够处理 LangSmith 的大多数使用模式。在内部测试中，此配置允许我们扩展到每秒摄取 100 条追踪和每秒 40 个读取请求。

为此，我们建议如下配置：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
config:
  blobStorage:
    # 请同时设置其他键以连接到您的 blob 存储。请参阅配置部分。
    enabled: true
  settings:
    redisRunsExpirySeconds: "3600"

frontend:
  deployment:
    replicas: 2

ingestQueue:
  deployment:
    replicas: 6 # 或启用下面的 KEDA 自动扩展
# autoscaling:
#   keda:
#     enabled: true
#     minReplicaCount: 3
#     maxReplicaCount: 6

backend:
  deployment:
    replicas: 16 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 8
#     maxReplicas: 16

redis:
  statefulSet:
    resources:
      requests:
        memory: 13Gi
      limits:
        memory: 13Gi

  # -- 对于外部 Redis，请使用类似以下内容 --
  # external:
  #   enabled: true
  #   connectionUrl: "<URL>" 或 existingSecretName: "<SECRET-NAME>"

clickhouse:
  statefulSet:
    persistence:
      # 这可能取决于您配置的 TTL。
      # 如果持续在此规模下运行，我们建议为每个短期 TTL 天配置 60Gi。
      size: 420Gi # 这假设 7 天 TTL 并持续在此规模下运行。
    resources:
      requests:
        cpu: "16"
        memory: "24Gi"
      limits:
        cpu: "28"
        memory: "40Gi"

commonEnv:
  - name: "CLICKHOUSE_ASYNC_INSERT_WAIT_PCT_FLOAT"
    value: "0"
```

<Warning>
  如果您使用上述配置仍然注意到读取缓慢，我们建议迁移到 [复制 ClickHouse 集群设置](/langsmith/self-host-external-clickhouse#ha-replicated-clickhouse-cluster)。
</Warning>

### 高读取，高写入 <a name="high-reads-high-writes" />

您有非常高的追踪摄取速率（接近每秒提交 1000 条追踪），并且有许多用户在前端查询追踪（超过 50 个用户）和/或脚本持续向 `/runs/query` 或 `/runs/<run-id>` 端点发出请求。

**为此，我们非常强烈建议设置复制 ClickHouse 集群，以防止在高写入规模下读取性能下降。** 有关如何设置复制 ClickHouse 集群的更多指导，请参阅我们的 [外部 ClickHouse 文档](/langsmith/self-host-external-clickhouse#ha-replicated-clickhouse-cluster)。对于此负载模式，我们建议使用 3 节点复制设置，其中集群中的每个副本应具有 14+ 核和 24+ GB 内存的资源请求，以及 20 核和 48 GB 内存的资源限制。我们还建议 ClickHouse 的每个节点/实例为每个启用的 TTL 天配置 600 Gi 的卷存储（根据以下配置）。

总体而言，我们建议如下配置：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
config:
  blobStorage:
    # 请同时设置其他键以连接到您的 blob 存储。请参阅配置部分。
    enabled: true
  settings:
    redisRunsExpirySeconds: "3600"
# ttl:
#   enabled: true
#   ttl_period_seconds:
#     longlived: "7776000"  # 90 天（默认为 400 天）
#     shortlived: "604800"  # 7 天（默认为 14 天）

frontend:
  deployment:
    replicas: 4 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 2
#     maxReplicas: 4

platformBackend:
  deployment:
    replicas: 20 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 8
#     maxReplicas: 20

ingestQueue:
  deployment:
    replicas: 24 # 或启用下面的 KEDA 自动扩展
# autoscaling:
#   keda:
#     enabled: true
#     minReplicaCount: 8
#     maxReplicaCount: 24

backend:
  deployment:
    replicas: 50 # 或启用下面的自动扩展
# autoscaling:
#   hpa:
#     enabled: true
#     minReplicas: 20
#     maxReplicas: 50

## 确保您的 Redis 缓存至少为 26 GB 以支持高写入规模
redis:
  external:
    enabled: true
    existingSecretName: langsmith-redis-secret # 设置外部 Redis 实例的连接 URL（26+ GB）

# 我们强烈建议为此负载设置复制 ClickHouse 集群。
# 根据需要更新这些值以连接到您的复制 ClickHouse 集群。
clickhouse:
  external:
    # 如果使用 3 节点复制设置，集群中的每个副本应具有 14+ 核和 24+ GB 内存的资源请求，以及 20 核和 48 GB 内存的资源限制。
    enabled: true
    host: langsmith-ch-clickhouse-replicated.default.svc.cluster.local
    port: "8123"
    nativePort: "9000"
    user: "default"
    password: "password"
    database: "default"
    cluster: "replicated"

commonEnv:
  - name: "CLICKHOUSE_ASYNC_INSERT_WAIT_PCT_FLOAT"
    value: "0"
```

<Note>
  确保 Kubernetes 集群配置了足够的资源以扩展到推荐的大小。部署后，Kubernetes 集群中的所有 Pod 都应处于 `Running` 状态。卡在 `Pending` 状态的 Pod 可能表明您已达到节点池限制或需要更大的节点。

  此外，确保集群上部署的任何入口控制器能够处理所需的负载，以防止瓶颈。
</Note>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/self-host-scale.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>