启用 Blob 存储

默认情况下，LangSmith 将运行的输入、输出、错误、清单、附加信息和事件存储在 ClickHouse 中。如果您愿意，可以改为将这些信息存储在 Blob 存储中，这有几个显著的优势。为了在生产部署中获得最佳效果，我们强烈建议使用 Blob 存储，它提供以下好处：

在高追踪环境中，输入、输出、错误、清单、附加信息和事件可能会使您的数据库大小急剧膨胀。
如果您使用的是 LangSmith 托管 ClickHouse，您可能希望将敏感信息存储在您环境内的 Blob 存储中。为了解决这个问题，LangSmith 支持将运行的输入、输出、错误、清单、附加信息、事件和附件存储在外部 Blob 存储系统中。

针对特定云平台的设置，请选择您的平台：

Amazon S3 (AWS)
Google Cloud Storage (GCP)
Azure Blob Storage

有关完整的特定云平台设置和架构指南，请参阅 AWS、GCP 或 Azure。

要求

Azure Blob 存储在 Helm Chart 版本 0.8.9 及更高版本中可用。删除追踪项目在 Azure 中从 Helm Chart 版本 0.10.43 开始支持。原生 GCS Blob 存储引擎支持（使用 engine: "GCS"）在 Helm Chart 版本 0.13.29 及更高版本中可用。对于早期版本，GCS 通过 S3 兼容的 API 支持，需设置 engine: "S3" 并使用 HMAC 凭证。

访问一个有效的 Blob 存储服务
Blob 存储中用于存储数据的桶/目录。我们强烈建议为 LangSmith 数据创建一个单独的桶/目录。
- 如果您正在使用 TTL，您将需要设置生命周期策略来删除旧数据。有关更多信息，请参阅配置 TTL。这些策略应与您在 LangSmith 配置中设置的 TTL 相匹配，否则您可能会遇到数据丢失。请参阅 Blob 存储的 TTL 配置了解如何设置生命周期规则。
允许 LangSmith 服务访问桶/目录的凭证
- 您需要为您的 LangSmith 实例提供访问桶/目录所需的凭证。请阅读下面的认证部分以获取更多信息。
如果使用 S3 或 GCS，需要一个用于您的 Blob 存储服务的 API URL
- 这将是 LangSmith 用于访问您的 Blob 存储系统的 URL
- 对于 Amazon S3，这将是 S3 端点的 URL。类似于：https://s3.amazonaws.com 或 https://s3.us-west-1.amazonaws.com（如果使用区域端点）。
- 对于 Google Cloud Storage，这将是 GCS 端点的 URL。类似于：https://storage.googleapis.com

认证

AWS
GCP
Azure

Amazon S3

要向 Amazon S3 进行认证，您需要创建一个 IAM 策略，授予以下对您桶的权限。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

一旦您有了正确的策略，有三种方式可以向 Amazon S3 进行认证：

IAM Roles for Service Accounts (IRSA)（推荐）：您可以为您的 LangSmith 实例创建一个 IAM 角色并将该策略附加到该角色。这是在生产环境中向 Amazon S3 认证的推荐方式。
1. 您需要创建一个附加了该策略的 IAM 角色。
2. 您需要允许 LangSmith 服务账户承担该角色。langsmith-queue、langsmith-backend、langsmith-platform-backend 和 langsmith-ingest-queue 服务账户需要能够承担该角色。
  如果您使用自定义发布名称，服务账户名称会有所不同。您可以通过在集群中运行 kubectl get serviceaccounts 来找到服务账户名称。
3. 您需要将角色 ARN 提供给 LangSmith。您可以通过在 Helm Chart 安装中为 queue、backend、platform-backend 和 ingest-queue 服务添加 eks.amazonaws.com/role-arn: "<role_arn>" 注释来实现。
Access Key and Secret Key：您可以向 LangSmith 提供访问密钥和秘密密钥。这是向 Amazon S3 认证的最简单方式。但是，由于安全性较低，不建议在生产中使用。
1. 您需要创建一个附加了该策略的用户。然后您可以为该用户配置访问密钥和秘密密钥。
VPC Endpoint Access：您可以通过 VPC 端点启用对 S3 桶的访问，这允许流量安全地从您的 VPC 流向您的 S3 桶。
1. 您需要配置一个 VPC 端点并将其设置为允许访问您的 S3 桶。
2. 您可以参考我们的公共 Terraform 模块获取配置指导和示例。

KMS 加密头支持

从 LangSmith Helm Chart 版本 0.11.24 开始，您可以通过提供其 ARN 来传递 KMS 加密密钥头并强制写入时使用特定的 KMS 密钥。要启用此功能，请在您的 Helm Chart 中设置以下值：

config:
  blobStorage:
    kmsEncryptionEnabled: true
    kmsKeyArn: <your_kms_key_arn>

Google Cloud Storage

要向 Google Cloud Storage 进行认证，您需要创建一个具有访问您的桶所需权限的 service account。您的服务账户需要 Storage Admin 角色或具有等效权限的自定义角色。这可以限定在 LangSmith 将使用的桶上。一旦您配置好了服务账户，您需要为该服务账户生成一个 HMAC key。此密钥和秘密将用于向 Google Cloud Storage 认证。

从 Helm Chart 版本 0.13.29 开始，您可以直接将 Blob 存储引擎设置为 "GCS"。这支持两种认证方法：

GCP Workload Identity（推荐）：将 accessKey 和 accessKeySecret 留空。LangSmith 将使用应用程序默认凭据。您需要将工作负载身份注释添加到 backend、platform-backend、queue 和 ingest-queue 服务账户。
HMAC 密钥：将 accessKey 和 accessKeySecret 设置为您的 GCS HMAC 凭据。

对于这两种方法，将 apiURL 设置为 https://storage.googleapis.com，将 bucketName 设置为您的 GCS 桶名称。对于 0.13.29 之前的 Helm Chart 版本，GCS 通过 S3 兼容的 API 支持，需设置 engine: "S3" 并使用 HMAC 凭据。

Azure Blob Storage

要向 Azure Blob Storage 进行认证，您需要使用以下方法之一授予 LangSmith 工作负载访问您的容器的权限（按优先级顺序列出）：

存储账户和访问密钥
连接字符串
工作负载身份（推荐）、托管标识或 DefaultAzureCredential 支持的环境变量。当以上任一选项的配置不存在时，这是默认的认证方法。
1. 要使用工作负载身份，请在 queue、backend、platform-backend 和 ingest-queue 部署中添加标签 azure.workload.identity/use: true。此外，在相应的服务账户上添加 azure.workload.identity/client-id 注释，该注释应为现有 Azure AD 应用程序的客户端 ID 或用户分配的托管标识的客户端 ID。有关更多详细信息，请参阅 Azure 的文档。

某些部署可能需要进一步自定义连接配置，使用服务 URL 覆盖而不是默认的服务 URL（https://<storage_account_name>.blob.core.windows.net/）。例如，要使用不同的 Blob 存储域（例如政府或中国区域），此覆盖是必需的。

CH 搜索

默认情况下，LangSmith 仍将用于搜索的 token 存储在 ClickHouse 中。如果您使用的是 LangSmith 托管 ClickHouse，您可能希望禁用此功能，以避免将潜在敏感信息发送到 ClickHouse。您可以在 Blob 存储配置中执行此操作。

配置

创建桶并获取必要的凭证后，您可以配置 LangSmith 以使用您的 Blob 存储系统。

Helm

config:
  blobStorage:
    enabled: true
    engine: "S3" # 或 "GCS" 或 "Azure"。这是大小写敏感的。
    chSearchEnabled: true # 如果您想禁用 CH 搜索，请设置为 false（推荐用于 LangSmith 托管 Clickhouse）
    bucketName: "your-bucket-name"
    apiURL: "Your connection url"
    accessKey: "Your access key" # 可选。仅在使用 S3 访问密钥和秘密密钥时必需
    accessKeySecret: "Your access key secret" # 可选。仅在使用访问密钥和秘密密钥时必需
    # 以下 Blob 存储配置值适用于 Azure，需要 blobStorage.engine = "Azure"。否则请忽略。
    azureStorageAccountName: "Your storage account name" # 可选。仅在使用存储账户和访问密钥时必需。
    azureStorageAccountKey: "Your storage account access key" # 可选。仅在使用存储账户和访问密钥时必需。
    azureStorageContainerName: "your-container-name" # 必需
    azureStorageConnectionString: "" # 可选。
    azureStorageServiceUrlOverride: "" # 可选
  backend: # 可选，仅在 AWS 上使用服务账户的 IAM 角色、GKE 上的工作负载身份或 AKS 上的工作负载身份时必需
    deployment: # 仅限 Azure
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # 仅限 Azure
        eks.amazonaws.com/role-arn: "<role_arn>" # 仅限 AWS
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # 仅限 GCP
  platformBackend: # 可选，仅在 AWS 上使用服务账户的 IAM 角色、GKE 上的工作负载身份或 AKS 上的工作负载身份时必需
    deployment: # 仅限 Azure
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # 仅限 Azure
        eks.amazonaws.com/role-arn: "<role_arn>" # 仅限 AWS
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # 仅限 GCP
  queue: # 可选，仅在 AWS 上使用服务账户的 IAM 角色、GKE 上的工作负载身份或 AKS 上的工作负载身份时必需
    deployment: # 仅限 Azure
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # 仅限 Azure
        eks.amazonaws.com/role-arn: "<role_arn>" # 仅限 AWS
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # 仅限 GCP
  ingestQueue: # 可选，仅在 AWS 上使用服务账户的 IAM 角色、GKE 上的工作负载身份或 AKS 上的工作负载身份时必需
    deployment: # 仅限 Azure
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # 仅限 Azure
        eks.amazonaws.com/role-arn: "<role_arn>" # 仅限 AWS
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # 仅限 GCP

如果使用访问密钥和秘密，您也可以提供一个包含认证信息的现有 Kubernetes 密钥。建议这样做，而不是在配置中直接提供访问密钥和秘密密钥。有关预期的密钥名称，请参阅生成的密钥模板。

TTL 配置

如果将 TTL 功能与 LangSmith 一起使用，您还需要为您的 Blob 存储配置 TTL 规则。存储在 Blob 存储上的追踪信息存储在特定的前缀路径下，该路径决定了数据的 TTL。当一个追踪的保留期被延长时，其相应的 Blob 存储路径会改变，以确保它与新的延长保留期匹配。使用以下 TTL 前缀：

ttl_s/：短期（基础）TTL，配置为 14 天。
ttl_l/：长期（扩展）TTL，默认配置为 400 天。

自定义工作区级别保留前缀

如果您使用工作区级别扩展保留，LangSmith 会将 Blob 数据写入格式为 ttl_XXd/ 的前缀，其中 XX 是为该工作区配置的天数。例如，如果一个工作区配置了 90 天的扩展保留，则该工作区的 Blob 数据将写入 ttl_90d/ 前缀。您必须为跨工作区配置的每个自定义保留期限创建一个生命周期规则。常见示例：

ttl_90d/ — 90 天保留
ttl_180d/ — 180 天保留
ttl_365d/ — 365 天保留

如果缺少某个已配置保留期限的生命周期规则，则该前缀下的 Blob 数据将永远不会被自动删除。每当您配置新的工作区保留期限时，请确保添加匹配的生命周期规则。

例如，如果您配置了 90 天和 180 天扩展保留的工作区，则需要在默认的 ttl_s 和 ttl_l 规则之外添加以下生命周期规则：

AWS
GCP
Azure

rule {
  id      = "ttl-90d"
  prefix  = "ttl_90d/"
  enabled = true
  expiration {
    days = 90
  }
}
rule {
  id      = "ttl-180d"
  prefix  = "ttl_180d/"
  enabled = true
  expiration {
    days = 180
  }
}

lifecycle_rule {
  condition {
    age            = 90
    matches_prefix = ["ttl_90d"]
  }
  action {
    type = "Delete"
  }
}
lifecycle_rule {
  condition {
    age            = 180
    matches_prefix = ["ttl_180d"]
  }
  action {
    type = "Delete"
  }
}

rule {
  name    = "ttl-90d"
  enabled = true
  type    = "Lifecycle"
  filters {
    prefix_match = ["my-container/ttl_90d"]
    blob_types   = ["blockBlob"]
  }
  actions {
    base_blob {
      delete_after_days_since_creation_greater_than = 90
    }
    snapshot {
      delete_after_days_since_creation_greater_than = 90
    }
    version {
      delete_after_days_since_creation_greater_than = 90
    }
  }
}
rule {
  name    = "ttl-180d"
  enabled = true
  type    = "Lifecycle"
  filters {
    prefix_match = ["my-container/ttl_180d"]
    blob_types   = ["blockBlob"]
  }
  actions {
    base_blob {
      delete_after_days_since_creation_greater_than = 180
    }
    snapshot {
      delete_after_days_since_creation_greater_than = 180
    }
    version {
      delete_after_days_since_creation_greater_than = 180
    }
  }
}

如果您已在 LangSmith 配置中自定义了 TTL，则需要调整 Blob 存储配置中的 TTL 以匹配。

AWS
GCP
Azure

Amazon S3 生命周期规则

如果使用 S3 作为您的 Blob 存储，您需要设置一个匹配上述前缀的过滤器生命周期配置。您可以在亚马逊文档中找到相关信息。例如，如果您使用 Terraform 来管理您的 S3 桶，您需要这样设置：

rule {
  id      = "short-term-ttl"
  prefix  = "ttl_s/"
  enabled = true
  expiration {
    days = 14
  }
}
rule {
  id      = "long-term-ttl"
  prefix  = "ttl_l/"
  enabled = true
  expiration {
    days = 400
  }
}

Google Cloud Storage 生命周期规则

您需要为您正在使用的 GCS 桶设置生命周期条件。您可以在谷歌文档中找到相关信息，特别是使用 matchesPrefix。例如，如果您使用 Terraform 来管理您的 GCS 桶，您需要这样设置：

lifecycle_rule {
  condition {
    age            = 14
    matches_prefix = ["ttl_s"]
  }
  action {
    type = "Delete"
  }
}
lifecycle_rule {
  condition {
    age            = 400
    matches_prefix = ["ttl_l"]
  }
  action {
    type = "Delete"
  }
}

Azure Blob 存储生命周期管理

您需要在容器上配置生命周期管理策略以使匹配上述前缀的对象过期。例如，如果您使用 Terraform 来管理您的 Blob 存储容器，您需要这样设置：

resource "azurerm_storage_management_policy" "example" {
  storage_account_id = "my-storage-account-id"
  rule {
    name = "base"
    enabled = true
    type = "Lifecycle"
    filters {
      prefix_match = ["my-container/ttl_s"]
      blob_types = ["blockBlob"]
    }
    actions {
      base_blob {
        delete_after_days_since_creation_greater_than = 14
      }
      snapshot {
        delete_after_days_since_creation_greater_than = 14
      }
      version {
        delete_after_days_since_creation_greater_than = 14
      }
    }
  }
  rule {
    name = "extended"
    enabled = true
    type = "Lifecycle"
    filters {
      prefix_match = ["my-container/ttl_l"]
      blob_types = ["blockBlob"]
    }
    actions {
      base_blob {
        delete_after_days_since_creation_greater_than = 400
      }
      snapshot {
        delete_after_days_since_creation_greater_than = 400
      }
      version {
        delete_after_days_since_creation_greater_than = 400
      }
    }
  }
}

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started by cloud provider

Deploy with Terraform

Setup guides

Configuration

Connect external services

Platform auth & access control

Self-hosted observability

Hybrid

Scripts

Reference

要求

认证

Amazon S3

KMS 加密头支持

Google Cloud Storage

Azure Blob Storage

CH 搜索

配置

TTL 配置

自定义工作区级别保留前缀

Amazon S3 生命周期规则

Google Cloud Storage 生命周期规则

Azure Blob 存储生命周期管理

​要求

​认证

​Amazon S3

​KMS 加密头支持

​Google Cloud Storage

​Azure Blob Storage

​CH 搜索

​配置

​TTL 配置

​自定义工作区级别保留前缀

​Amazon S3 生命周期规则

​Google Cloud Storage 生命周期规则

​Azure Blob 存储生命周期管理

要求

认证

Amazon S3

KMS 加密头支持

Google Cloud Storage

Azure Blob Storage

CH 搜索

配置

TTL 配置

自定义工作区级别保留前缀

Amazon S3 生命周期规则

Google Cloud Storage 生命周期规则

Azure Blob 存储生命周期管理