启用 Blob 存储 - 以编程方式使用文档

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

在高跟踪量环境中，输入、输出、错误、清单、额外数据和事件可能会使数据库的大小急剧增加。
如果您使用 LangSmith 托管的 ClickHouse，您可能希望将敏感信息存储在您环境中的 Blob 存储中。为此，LangSmith 支持将运行输入、输出、错误、清单、额外数据、事件和附件存储在外部 Blob 存储系统中。

要求

* 访问有效的 Blob 存储服务
* Amazon S3
* Google Cloud Storage (GCS)
* Azure Blob Storage
* A bucket/directory in your blob storage to store the data. We highly recommend creating a separate bucket/directory for LangSmith data.
* **如果您使用 TTL**，则需要设置生命周期策略来删除旧数据。如需了解更多信息，请参阅配置 TTL。这些策略应与您在 LangSmith 配置中设置的 TTL 保持一致，否则可能会导致数据丢失。请参阅 Blob 存储的 TTL 配置以了解如何设置生命周期规则。
* Credentials to permit LangSmith Services to access the bucket/directory
* You will need to provide your LangSmith instance with the necessary credentials to access the bucket/directory. Read the authentication 章节了解更多。
* 如果使用 S3 或 GCS，则需要为 Blob 存储服务提供 API URL
* 这是 LangSmith 用于访问 Blob 存储系统的 URL
* 对于 Amazon S3，这将是 S3 端点的 URL。示例： https://s3.amazonaws.com or https://s3.us-west-1.amazonaws.com 如果使用区域端点。
* 对于 Google Cloud Storage，这将是 GCS 端点的 URL。示例： https://storage.googleapis.com

身份验证

AWS

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 进行身份验证：

1. 服务账号的 IAM 角色 (IRSA) （推荐）：您可以为 LangSmith 实例创建一个 IAM 角色，并将策略附加到该角色。这是生产环境中与 Amazon S3 进行身份验证的推荐方式。 1. 您需要创建一个附加了策略的 IAM 角色。 1. 您需要允许 LangSmith 服务账户承担该角色。 langsmith-queue, langsmith-backend, langsmith-platform-backend和 langsmith-ingest-queue 服务账户将需要能够承担该角色。 <aside class="callout"><strong>警告</strong>

如果您使用自定义发布名称，服务账户名称将会有所不同。您可以通过运行 kubectl get serviceaccounts 在您的集群中找到服务账户名称。 </aside>

您需要向 LangSmith 提供角色 ARN。您可以通过将 eks.amazonaws.com/role-arn: "<role_arn>" 注解添加到 queue, backend, platform-backend和 ingest-queue 服务来完成此操作。

访问密钥和秘密密钥：您可以为 LangSmith 提供访问密钥和秘密密钥。这是与 Amazon S3 进行身份验证的最简单方式。但是，由于安全性较低，不建议用于生产环境。
您需要创建一个附加了策略的用户。然后您可以为该用户生成访问密钥和秘密密钥。

VPC 端点访问：您可以通过 VPC 端点启用对 S3 存储桶的访问，这允许流量从您的 VPC 安全地流向 S3 存储桶。
您需要配置一个 VPC 端点并将其设置为允许访问您的 S3 存储桶。
您可以参考我们的公共 Terraform 模块获取指导以及配置此功能的示例。

KMS 加密标头支持

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

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

GCP

Google Cloud Storage

要通过 Google Cloud Storage进行身份验证，您需要创建一个 service account 并授予其访问存储桶的必要权限。

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

配置服务账户后，您需要为该服务账户生成一个 HMAC key 。此密钥和密钥将用于向 Google Cloud Storage 进行身份验证。

Azure

Azure Blob 存储

要通过以下方式向以下对象进行身份验证 Azure Blob 存储，您需要使用以下方法之一来授予 LangSmith 工作负载访问您的以下对象的权限容器（按优先级顺序列出）：

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

CH 搜索

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

配置

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

config:
  blobStorage:
    enabled: true
    engine: "S3" # Or "GCS" or "Azure". This is case-sensitive.
    chSearchEnabled: true # Set to false if you want to disable CH search (Recommended for LangSmith Managed Clickhouse)
    bucketName: "your-bucket-name"
    apiURL: "Your connection url"
    accessKey: "Your access key" # Optional. Only required if using S3 access key and secret key
    accessKeySecret: "Your access key secret" # Optional. Only required if using access key and secret key
    # The following blob storage configuration values are for Azure and require blobStorage.engine = "Azure". Omit otherwise.
    azureStorageAccountName: "Your storage account name" # Optional. Only required if using storage account and access key.
    azureStorageAccountKey: "Your storage account access key" # Optional. Only required if using storage account and access key.
    azureStorageContainerName: "your-container-name" # Required
    azureStorageConnectionString: "" # Optional.
    azureStorageServiceUrlOverride: "" # Optional
  backend: # Optional, only required if using IAM role for service account on AWS, workload identity on GKE, or workload identity on AKS
    deployment: # Azure only
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # Azure only
        eks.amazonaws.com/role-arn: "<role_arn>" # AWS only
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # GCP only
  platformBackend: # Optional, only required if using IAM role for service account on AWS, workload identity on GKE, or workload identity on AKS
    deployment: # Azure only
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # Azure only
        eks.amazonaws.com/role-arn: "<role_arn>" # AWS only
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # GCP only
  queue: # Optional, only required if using IAM role for service account on AWS, workload identity on GKE, or workload identity on AKS
    deployment: # Azure only
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # Azure only
        eks.amazonaws.com/role-arn: "<role_arn>" # AWS only
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # GCP only
  ingestQueue: # Optional, only required if using IAM role for service account on AWS, workload identity on GKE, or workload identity on AKS
    deployment: # Azure only
      labels:
        azure.workload.identity/use: true
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>" # Azure only
        eks.amazonaws.com/role-arn: "<role_arn>" # AWS only
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com" # GCP only

# In your .env file
FF_BLOB_STORAGE_ENABLED=false # Set to true if you want to enable blob storage
BLOB_STORAGE_ENGINE=S3 # Or GCS or Azure
BLOB_STORAGE_BUCKET_NAME=langsmith-blob-storage # Required for using S3. Change to your desired blob storage bucket name
BLOB_STORAGE_API_URL=https://s3.us-west-2.amazonaws.com # Change to your desired blob storage API URL
BLOB_STORAGE_ACCESS_KEY=your-access-key # Change to your desired blob storage access key
BLOB_STORAGE_ACCESS_KEY_SECRET=your-access-key-secret # Change to your desired blob storage access key secret
AZURE_STORAGE_ACCOUNT_NAME=your-storage-account-name # Optional. Only required if using storage account and access key.
AZURE_STORAGE_ACCOUNT_KEY=your-storage-account-key # Optional. Only required if using storage account and access key.
AZURE_STORAGE_CONTAINER_NAME=your-container-name # Required for using Azure blob storage. Change to your desired container name
AZURE_STORAGE_CONNECTION_STRING=BlobEndpoint=https://storagesample.blob.core.windows.net;SharedAccessSignature=signature; # Optional.
AZURE_STORAGE_SERVICE_URL_OVERRIDE=https://your.override.domain.net # Optional

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/ prefix.

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

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

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

AWS

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

GCP

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

Azure

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

Amazon S3 生命周期规则

如果使用 S3 作为 blob 存储，则需要设置与上述前缀匹配的筛选器生命周期配置。您可以在以下位置找到相关信息 Amazon 文档中.

例如，如果您使用 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
  }
}

GCP

Google Cloud Storage 生命周期规则

您需要为您使用的 GCS 存储桶设置生命周期条件。您可以在以下位置找到相关信息 Google 文档中，具体使用 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

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