启用 blob 存储

默认情况下，LangSmith 将运行输入、输出、错误、清单、附加项和事件存储在 ClickHouse 中。你可以选择改为将这些信息存储在 blob 存储中，后者有几个显著的好处。为了在生产部署中获得最佳效果，我们强烈推荐使用 blob 存储，它提供以下好处：

在高追踪环境中，输入、输出、错误、清单、附加项和事件可能会使你的数据库体积膨胀。
如果使用 LangSmith Managed ClickHouse，你可能希望将敏感信息存放在位于你环境中的 blob 存储里。为缓解这一点，LangSmith 支持将运行输入、输出、错误、清单、附加项、事件和附件存储在外部的 blob 存储系统中。

TIP

对于特定云的设置，选择你的平台：

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

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

要求

NOTE

Azure blob 存储可在 Helm chart 0.8.9 及更高版本中使用。Azure 中从 Helm chart 0.10.43 版开始支持删除追踪项目。

原生 GCS blob 存储引擎支持（使用 engine: "GCS"）可在 Helm chart 0.13.29 及更高版本中使用。对于更早的版本，GCS 通过以 engine: "S3" 配合 HMAC 凭据、使用 S3 兼容 API 来获得支持。

访问一个有效的 blob 存储服务
在你的 blob 存储中有一个用于存储数据的 bucket/目录。我们强烈建议为 LangSmith 数据创建一个单独的 bucket/目录。
- 如果你使用 TTL，你将需要设置一条生命周期策略来删除旧数据。更多信息参阅配置 TTL。这些策略应当与你在 LangSmith 配置中设置的 TTL 相匹配，否则你可能遭遇数据丢失。有关如何设置生命周期规则，参阅blob 存储的 TTL 配置。
允许 LangSmith 服务访问该 bucket/目录的凭据
- 你需要向 LangSmith 实例提供访问该 bucket/目录所必需的凭据。更多信息阅读下方的身份验证部分。
如果使用 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

身份认证

Amazon S3

要向 Amazon S3 进行身份验证，你需要创建一条 IAM 策略，在你的 bucket 上授予以下权限。

json

{
  "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 角色（IRSA）（推荐）：你可以为你的 LangSmith 实例创建一个 IAM 角色，并将策略附加到该角色。这是在生产环境中与 Amazon S3 进行身份验证的推荐方式。
1. 你需要创建一个附加了该策略的 IAM 角色。
2. 你需要允许 LangSmith 服务账户承担该角色。langsmith-queue、langsmith-backend、langsmith-platform-backend 和 langsmith-ingest-queue 服务账户将需要能够承担该角色。

WARNING

      如果你使用自定义的 release 名称，服务账户名称会有所不同。你可以通过在你的集群中运行 `kubectl get serviceaccounts` 来找到服务账户名称。

你需要向 LangSmith 提供角色 ARN。你可以通过在你的 Helm Chart 安装中向 queue、backend、platform-backend 和 ingest-queue 服务添加 eks.amazonaws.com/role-arn: "<role_arn>" 注解来实现这一点。
访问密钥和秘密密钥：你可以向 LangSmith 提供一个访问密钥和一个秘密密钥。这是与 Amazon S3 进行身份验证的最简单方式。但它不建议用于生产，因为它安全性较低。
1. 你需要创建一个附加了该策略的用户。然后你可以为该用户预配一个访问密钥和一个秘密密钥。
VPC 端点访问：你可以通过一个 VPC 端点启用对你 S3 bucket 的访问，这让流量安全地从你的 VPC 流向你的 S3 bucket。
1. 你需要预配一个 VPC 端点并配置它以允许访问你的 S3 bucket。
2. 你可以参考我们的公共 Terraform 模块以获得指导和配置示例。

KMS 加密标头支持

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

yaml

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

CH 搜索

默认情况下，LangSmith 仍会在 ClickHouse 中存储用于搜索的 token。如果你使用的是 LangSmith Managed Clickhouse，你可能希望禁用此功能以避免将潜在的敏感信息发送到 ClickHouse。你可以在你的 blob 存储配置中做到这一点。

配置

在创建你的 bucket 并获得必要凭据之后，你可以配置 LangSmith 使用你的 blob 存储系统。

yaml

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

NOTE

如果使用访问密钥和秘密，你还可以提供一个包含身份验证信息的现有 Kubernetes secret。这比直接在你的配置中提供访问密钥和秘密密钥更推荐。有关预期的 secret 键，参阅生成的 secret 模板。

TTL 配置

如果在 LangSmith 中使用 TTL 功能，你还将必须为你的 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 天保留

WARNING

如果某个已配置的保留期缺少一条生命周期规则，则该前缀下的 blob 数据将永不被自动删除。每当你配置一个新的工作区保留期时，请务必添加一条匹配的生命周期规则。

例如，如果你有配置为 90 天和 180 天延长保留的工作区，你会在默认的 ttl_s 和 ttl_l 规则之外添加以下生命周期规则：

hcl

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

如果你自定义了 LangSmith 配置中的 TTL，你将需要调整 blob 存储配置中的 TTL 以与之匹配。

Amazon S3 生命周期规则

如果你使用 S3 作为 blob 存储，你将需要设置一条匹配上述前缀的过滤器生命周期配置。你可以在 Amazon 文档中找到相关信息。

例如，如果你使用 Terraform 来管理你的 S3 bucket，你会做类似这样的设置：

hcl

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

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织