管理批量导出目标 - Docs by LangChain

适用于自托管、欧盟 (GCP) 和美国 (AWS) SaaS 版本对于自托管安装、欧盟 (GCP) (eu.api.smith.langchain.com) 或美国 (AWS) (aws.api.smith.langchain.com)，请更新以下请求中的 LangSmith URL。

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

设置目标所需的配置字段。
AWS S3 和 GCS 所需的存储桶权限。
如何通过 API 创建目标，包括特定于提供商的示例和凭据选项。
如何在不重新创建目标的情况下轮换目标凭据。
如何调试目标错误。

配置字段

配置目标需要以下信息：

存储桶名称：数据将导出到的 S3 存储桶的名称。
前缀：存储桶内数据将导出到的根前缀。
S3 区域：存储桶的区域——对于 AWS S3 存储桶是必需的。
端点 URL：S3 存储桶的端点 URL——对于 S3 API 兼容的存储桶是必需的。
访问密钥：S3 存储桶的访问密钥。
秘密密钥：S3 存储桶的秘密密钥。
在前缀中包含存储桶（可选）：是否将存储桶名称作为路径前缀的一部分。默认为 true。当使用虚拟托管样式端点（其中存储桶名称已在端点 URL 中）时，设置为 false。
S3 配置选项 (config_kwargs_s3，可选)：传递给 botocore 的高级 S3 寻址样式和请求设置。最常见的用途是为需要虚拟托管或路径样式请求的 S3 兼容服务设置 addressing_style：
- "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 在后续的批量导出操作中引用此目标。 如果在创建目标时收到错误，请参阅调试目标错误了解如何调试。

凭据配置

需要 LangSmith Helm 版本 >= 0.10.34（应用程序版本 >= 0.10.91）

除了静态的 access_key_id 和 secret_access_key，我们还支持以下附加凭据格式：

要使用包含 AWS 会话令牌的临时凭据，请在创建批量导出目标时额外提供 credentials.session_token 键。
（仅限自托管）：要使用基于环境的凭据，例如 AWS IAM Roles for Service Accounts (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 设置为 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 字段是可选的，您可以为临时凭据包含它。 所需权限：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 测试与存储桶的连接。您应该能够使用与上述提供给目标 API 相同的数据通过 CLI 写入文件。 AWS S3：

aws configure

# 设置与您用于目标相同的访问密钥凭据和区域
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# 列出存储桶
aws s3 ls /

# 测试写入权限
touch ./test.txt
aws s3 cp ./test.txt s3://<bucket-name>/tmp/test.txt

GCS 兼容存储桶： 您需要使用 --endpoint-url 选项提供 endpoint_url。对于 GCS，endpoint_url 通常是 https://storage.googleapis.com：

aws configure

# 设置与您用于目标相同的访问密钥凭据和区域
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# 列出存储桶
aws s3 --endpoint-url=<endpoint_url> ls /

# 测试写入权限
touch ./test.txt
aws s3 --endpoint-url=<endpoint_url> cp ./test.txt s3://<bucket-name>/tmp/test.txt

常见错误

以下是一些常见错误：

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

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​配置字段

​所需权限

​AWS S3 权限

​Google Cloud Storage (GCS) 权限

​创建目标

​凭据配置

​AWS S3 存储桶

​Google GCS XML S3 兼容存储桶

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

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

​轮换目标凭据

​凭据轮换行为

​请求

​响应

​轮换清单

​调试目标错误

​常见错误

配置字段

所需权限

AWS S3 权限

Google Cloud Storage (GCS) 权限

创建目标

凭据配置

AWS S3 存储桶

Google GCS XML S3 兼容存储桶

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

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

轮换目标凭据

凭据轮换行为

请求

响应

轮换清单

调试目标错误

常见错误