> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 启用 Blob 存储

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

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

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

  * [Amazon S3 (AWS)](#amazon-s3)
  * [Google Cloud Storage (GCP)](#google-cloud-storage)
  * [Azure Blob Storage](#azure-blob-storage)

  有关完整的特定云平台设置和架构指南，请参阅 [AWS](/langsmith/aws-self-hosted)、[GCP](/langsmith/gcp-self-hosted) 或 [Azure](/langsmith/azure-self-hosted)。
</Tip>

## 要求

<Note>
  Azure Blob 存储从 Helm chart 版本 0.8.9 开始可用。[删除跟踪项目](/langsmith/observability-concepts#deleting-traces-from-langsmith) 功能在 Azure 中从 Helm chart 版本 0.10.43 开始支持。

  原生 GCS Blob 存储引擎支持（使用 `engine: "GCS"`）从 Helm chart 版本 0.13.29 开始可用。对于更早的版本，GCS 通过 S3 兼容 API 支持，通过设置 `engine: "S3"` 并使用 HMAC 凭证。
</Note>

* 访问有效的 Blob 存储服务

  * [Amazon S3](https://aws.amazon.com/s3/)
    * [Google Cloud Storage (GCS)](https://cloud.google.com/storage?hl=en)
  * [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs)

* 在您的 Blob 存储中有一个用于存储数据的桶/目录。我们强烈建议为 LangSmith 数据创建一个单独的桶/目录。
  * **如果您使用 TTL**，您需要设置一个生命周期策略来删除旧数据。更多信息，请参阅[配置 TTL](/langsmith/self-host-ttl)。这些策略应与您在 LangSmith 配置中设置的 TTL 保持一致，否则可能会遇到数据丢失。有关如何设置生命周期规则，请参阅 [Blob 存储的 TTL 配置](#ttl-configuration)。

* 允许 LangSmith 服务访问桶/目录的凭证
  * 您需要为您的 LangSmith 实例提供访问桶/目录所需的凭证。请阅读下面的[身份验证](#authentication)部分了解更多信息。

* 如果使用 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`

## 身份验证

<Tabs>
  <Tab title="AWS">
    ### Amazon S3

    要验证到 [Amazon S3](https://aws.amazon.com/s3/)，您需要创建一个 IAM 策略，授予对您的桶的以下权限。

    ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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 进行身份验证：

    1. [服务账户的 IAM 角色 (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)（推荐）：您可以为您的 LangSmith 实例创建一个 IAM 角色，并将策略附加到该角色。这是在生产环境中与 Amazon S3 进行身份验证的推荐方式。
       1. 您需要创建一个附加了策略的 IAM 角色。
       2. 您需要允许 LangSmith 服务账户担任该角色。`langsmith-queue`、`langsmith-backend`、`langsmith-platform-backend` 和 `langsmith-ingest-queue` 服务账户需要能够担任该角色。
              <Warning>
                如果您使用自定义的发布名称，服务账户名称将会不同。您可以通过在集群中运行 `kubectl get serviceaccounts` 来查找服务账户名称。
              </Warning>
       3. 您需要向 LangSmith 提供角色 ARN。您可以通过在 Helm Chart 安装中的 `queue`、`backend`、`platform-backend` 和 `ingest-queue` 服务上添加 `eks.amazonaws.com/role-arn: "<role_arn>"` 注解来实现。

    2. [访问密钥和秘密密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)：您可以为 LangSmith 提供访问密钥和秘密密钥。这是与 Amazon S3 进行身份验证的最简单方式。但是，不建议在生产环境中使用，因为它安全性较低。
       1. 您需要创建一个附加了策略的用户。然后您可以为该用户配置访问密钥和秘密密钥。

    3. [VPC 端点访问](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html)：您可以通过 VPC 端点启用对 S3 桶的访问，这允许流量从您的 VPC 安全地流向您的 S3 桶。
       1. 您需要配置一个 VPC 端点，并将其配置为允许访问您的 S3 桶。
       2. 您可以参考我们的[公共 Terraform 模块](https://github.com/langchain-ai/terraform/blob/main/modules/aws/s3/main.tf#L12)来获取指导和配置示例。

    ### KMS 加密头支持

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

    ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    config:
      blobStorage:
        kmsEncryptionEnabled: true
        kmsKeyArn: <your_kms_key_arn>
    ```
  </Tab>

  <Tab title="GCP">
    ### Google Cloud Storage

    要与 [Google Cloud Storage](https://cloud.google.com/storage?hl=en) 进行身份验证，您需要创建一个具有访问您的桶所需权限的[`服务账户`](https://cloud.google.com/iam/docs/service-account-overview)。

    您的服务账户需要 `Storage Admin` 角色或具有等效权限的自定义角色。这可以限定在 LangSmith 将使用的桶上。

    一旦您配置了服务账户，您需要为该服务账户生成一个 [`HMAC 密钥`](https://cloud.google.com/storage/docs/authentication/hmackeys)。该密钥和秘密将用于与 Google Cloud Storage 进行身份验证。

    <Note>
      从 Helm chart 版本 **0.13.29** 开始，您可以直接将 Blob 存储引擎设置为 `"GCS"`。这支持两种身份验证方法：

      1. **GCP 工作负载身份（推荐）**：将 `accessKey` 和 `accessKeySecret` 留空。LangSmith 将使用[应用程序默认凭证](https://cloud.google.com/docs/authentication/application-default-credentials)。您需要将工作负载身份注解添加到 `backend`、`platform-backend`、`queue` 和 `ingest-queue` 服务账户。
      2. **HMAC 密钥**：将 `accessKey` 和 `accessKeySecret` 设置为您的 GCS [HMAC 凭证](https://cloud.google.com/storage/docs/authentication/hmackeys)。

      对于这两种方法，将 `apiURL` 设置为 `https://storage.googleapis.com`，将 `bucketName` 设置为您的 GCS 桶名称。

      对于 Helm chart 版本 0.13.29 之前的版本，GCS 通过 S3 兼容 API 支持，通过设置 `engine: "S3"` 并使用 HMAC 凭证。
    </Note>
  </Tab>

  <Tab title="Azure">
    ### Azure Blob Storage

    要与 [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs) 进行身份验证，您需要使用以下方法之一来授予 LangSmith 工作负载访问您的[容器](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction#containers)的权限（按优先级顺序列出）：

    1. [存储账户和访问密钥](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
    2. [连接字符串](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string)
    3. [工作负载身份](https://azure.github.io/azure-workload-identity/docs/introduction.html)（推荐）、托管身份或由 [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication?tabs=bash#2-authenticate-with-azure) 支持的环境变量。当上述任一选项的配置不存在时，这是默认的身份验证方法。
       1. 要使用工作负载身份，请将标签 `azure.workload.identity/use: true` 添加到 `queue`、`backend`、`platform-backend` 和 `ingest-queue` 部署。此外，将 `azure.workload.identity/client-id` 注解添加到相应的服务账户，这应该是一个现有的 Azure AD 应用程序的客户端 ID 或用户分配的托管身份的客户端 ID。有关更多详细信息，请参阅 [Azure 的文档](https://azure.github.io/azure-workload-identity/docs/topics/service-account-labels-and-annotations.html)。

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

## CH 搜索

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

## 配置

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

<CodeGroup>
  ```yaml Helm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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
  ```

  ```bash Docker theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 在您的 .env 文件中
  FF_BLOB_STORAGE_ENABLED=false # 如果要启用 Blob 存储，请设置为 true
  BLOB_STORAGE_ENGINE=S3 # 或 GCS 或 Azure
  BLOB_STORAGE_BUCKET_NAME=langsmith-blob-storage # 使用 S3 时必需。更改为您所需的 Blob 存储桶名称
  BLOB_STORAGE_API_URL=https://s3.us-west-2.amazonaws.com # 更改为您所需的 Blob 存储 API URL
  BLOB_STORAGE_ACCESS_KEY=your-access-key # 更改为您所需的 Blob 存储访问密钥
  BLOB_STORAGE_ACCESS_KEY_SECRET=your-access-key-secret # 更改为您所需的 Blob 存储访问密钥秘密
  AZURE_STORAGE_ACCOUNT_NAME=your-storage-account-name # 可选。仅在使用存储账户和访问密钥时需要。
  AZURE_STORAGE_ACCOUNT_KEY=your-storage-account-key # 可选。仅在使用存储账户和访问密钥时需要。
  AZURE_STORAGE_CONTAINER_NAME=your-container-name # 使用 Azure Blob 存储时必需。更改为您所需的容器名称
  AZURE_STORAGE_CONNECTION_STRING=BlobEndpoint=https://storagesample.blob.core.windows.net;SharedAccessSignature=signature; # 可选。
  AZURE_STORAGE_SERVICE_URL_OVERRIDE=https://your.override.domain.net # 可选
  ```
</CodeGroup>

<Note>
  如果使用访问密钥和秘密，您也可以提供一个包含身份验证信息的现有 Kubernetes 密钥。这比直接在配置中提供访问密钥和秘密密钥更推荐。有关预期的密钥键，请参阅[生成的密钥模板](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/templates/secrets.yaml)。
</Note>

## TTL 配置

如果在 LangSmith 中使用 [TTL](/langsmith/self-host-ttl) 功能，您还需要为您的 Blob 存储配置 TTL 规则。存储在 Blob 存储上的跟踪信息存储在特定的前缀路径上，该路径决定了数据的 TTL。当跟踪的保留期被延长时，其对应的 Blob 存储路径会更改，以确保与新的延长保留期匹配。

使用以下 TTL 前缀：

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

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

如果您使用[工作区级别延长保留](/langsmith/data-purging-compliance#customize-extended-retention-policy)，LangSmith 会将 Blob 数据写入形式为 `ttl_XXd/` 的前缀，其中 `XX` 是为该工作区配置的天数。例如，如果一个工作区配置了 90 天的延长保留，则该工作区的 Blob 数据将写入 `ttl_90d/` 前缀。

您必须为**每个**在您的工作区中配置的自定义保留期创建一个生命周期规则。常见示例：

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

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

例如，如果您有配置了 90 天和 180 天延长保留的工作区，您将需要添加以下生命周期规则**以及**[默认的 `ttl_s` 和 `ttl_l` 规则](#ttl-configuration)：

<Tabs>
  <Tab title="AWS">
    ```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    rule {
      id      = "ttl-90d"
      prefix  = "ttl_90d/"
      enabled = true
      expiration {
        days = 90
      }
    }
    rule {
      id      = "ttl-180d"
      prefix  = "ttl_180d/"
      enabled = true
      expiration {
        days = 180
      }
    }
    ```
  </Tab>

  <Tab title="GCP">
    ```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    lifecycle_rule {
      condition {
        age            = 90
        matches_prefix = ["ttl_90d"]
      }
      action {
        type = "Delete"
      }
    }
    lifecycle_rule {
      condition {
        age            = 180
        matches_prefix = ["ttl_180d"]
      }
      action {
        type = "Delete"
      }
    }
    ```
  </Tab>

  <Tab title="Azure">
    ```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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
        }
      }
    }
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="AWS">
    ### Amazon S3 生命周期规则

    如果使用 S3 作为您的 Blob 存储，您需要设置一个与上述前缀匹配的筛选器生命周期配置。您可以在 [Amazon 文档](https://docs.aws.amazon.com/AmazonS3/latest/userguide/intro-lifecycle-rules.html#intro-lifecycle-rules-filter)中找到相关信息。

    例如，如果您使用 Terraform 管理您的 S3 桶，您将设置类似以下的内容：

    ```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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
      }
    }
    ```
  </Tab>

  <Tab title="GCP">
    ### Google Cloud Storage 生命周期规则

    您需要为您正在使用的 GCS 桶设置生命周期条件。您可以在 [Google 文档](https://cloud.google.com/storage/docs/lifecycle#conditions)中找到相关信息，特别是使用 matchesPrefix。

    例如，如果您使用 Terraform 管理您的 GCS 桶，您将设置类似以下的内容：

    ```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    lifecycle_rule {
      condition {
        age            = 14
        matches_prefix = ["ttl_s"]
      }
      action {
        type = "Delete"
      }
    }
    lifecycle_rule {
      condition {
        age            = 400
        matches_prefix = ["ttl_l"]
      }
      action {
        type = "Delete"
      }
    }
    ```
  </Tab>

  <Tab title="Azure">
    ### Azure Blob 存储生命周期管理

    您需要在容器上配置[生命周期管理策略](https://learn.microsoft.com/en-us/azure/storage/blobs/lifecycle-management-policy-configure)，以便使与上述前缀匹配的对象过期。

    例如，如果您[使用 Terraform 管理您的 Blob 存储容器](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_management_policy)，您将设置类似以下的内容：

    ```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\self-host-blob-storage.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>