LangSmith uses Redis to back our queuing/caching operations. By default, LangSmith Self-Hosted will use an internal Redis instance. However, you can configure LangSmith to use an external Redis instance. By configuring an external Redis instance, you can more easily manage backups, scaling, and other operational tasks for your Redis instance.

Valkey 也被官方支持作为 Redis 的直接替代品。本页面中任何提及 Redis 的地方，您都可以使用兼容的 Valkey 实例。参见 要求 了解支持的版本。

要求

• * 一个已配置的 Redis 或 Valkey 实例，您的 LangSmith 实例将能够通过网络访问它。我们推荐使用托管服务，例如：
• * Amazon ElastiCache (Redis 或 Valkey)
• * Google Cloud Memorystore (Redis 或 Valkey)
• * Azure Cache for Redis
• * **支持的版本：** Redis >= 5 或 Valkey 8。本指南始终将 Valkey 视为 Redis 的直接替代品。
• * 我们同时支持单机版和 Redis Cluster（包括 Valkey Cluster）。请参阅相应章节了解部署说明。
• * 我们支持无身份验证、密码和 IAM/Workload Identity authentication.
• * 默认情况下，我们建议使用至少 2 个 vCPU 和 8GB 内存的实例。但是，实际需求将取决于您的追踪工作负载。我们建议监控您的 Redis 实例并根据需要进行扩展。

单机版 Redis

连接字符串

您需要为您的 Redis 实例组装连接字符串。此连接字符串应包含以下信息：

• * 主机
• * 数据库
• * 端口
• * URL 参数

格式如下：

"redis://host:port/db?<url_params>"

连接字符串示例可能如下所示：

"redis://langsmith-redis:6379/0"

注意：如果您的单机版 Redis 需要身份验证或 TLS，请将这些直接包含在连接 URL 中：

• - 使用 rediss:// 当您的 Redis 服务器启用 TLS 时。
• - 在连接字符串中提供密码。

例如：

rediss://langsmith-redis:6380/0?password=foo

对于 IAM 身份验证，请使用身份作为用户名（无密码）：

rediss://<iam-identity>@host:6380

配置

准备好连接字符串后，您可以配置 LangSmith 实例使用外部 Redis 实例。您可以通过修改 values LangSmith Helm Chart 安装的文件或 .env Docker 安装的文件。

redis:
  external:
    enabled: true
    connectionUrl: "Your connection url"

# In your .env file
REDIS_DATABASE_URI="Your connection url"

您也可以将连接 URL 存储在现有的 Kubernetes Secret 中，并在 Helm values 中引用它。

redis:
  external:
    enabled: true
    # Name of an existing Secret that contains the connection URL
    existingSecretName: "my-redis-secret"
    # Key in the Secret that stores the connection URL (default shown)
    connectionUrlSecretKey: "connection_url"

apiVersion: v1
kind: Secret
metadata:
  name: my-redis-secret
type: Opaque
stringData:
  # Full connection URL, e.g., using TLS with password
  connection_url: "rediss://langsmith-redis:6380/0?password=foo"

配置完成后，您应该能够重新安装 LangSmith 实例。如果一切配置正确，您的 LangSmith 实例现在应该使用您的外部 Redis 实例。

## Redis 集群 从 LangSmith helm 版本开始 **0.12.25**，我们正式支持 **Redis Cluster**.

主机名

使用 Redis Cluster 时，请提供节点主机名和端口列表。每个节点 URI 必须采用以下形式：

redis://hostname:port

例如：

redis://redis-node-0:6379
redis://redis-node-1:6379
redis://redis-node-2:6379

不要在这些 URI 中包含密码，也不要使用 rediss 。对于 Redis Cluster：

• - 通过以下方式单独提供密码 redis.external.cluster.password 或通过 Secret 使用 passwordSecretKey.
• - Redis Cluster 默认启用 TLS（redis.external.cluster.tlsEnabled: true）。如果您的集群不使用 TLS，请设置 tlsEnabled: false 。

配置

连接外部 Redis Cluster 时，请在以下位置配置 Helm values redis.external.cluster。您可以：

• * 直接在 values.yaml.
• * 中提供节点 URI 和（可选）密码，或引用现有的 Kubernetes Secret 包含节点 URI 和密码。

redis:
  external:
    enabled: true
    cluster:
      enabled: true
      # List of cluster node URIs. Format: redis://host:port
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      # Optional. If your cluster requires auth, set a password or use a Secret (recommended).
      password: "your_redis_password"
      # TLS is enabled by default. Set to false if your cluster does not use TLS.
      tlsEnabled: true

redis:
  external:
    enabled: true
    # Name of an existing Secret that contains cluster connection details
    existingSecretName: "my-redis-cluster-secret"
    cluster:
      enabled: true
      # Keys in the Secret. Defaults shown here; override if your Secret uses different keys.
      nodeUrisSecretKey: "redis_cluster_node_uris"
      passwordSecretKey: "redis_cluster_password"
      tlsEnabled: true

如果使用现有的 Secret，它应包含：

apiVersion: v1
kind: Secret
metadata:
  name: my-redis-cluster-secret
type: Opaque
stringData:
  # JSON array of node URIs (as a string)
  redis_cluster_node_uris: '["redis://redis-node-0:6379","redis://redis-node-1:6379","redis://redis-node-2:6379"]'
  # Optional if your cluster requires a password
  redis_cluster_password: "your_redis_password"

Azure 托管 Redis

Azure Managed Redis 支持两种影响 LangSmith 连接方式的集群策略。根据您实例的集群策略选择以下配置。

OSS 集群

LangSmith 使用 Redis Cluster 模式连接到 OSS 集群策略实例。

从 LangSmith helm chart 版本开始 **0.13.33**, ssl_check_hostname=false 支持作为节点 URI 参数。在我们的测试中，OSS 集群策略需要禁用 SSL 主机名验证。Azure 的代理将连接解析到证书 SAN 中不存在的内部节点 IP，导致主机名验证失败。

redis:
  external:
    enabled: true
    cluster:
      enabled: true
      nodeUris:
        - "redis://<node_url>:10000?ssl_check_hostname=false"
      tlsEnabled: true

EnterpriseCluster

从 LangSmith helm chart 版本开始 **0.13.33**, LangSmith supports Azure Managed Redis with the EnterpriseCluster policy. This policy exposes a single endpoint that handles sharding internally. LangSmith must connect to it as a standalone (single-instance) client, but it does not support cluster unsafe operations such as MULTI/EXEC. Set redis.external.clusterSafeMode: true 支持禁用不安全的集群操作。

redis:
  external:
    enabled: true
    connectionUrl: "rediss://<azure-redis-host>:6380"
    # Required for EnterpriseCluster: use a single-instance client and disable unsafe cluster operations
    clusterSafeMode: true

有关 EnterpriseCluster 的 Microsoft Entra (IAM) 身份验证，请参阅 IAM 身份验证中的 Azure 选项卡 并在您的 Helm values 中包含 clusterSafeMode: true 。

Redis TLS

Use this section to configure TLS for Redis connections. For mounting internal/public CAs so LangSmith trusts your Redis server certificate, see 配置自定义 TLS 证书.

服务器 TLS（单向）

要验证 Redis 服务器证书：

• - 使用 config.customCa.secretName 和 config.customCa.secretKey.
• - 提供 CA 证书包。对于独立 Redis，请在连接 URL 中使用 rediss:// 。
• - 对于 Redis Cluster， redis.external.cluster.tlsEnabled 默认为 true。请确保未将其设置为 false.

config:
  customCa:
    secretName: "langsmith-custom-ca"  # Secret containing your CA bundle
    secretKey: "ca.crt"    # Key in the Secret with the CA bundle
redis:
  external:
    enabled: true
    # Use rediss:// and include password if required by your server
    connectionUrl: "rediss://host:6380/0?password="

config:
  customCa:
    secretName: "langsmith-custom-ca"  # Secret containing your CA bundle
    secretKey: "ca.crt"    # Key in the Secret with the CA bundle
redis:
  external:
    enabled: true
    cluster:
      enabled: true
      tlsEnabled: true
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      password: ""

apiVersion: v1
kind: Secret
metadata:
  name: langsmith-custom-ca
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----

    -----END CERTIFICATE-----

使用客户端身份验证的相互 TLS (mTLS)

自 LangSmith Helm 图表版本起 **0.12.29**，我们支持 Redis 客户端的 mTLS。对于 mTLS 中的服务器端身份验证，请使用 服务器 TLS 步骤 （自定义 CA）以及以下客户端证书配置。

如果您的 Redis 服务器需要客户端证书身份验证：

• - 提供一个包含您的客户端证书和密钥的 Secret。
• - 通过以下方式引用它 redis.external.clientCert.secretName 并使用以下方式指定密钥 certSecretKey 和 keySecretKey.
• - 对于独立 Redis，继续使用 rediss:// 在连接 URL 中。
• - 对于 Redis Cluster， redis.external.cluster.tlsEnabled 默认为 true。请确保未将其设置为 false.

redis:
  external:
    enabled: true
    clientCert:
      secretName: "redis-mtls-secret"
      certSecretKey: "tls.crt"
      keySecretKey: "tls.key"
    # Standalone example:
    # connectionUrl: "rediss://host:6380/0?password="
    # Or, for Cluster:
    cluster:
      enabled: true
      tlsEnabled: true
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      password: ""

apiVersion: v1
kind: Secret
metadata:
  name: redis-mtls-secret
type: Opaque
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----

    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----

    -----END PRIVATE KEY-----

证书卷的 Pod 安全上下文

为 mTLS 挂载的证书卷受文件访问限制保护。为了确保所有 LangSmith Pod 可以读取证书文件，您必须设置 fsGroup: 1000 在 Pod 安全上下文中。

您可以通过以下两种方式之一进行配置：

**选项 1：使用 commonPodSecurityContext**

设置 fsGroup 在顶层以将其应用到所有 Pod：

commonPodSecurityContext:
  fsGroup: 1000

选项 2：添加到各个 Pod 安全上下文

如果您需要更细粒度的控制，请将 fsGroup 单独添加到每个 Pod 的安全上下文中。请参阅 mTLS 配置示例 以获取完整参考。

IAM 身份验证

自 LangSmith Helm 图表版本起 **0.12.34**，我们支持 Redis 的 IAM 身份验证。这允许您使用云提供商工作负载身份而不是静态密码。

redis:
  external:
    enabled: true
    existingSecretName: "redis-secret"
    iamAuthProvider: "aws"

apiVersion: v1
kind: Secret
metadata:
  name: redis-secret
type: Opaque
stringData:
  # IAM connection URL - identity as username, no password
  connection_url: "rediss://<iam-identity>@<elasticache-host>:6380"

redis:
  external:
    enabled: true
    existingSecretName: "redis-cluster-secret"
    iamAuthProvider: "aws"
    cluster:
      enabled: true
      nodeUrisSecretKey: "redis_cluster_node_uris"
      tlsEnabled: true

backend:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

queue:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

platformBackend:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

hostBackend:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

ingestQueue:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

redis:
  external:
    enabled: true
    existingSecretName: "redis-cluster-secret"
    iamAuthProvider: "gcp"
    cluster:
      enabled: true
      nodeUrisSecretKey: "redis_cluster_node_uris"
      tlsEnabled: true

apiVersion: v1
kind: Secret
metadata:
  name: redis-cluster-secret
type: Opaque
stringData:
  redis_cluster_node_uris: '["redis://node-0:6379","redis://node-1:6379","redis://node-2:6379"]'

backend:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

queue:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

platformBackend:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

hostBackend:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

ingestQueue:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

redis:
  external:
    enabled: true
    existingSecretName: "redis-secret"
    iamAuthProvider: "azure"
    # Include if using EnterpriseCluster policy. See the Azure managed Redis section for details.
    # clusterSafeMode: true

apiVersion: v1
kind: Secret
metadata:
  name: redis-secret
type: Opaque
stringData:
  # IAM connection URL - managed identity as username, no password
  connection_url: "rediss://<managed-identity>@<azure-redis-host>:6380"

redis:
  external:
    enabled: true
    existingSecretName: "redis-cluster-secret"
    iamAuthProvider: "azure"
    cluster:
      enabled: true
      nodeUrisSecretKey: "redis_cluster_node_uris"
      tlsEnabled: true

backend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

queue:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

platformBackend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

hostBackend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

ingestQueue:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"