连接到外部 Redis 或 Valkey 数据库

LangSmith 使用 Redis 来支持我们的队列/缓存操作。默认情况下，LangSmith 自托管版本将使用内部 Redis 实例。但是，您可以配置 LangSmith 使用外部 Redis 实例。通过配置外部 Redis 实例，您可以更轻松地管理 Redis 实例的备份、扩展和其他运维任务。 Valkey 也被官方支持作为 Redis 的直接替代品。本页面中任何提及 Redis 的地方，您都可以使用兼容的 Valkey 实例。有关支持的版本，请参阅要求。

每个 LangSmith 安装必须使用其专用的 Redis 实例。Redis 不能在不同的 LangSmith 安装之间共享（例如，在迁移过程中在现有集群和新集群之间共享）。在安装之间共享会导致部署任务被路由到错误的集群。

如果您使用的是托管 Redis 服务，我们推荐：

有关云特定的 IAM/工作负载身份验证，请参阅 IAM 身份验证部分。

要求

一个您的 LangSmith 实例可以网络访问的已配置的 Redis 或 Valkey 实例。我们建议使用托管服务，例如：
- Amazon ElastiCache (Redis 或 Valkey)
- Google Cloud Memorystore (Redis 或 Valkey)
- Azure Cache for Redis
支持的版本： Redis >= 5，或 Valkey 8。在本指南中，Valkey 被视为 Redis 的直接替代品。
我们支持单机版和 Redis 集群（包括 Valkey 集群）。有关部署说明，请参阅相应部分。
我们支持无身份验证、密码和 IAM/工作负载身份验证。
默认情况下，我们建议使用至少 2 个 vCPU 和 8GB 内存的实例。但是，实际要求将取决于您的追踪工作负载。我们建议监控您的 Redis 实例，并根据需要进行扩展。

单机版 Redis

连接字符串

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

主机
数据库
端口
URL 参数

其形式如下：

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

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

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

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

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

例如：

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

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

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

配置

有了连接字符串，您就可以配置 LangSmith 实例使用外部 Redis 实例。您可以通过修改 LangSmith Helm Chart 安装的 values 文件或 Docker 安装的 .env 文件来完成此操作。

redis:
  external:
    enabled: true
    connectionUrl: "您的连接 URL"

# 在您的 .env 文件中
REDIS_DATABASE_URI="您的连接 URL"

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

redis:
  external:
    enabled: true
    # 包含连接 URL 的现有 Secret 的名称
    existingSecretName: "my-redis-secret"
    # Secret 中存储连接 URL 的键（显示默认值）
    connectionUrlSecretKey: "connection_url"

apiVersion: v1
kind: Secret
metadata:
  name: my-redis-secret
type: Opaque
stringData:
  # 完整的连接 URL，例如，使用带密码的 TLS
  connection_url: "rediss://langsmith-redis:6380/0?password=foo"

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

Redis 集群

从 LangSmith helm 版本 0.12.25 开始，我们正式支持 Redis 集群。

主机名

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

redis://hostname:port

例如：

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

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

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

配置

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

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

redis:
  external:
    enabled: true
    cluster:
      enabled: true
      # 集群节点 URI 列表。格式：redis://host:port
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      # 可选。如果您的集群需要身份验证，请设置密码或使用 Secret（推荐）。
      password: "your_redis_password"
      # TLS 默认启用。如果您的集群不使用 TLS，请设置为 false。
      tlsEnabled: true

redis:
  external:
    enabled: true
    # 包含集群连接详情的现有 Secret 的名称
    existingSecretName: "my-redis-cluster-secret"
    cluster:
      enabled: true
      # Secret 中的键。此处显示默认值；如果您的 Secret 使用不同的键，请覆盖。
      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:
  # 节点 URI 的 JSON 数组（作为字符串）
  redis_cluster_node_uris: '["redis://redis-node-0:6379","redis://redis-node-1:6379","redis://redis-node-2:6379"]'
  # 如果您的集群需要密码，则为可选
  redis_cluster_password: "your_redis_password"

Azure 托管 Redis

Azure 托管 Redis 支持两种集群策略，这会影响 LangSmith 如何连接到它。请根据您实例的集群策略选择下面的配置。

OSS 集群

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

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 支持使用 EnterpriseCluster 策略的 Azure 托管 Redis。此策略公开一个端点，该端点在内部处理分片。LangSmith 必须将其作为单机（单实例）客户端连接，但它不支持不安全的集群操作，如 MULTI/EXEC。设置 redis.external.clusterSafeMode: true 以禁用不安全的集群操作。

redis:
  external:
    enabled: true
    connectionUrl: "rediss://<azure-redis-host>:6380"
    # EnterpriseCluster 必需：使用单实例客户端并禁用不安全的集群操作
    clusterSafeMode: true

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

Redis 的 TLS

使用此部分为 Redis 连接配置 TLS。有关挂载内部/公共 CA 以使 LangSmith 信任您的 Redis 服务器证书，请参阅配置自定义 TLS 证书。

服务器 TLS（单向）

要验证 Redis 服务器证书：

使用 config.customCa.secretName 和 config.customCa.secretKey 提供 CA 包。
对于单机版 Redis，在连接 URL 中使用 rediss://。
对于 Redis 集群，redis.external.cluster.tlsEnabled 默认为 true。确保未将其设置为 false。

仅当您的 Redis 服务器使用内部或私有 CA 时才挂载自定义 CA。公开受信任的 CA 不需要此配置。

config:
  customCa:
    secretName: "langsmith-custom-ca"  # 包含您的 CA 包的 Secret
    secretKey: "ca.crt"    # Secret 中包含 CA 包的键
redis:
  external:
    enabled: true
    # 使用 rediss:// 并在服务器要求时包含密码
    connectionUrl: "rediss://host:6380/0?password=<PASSWORD>"

config:
  customCa:
    secretName: "langsmith-custom-ca"  # 包含您的 CA 包的 Secret
    secretKey: "ca.crt"    # Secret 中包含 CA 包的键
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: "<PASSWORD>"

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

带客户端身份验证的双向 TLS (mTLS)

从 LangSmith helm chart 版本 0.12.29 开始，我们支持 Redis 客户端的 mTLS。有关 mTLS 中的服务器端身份验证，请使用服务器 TLS 步骤（自定义 CA），并附加以下客户端证书配置。如果您的 Redis 服务器需要客户端证书身份验证：

提供包含客户端证书和密钥的 Secret。
通过 redis.external.clientCert.secretName 引用它，并使用 certSecretKey 和 keySecretKey 指定键。
对于单机版 Redis，在连接 URL 中继续使用 rediss://。
对于 Redis 集群，redis.external.cluster.tlsEnabled 默认为 true。确保未将其设置为 false。

redis:
  external:
    enabled: true
    clientCert:
      secretName: "redis-mtls-secret"
      certSecretKey: "tls.crt"
      keySecretKey: "tls.key"
    # 单机版示例：
    # connectionUrl: "rediss://host:6380/0?password=<PASSWORD>"
    # 或者，对于集群：
    cluster:
      enabled: true
      tlsEnabled: true
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      password: "<PASSWORD>"

apiVersion: v1
kind: Secret
metadata:
  name: redis-mtls-secret
type: Opaque
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    <CLIENT_CERT>
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    <CLIENT_KEY>
    -----END PRIVATE KEY-----

用于证书卷的 Pod 安全上下文

为 mTLS 挂载的证书卷受文件访问限制保护。为确保所有 LangSmith Pod 可以读取证书文件，您必须在 Pod 安全上下文中设置 fsGroup: 1000。您可以通过以下两种方式之一进行配置： 选项 1：使用 commonPodSecurityContext 在顶层设置 fsGroup 以将其应用于所有 Pod：

commonPodSecurityContext:
  fsGroup: 1000

选项 2：添加到各个 Pod 安全上下文 如果您需要更精细的控制，请将 fsGroup 单独添加到每个 Pod 的安全上下文中。有关完整参考，请参阅 mtls 配置示例。

IAM 身份验证

从 LangSmith helm chart 版本 0.12.34 开始，我们支持 Redis 的 IAM 身份验证。这允许您使用云提供商工作负载身份而不是静态密码。

IAM 身份验证支持单机版 Redis 和 Redis 集群配置。但是，并非所有云提供商都支持所有 Redis 产品的 IAM 身份验证。请检查您的云提供商文档以验证您的特定 Redis 设置是否支持 IAM（例如，GCP 仅支持 Memorystore 集群的 IAM，不支持单机版 Memorystore）。

AWS
GCP
Azure

ElastiCache for Redis IAM 身份验证

ElastiCache for Redis 支持 IAM 身份验证，允许您使用 AWS IAM 凭据而不是 Redis AUTH 密码进行身份验证。

先决条件

使用 AWS IRSA 或 EKS Pod Identity 在 Kubernetes 集群中配置工作负载身份
在您的 ElastiCache 实例上启用 IAM 身份验证并授予工作负载身份访问权限

配置

单机版 Redis：

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

apiVersion: v1
kind: Secret
metadata:
  name: redis-secret
type: Opaque
stringData:
  # IAM 连接 URL - 身份作为用户名，无密码
  connection_url: "rediss://<iam-identity>@<elasticache-host>:6380"

Redis 集群：

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

必需的注解

您必须将 AWS IRSA 所需的 ServiceAccount 注解应用于所有连接到 Redis 的 LangSmith 组件：部署： backend、queue、platformBackend、hostBackend、ingestQueue示例配置：

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>"

有关可配置服务的完整列表，请参阅 Helm values 参考。

Memorystore for Redis IAM 身份验证

Memorystore for Redis 支持 IAM 身份验证，仅限集群实例（不支持单机版 Memorystore）。这允许您使用 GCP 服务帐户进行身份验证。

IAM 身份验证仅适用于 Memorystore 集群，不适用于单机版 Memorystore 实例。

先决条件

使用 GCP Workload Identity 在 Kubernetes 集群中配置工作负载身份
在您的 Memorystore 集群上启用 IAM 身份验证并授予工作负载身份访问权限

配置

带 IAM 的 Memorystore 集群：

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"]'

必需的注解

您必须将 GCP Workload Identity 所需的 ServiceAccount 注解应用于所有连接到 Redis 的 LangSmith 组件：部署： backend、queue、platformBackend、hostBackend、ingestQueue示例配置：

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"

有关可配置服务的完整列表，请参阅 Helm values 参考。

带 Microsoft Entra 身份验证的 Azure Cache for Redis

Azure Cache for Redis 支持 Microsoft Entra 身份验证，允许您使用 Azure 托管标识进行身份验证。

先决条件

使用 Azure Workload Identity 在 Kubernetes 集群中配置工作负载身份
在您的 Azure Cache for Redis 上启用 Microsoft Entra 身份验证并授予工作负载身份访问权限

配置

单机版 Redis：

redis:
  external:
    enabled: true
    existingSecretName: "redis-secret"
    iamAuthProvider: "azure"
    # 如果使用 EnterpriseCluster 策略则包含。详情请参阅 Azure 托管 Redis 部分。
    # clusterSafeMode: true

apiVersion: v1
kind: Secret
metadata:
  name: redis-secret
type: Opaque
stringData:
  # IAM 连接 URL - 托管标识作为用户名，无密码
  connection_url: "rediss://<managed-identity>@<azure-redis-host>:6380"

Redis 集群：

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

必需的注解

您必须将 Azure Workload Identity 所需的 ServiceAccount 注解和 Pod 标签应用于所有连接到 Redis 的 LangSmith 组件：部署： backend、queue、platformBackend、hostBackend、ingestQueue示例配置：

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"

有关可配置服务的完整列表，请参阅 Helm values 参考。

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。

Overview

Hybrid

Self-hosted

连接到外部 Redis 或 Valkey 数据库

要求

单机版 Redis

连接字符串

配置

Redis 集群

主机名

配置

Azure 托管 Redis

OSS 集群

EnterpriseCluster

Redis 的 TLS

服务器 TLS（单向）

带客户端身份验证的双向 TLS (mTLS)

用于证书卷的 Pod 安全上下文

IAM 身份验证

ElastiCache for Redis IAM 身份验证

先决条件

配置

必需的注解

Memorystore for Redis IAM 身份验证

先决条件

配置

必需的注解

带 Microsoft Entra 身份验证的 Azure Cache for Redis

先决条件

配置

必需的注解

​要求

​单机版 Redis

​连接字符串

​配置

​Redis 集群

​主机名

​配置

​Azure 托管 Redis

​OSS 集群

​EnterpriseCluster

​Redis 的 TLS

​服务器 TLS（单向）

​带客户端身份验证的双向 TLS (mTLS)

​用于证书卷的 Pod 安全上下文

​IAM 身份验证

​ElastiCache for Redis IAM 身份验证

​先决条件

​配置

​必需的注解

​Memorystore for Redis IAM 身份验证

​先决条件

​配置

​必需的注解

​带 Microsoft Entra 身份验证的 Azure Cache for Redis

​先决条件

​配置

​必需的注解

要求

单机版 Redis

连接字符串

配置

Redis 集群

主机名

配置

Azure 托管 Redis

OSS 集群

EnterpriseCluster

Redis 的 TLS

服务器 TLS（单向）

带客户端身份验证的双向 TLS (mTLS)

用于证书卷的 Pod 安全上下文

IAM 身份验证

ElastiCache for Redis IAM 身份验证

先决条件

配置

必需的注解

Memorystore for Redis IAM 身份验证

先决条件

配置

必需的注解

带 Microsoft Entra 身份验证的 Azure Cache for Redis

先决条件

配置

必需的注解