管理批量导出目标 - 以编程方式使用文档

目标是一个命名配置，用于告诉 LangSmith 将导出的跟踪数据写入何处。您创建一个目标一次，然后在创建导出作业时通过 ID 引用它。LangSmith 当前支持 S3 和任何 S3 兼容的存储桶（如 GCS 或 MinIO）作为目标。导出数据以 Parquet 列式格式编写，包含与运行数据格式.

等效的字段。本页涵盖：

- 配置字段设置目标所需的信息。
- 必需的存储桶权限用于 AWS S3 和 GCS。
- 如何创建目标通过 API 创建目标，包括特定提供商的示例和凭证选项。
- 如何轮换目标凭证无需重新创建目标。
- 如何调试目标错误.

配置字段

配置目标需要以下信息：

存储桶名称：要将数据导出到的 S3 存储桶的名称。
前缀：存储桶内导出数据所在的根前缀。
S3 区域：存储桶的区域——AWS S3 存储桶必需。
端点 URL：S3 存储桶的端点 URL——S3 API 兼容存储桶必需。
访问密钥：S3 存储桶的访问密钥。
密钥：S3 存储桶的密钥。
在前缀中包含存储桶 （可选）：是否将存储桶名称包含在路径前缀中。默认为 true。设置为 false 当使用虚拟托管样式端点时（存储桶名称已包含在端点 URL 中）。
S3 配置选项 (config_kwargs_s3，可选）：传递给 botocore 的高级 S3 寻址样式和请求设置。最常见的用途是设置 addressing_style 用于需要虚拟托管或路径样式请求的 S3 兼容服务：
- "virtual"：存储桶名称是主机名的一部分（例如 bucket.endpoint/key某些S3兼容服务（如火山引擎TOS）需要此配置。
- "path"：存储桶名称是URL路径的一部分（例如： endpoint/bucket/key).
- "auto" （默认）：boto3根据端点决定。

我们支持任何S3兼容的存储桶。对于非AWS存储桶（如GCS或MinIO），您需要提供端点URL。

所需权限

和 backend 服务都需要对目标存储桶具有写权限： queue 这两个

- 服务会在创建导出目标时尝试向目标存储桶写入测试文件。如果有删除权限，它会删除测试文件（删除权限为可选项）。 backend 服务负责批量导出的执行以及将文件上传到存储桶。
- 服务负责批量导出的执行以及将文件上传到存储桶。 queue 服务负责批量导出的执行以及将文件上传到存储桶。

AWS S3 权限

最小 AWS S3 权限策略依赖以下权限：

- s3:PutObject （必需）：允许向存储桶写入 Parquet 文件。
- s3:DeleteObject （可选）：在目标创建期间清理测试文件。如果不存在此权限，文件会保留在 /tmp 目录下，目标创建后不会被删除。
- s3:GetObject （可选但建议）：在写入后验证文件大小。
- s3:AbortMultipartUpload （可选但建议）：避免未完成的多部分上传。

最小 IAM 策略示例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

包含额外权限的建议 IAM 策略示例：

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

Google Cloud Storage (GCS) 权限

使用 GCS 配合 S3 兼容的 XML API 时，需要以下 IAM 权限：

- storage.objects.create （必需）：允许向存储桶写入文件。
- storage.objects.delete （可选）：在创建目标期间清理测试文件。如果未授予此权限，文件将保留在 /tmp 目录中。
- storage.objects.get （可选但建议）：在写入后验证文件大小。

可通过 "Storage Object Admin" 预定义角色或自定义角色授予这些权限。

创建目标

以下示例演示如何使用 cURL 创建目标。请将占位符值替换为您的实际配置详情。请注意，凭证将以加密形式安全地存储在我们的系统中。

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My S3 Destination",
    "config": {
      "bucket_name": "your-s3-bucket-name",
      "prefix": "root_folder_prefix",
      "region": "your aws s3 region",
      "endpoint_url": "your endpoint url for s3 compatible buckets",
      "include_bucket_in_prefix": true // defaults to true, can be omitted
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

使用返回的 id 在后续的批量导出操作中引用此目标。

**如果在创建目标时收到错误，请参阅目标错误调试了解如何调试此问题。**

凭证配置

除静态 access_key_id 和 secret_access_key:

- 外，我们还支持以下额外的凭证格式临时凭证要使用包含 AWS 会话令牌的还需额外提供 credentials.session_token 创建批量导出目标时的密钥。 - （仅限自托管）：要使用基于环境的凭证，例如配合 AWS IAM 服务账户角色（IRSA），请省略 credentials 创建批量导出目标时，请从请求中省略该密钥。在这种情况下，将按标准 Boto3 凭证位置的顺序进行检查。

AWS S3 存储桶

对于 AWS S3，您可以省略 endpoint_url 并提供与存储桶所在区域匹配的区域。

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My AWS S3 Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "region": "us-east-1"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

Google GCS XML S3 兼容存储桶

使用 Google GCS 存储桶时，您需要使用 XML S3 兼容 API，并提供 endpoint_url 通常是 https://storage.googleapis.com. 以下是使用与 S3 兼容的 GCS XML API 时的 API 请求示例：

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My GCS Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://storage.googleapis.com"
      "include_bucket_in_prefix": true // defaults to true, can be omitted
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

请参阅 Google 文档了解更多

采用虚拟托管样式寻址的 S3 兼容存储桶

某些 S3 兼容服务（如火山引擎 TOS）要求使用虚拟托管样式寻址，即存储桶名称作为主机名的一部分而非 URL 路径的一部分。使用 config_kwargs_s3 配合 addressing_style: "virtual" 启用此功能：

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My Volcengine TOS Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://tos-s3-cn-beijing.volces.com",
      "config_kwargs_s3": {
        "addressing_style": "virtual"
      }
    },
    "credentials": {
      "access_key_id": "YOUR_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_SECRET_ACCESS_KEY"
    }
  }'

采用虚拟托管样式端点的 S3 兼容存储桶

如果您的端点 URL 已包含存储桶名称（虚拟托管样式），请设置 include_bucket_in_prefix to false 以避免在路径中重复添加存储桶名称：

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My Virtual-Hosted Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://my_bucket.s3.us-east-1.amazonaws.com",
      "include_bucket_in_prefix": false
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

轮换目标凭证

使用 PATCH /api/v1/bulk-exports/destinations/{destination_id} 更新现有目标上的凭证。这允许您在不重新创建目标或其关联的批量导出的情况下轮换或替换凭证。目标配置（存储桶、前缀、区域、端点等）保持不变——仅替换凭证。

凭证轮换行为

切换并非即时完成：

新的批量导出运行 在 PATCH 完成后会立即使用更新后的凭证。
正在运行的批量导出运行 将继续使用之前的凭证直到完成。
两套凭证在过渡期间同时生效 。此窗口期最长可达单个批量导出运行的最大运行时间。

请相应地规划您的轮换：旧凭证必须保持有效直到所有进行中的运行完成。

请求

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations/{destination_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "credentials": {
      "access_key_id": "YOUR_NEW_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_NEW_SECRET_ACCESS_KEY"
    }
  }'

字段是可选的，您可以将其包含在 session_token 临时凭证的场景中。.

**所需权限**: bulk-exports:manage (or workspaces:manage，该权限历史上授予了此访问权限）。

在存储新凭证之前，LangSmith 会使用现有目标配置对存储桶执行测试写入来验证凭证。请求失败并返回 400 如果凭证没有足够的写权限。如果请求失败，请参阅调试目标错误.

响应

返回更新后的目标对象。凭证值永远不会返回——响应中仅包含凭证字段名称 credentials_keys.

{
  "id": "destination-uuid",
  "tenant_id": "tenant-uuid",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-06-01T00:00:00Z",
  "credentials_keys": ["access_key_id", "secret_access_key"]
}

轮换清单

在您的云提供商中配置具有目标存储桶和前缀写权限的新凭证。
使用新凭证调用 PATCH 端点。LangSmith 在保存前会验证它们。
保持旧凭证有效，直到所有进行中的批量导出运行完成（最长到最大运行时间).
一旦没有运行使用旧凭证，请立即撤销。

调试目标错误

目标 API 端点将验证目标和凭证是否有效，以及是否存在写权限存储桶是否存在写权限。

如果您收到错误并想调试此错误，可以使用 AWS CLI 测试与存储桶的连接。您应该能够使用 CLI 使用相同的数据写入文件，就像您提供给上面的目标 API 的一样。

AWS S3：

aws configure

# set the same access key credentials and region as you used for the destination
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# List buckets
aws s3 ls /

# test write permissions
touch ./test.txt
aws s3 cp ./test.txt s3://<bucket-name>/tmp/test.txt

GCS 兼容存储桶：

您需要提供端点_url 配合 --endpoint-url option. 对于 GCS， endpoint_url 通常是 https://storage.googleapis.com:

aws configure

# set the same access key credentials and region as you used for the destination
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# List buckets
aws s3 --endpoint-url=<endpoint_url> ls /

# test write permissions
touch ./test.txt
aws s3 --endpoint-url=<endpoint_url> cp ./test.txt s3://<bucket-name>/tmp/test.txt

常见错误

以下是一些常见错误：

错误	描述
访问被拒绝	blob 存储凭证或存储桶无效。当提供的访问密钥和秘密密钥组合没有必要的权限访问指定存储桶或执行所需操作时，会出现此错误。
存储桶无效	指定的 blob 存储桶无效。当存储桶不存在或没有足够的权限在存储桶上执行写操作时，会抛出此错误。
您提供的密钥 ID 不存在	提供的 blob 存储凭证无效。当用于身份验证的访问密钥 ID 不是有效密钥时，会出现此错误。
无效的端点	端点_url 无效。当指定的端点是无效端点时会引发此错误。仅支持 S3 兼容端点，例如 `https://storage.googleapis.com` 对于 GCS， `https://play.min.io` 对于 minio 等。如果使用 AWS，应省略端点_url。
InvalidBucketName	S3 兼容服务因寻址方式不匹配而拒绝请求。某些服务需要虚拟托管方式寻址。请在目标配置中设置 `config_kwargs_s3: {"addressing_style": "virtual"}` 来解决此问题。