连接到外部 Redis 或 Valkey 数据库

LangSmith 用 Redis 支撑我们的队列/缓存操作。默认情况下，LangSmith Self-Hosted 会用一个内部的 Redis 实例。不过，你可以配置 LangSmith 使用一个外部 Redis 实例。通过配置一个外部 Redis 实例，你能更轻松地管理该 Redis 实例的备份、扩容和其他运营任务。

Valkey 也作为 Redis 的即用替代方案被官方支持。本页任何提到 Redis 之处，你都可以使用一个兼容的 Valkey 实例。受支持的版本见要求。

WARNING

每个 LangSmith 安装必须使用它自己专属的 Redis 实例。Redis 不能跨独立的 LangSmith 安装共享（例如，在迁移期间在现有和新集群之间）。跨安装共享它会导致部署任务被路由到错误的集群。

TIP

如果你使用托管 Redis 服务，我们推荐：

关于云专属的 IAM/Workload Identity 身份验证，参阅 IAM 身份验证一节。

要求

一个已预配的 Redis 或 Valkey 实例，你的 LangSmith 实例将能网络访问到它。我们推荐使用像以下这样的托管服务：
- Amazon ElastiCache（Redis 或 Valkey）
- Google Cloud Memorystore（Redis 或 Valkey）
- Azure Cache for Redis
受支持的版本： Redis 6.2 或更高，或 Valkey 8。在本指南中，Valkey 被视为 Redis 的即用替代方案。
我们同时支持 Standalone 和 Redis Cluster（包括 Valkey Cluster）。有关部署说明，见相应的小节。
我们支持无身份验证、密码，以及 IAM/Workload Identity 身份验证。
默认情况下，我们推荐一个至少 2 vCPU、8GB 内存的实例。不过，实际要求会取决于你的追踪工作负载。我们建议监控你的 Redis 实例并按需扩容。

NOTE

Redis 6.2 之所以是底线，是因为 Agent Server（langgraph-api）0.8.0 引入的 Redis 支撑的运行队列。该队列用 ZADD ... LT 标志入队运行，而这个标志是在 Redis 6.2 中加入的。在 Redis 5.0 到 6.1 上，运行入队会以一个不指示版本不匹配的泛化 ERR syntax error 失败。Valkey 8 包含该标志。

TIP

如果你启用 LangSmith 沙箱，我们建议把用于沙箱存储的 Redis 元数据存储的 Redis maxmemory-policy 设为 noeviction。这能在内存压力下避免淘汰文件系统元数据。在 noeviction 下，当实例达到最大内存时 Redis 写入可能失败，因此要保留足够内存余量给沙箱元数据增长。

Standalone Redis

连接字符串

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

主机
数据库
端口
URL 参数

它将采取如下形式：

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

一个连接字符串的例子可能看起来像：

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

注意：如果你的 Standalone Redis 需要身份验证或 TLS，请把这些直接包含在连接 URL 中：

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

例如：

text

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

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

text

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

配置

有了连接字符串，你就可以配置你的 LangSmith 实例使用外部 Redis 实例。你可以通过修改你 LangSmith Helm Chart 安装的 values 文件来做到这一点。

yaml

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

你也可以把连接 URL 存在一个现有的 Kubernetes Secret 中，并在你的 Helm values 中引用它。

Helm (using an existing Secret)Kubernetes Secret

yaml

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"

yaml

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 cluster

从 LangSmith helm 版本 0.12.25 起，我们官方支持 Redis Cluster。

主机名

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

text

redis://hostname:port

例如：

text

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

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

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

配置

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

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

Helm (inline values)Helm (using an existing Secret)

yaml

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

yaml

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，它应包含：

Kubernetes Secret

yaml

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 managed Redis

Azure Managed Redis 支持两种影响 LangSmith 如何连接它的集群策略。根据你实例的集群策略，选择下面的配置。

OSS Cluster

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

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

yaml

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 Managed Redis。该策略暴露一个内部处理分片的单一端点。LangSmith 必须作为 standalone（单实例）客户端连接它，但它不支持 cluster 不安全操作，例如 MULTI/EXEC。设 redis.external.clusterSafeMode: true 以禁用不安全的集群操作。

yaml

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

用这一节为 Redis 连接配置 TLS。有关挂载内部/公共 CA 使 LangSmith 信任你的 Redis 服务器证书，参阅配置自定义 TLS 证书。

服务器 TLS（单向）

要验证 Redis 服务器证书：

用 config.customCa.secretName 和 config.customCa.secretKey 提供一个 CA 包。
对于 Standalone Redis，在连接 URL 中使用 rediss://。
对于 Redis Cluster，redis.external.cluster.tlsEnabled 默认为 true。确保它没被设为 false。

WARNING

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

Helm (Standalone - server TLS)Helm (Cluster - server TLS)Kubernetes Secret (CA bundle)

yaml

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

yaml

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

yaml

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 指定密钥。
对于 Standalone Redis，继续在连接 URL 中使用 rediss://。
对于 Redis Cluster，redis.external.cluster.tlsEnabled 默认为 true。确保它没被设为 false。

Helm (client Auth)Kubernetes Secret (client cert/key)

yaml

redis:
  external:
    enabled: true
    clientCert:
      secretName: "redis-mtls-secret"
      certSecretKey: "tls.crt"
      keySecretKey: "tls.key"
    # Standalone example:
    # connectionUrl: "rediss://host:6380/0?password=<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: "<PASSWORD>"

yaml

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：

yaml

commonPodSecurityContext:
  fsGroup: 1000

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

如果你需要更细粒度的控制，把 fsGroup 逐个添加到每个 pod 的安全上下文。完整参考见 mtls 配置示例。

IAM 身份验证

从 LangSmith helm chart 版本 0.12.34 起，LangSmith 支持 standalone Redis 的 IAM 身份验证。从 LangSmith 版本 v0.16.0（v16）起，Redis Cluster 也支持 IAM 身份验证。这让你能用云提供商的工作负载身份而非静态密码。

NOTE

带 IAM 身份验证的 Redis Cluster 需要 LangSmith v0.16.0 或更高。较早的 LangSmith 版本只对 standalone Redis 支持 IAM 身份验证。另外，并非所有云提供商都为其所有 Redis 产品支持 IAM 身份验证。查阅你云提供商的文档，以核实对你特定 Redis 设置的 IAM 支持（例如，GCP 只对 Memorystore Cluster 支持 IAM，不支持 standalone Memorystore）。

ElastiCache for Redis IAM 身份验证

ElastiCache for Redis 支持 IAM 身份验证，它让你能用 AWS IAM 凭据而非 Redis AUTH 密码来身份验证。

前置条件

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

配置

Standalone Redis：

yaml

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

yaml

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 Cluster：

yaml

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 组件：

Deployments： backend、queue、platformBackend、hostBackend、ingestQueue

配置示例：

yaml

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 参考。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织