Skip to main content
LangSmith 使用 Redis 来支持我们的队列/缓存操作。默认情况下，LangSmith 自托管版本将使用内部 Redis 实例。但是，您可以配置 LangSmith 使用外部 Redis 实例。通过配置外部 Redis 实例，您可以更轻松地管理 Redis 实例的备份、扩展和其他运维任务。 Valkey 也被官方支持作为 Redis 的直接替代品。本页面中任何提及 Redis 的地方，您都可以使用兼容的 Valkey 实例。有关支持的版本，请参阅要求。
每个 LangSmith 安装必须使用其专用的 Redis 实例。Redis 不能在不同的 LangSmith 安装之间共享（例如，在迁移过程中在现有集群和新集群之间共享）。在安装之间共享会导致部署任务被路由到错误的集群。
如果您使用的是托管 Redis 服务，我们推荐：有关云特定的 IAM/工作负载身份验证，请参阅 IAM 身份验证部分。

​
要求

  • 一个您的 LangSmith 实例可以网络访问的已配置的 Redis 或 Valkey 实例。我们建议使用托管服务，例如：
  • 支持的版本： 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"
您也可以将连接 URL 存储在现有的 Kubernetes Secret 中，并在 Helm values 中引用它。 
redis:
  external:
    enabled: true
    # 包含连接 URL 的现有 Secret 的名称
    existingSecretName: "my-redis-secret"
    # Secret 中存储连接 URL 的键（显示默认值）
    connectionUrlSecretKey: "connection_url"
配置完成后，您应该能够重新安装 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
如果使用现有 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>"

​
带客户端身份验证的双向 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>"

​
用于证书卷的 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）。

​
ElastiCache for Redis IAM 身份验证

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

​
先决条件

  1. 使用 AWS IRSA 或 EKS Pod Identity 在 Kubernetes 集群中配置工作负载身份
  2. 在您的 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 参考。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。