LangSmith 可以将追踪数据导出到 Google Cloud Storage (GCS) 存储桶，格式为 Parquet。从那里，您可以将其加载到 BigQuery 作为外部表（在 GCS 中原地查询）或本机表（复制到 BigQuery 存储中）。

本指南涵盖：

• - 为 LangSmith 设置 GCS 存储桶和 HMAC 凭据。
• - 创建批量导出目标位置和导出作业。
• - 将导出的数据加载到 BigQuery。

有关批量导出配置选项的完整详细信息，请参阅 批量导出追踪数据 和 管理批量导出目标位置.

前提条件

• - 您的 LangSmith 中的数据 追踪项目.
• - gcloud 已安装 CLI。（您也可以使用 Google Cloud 控制台进行设置。）

1. 创建 GCS 存储桶

为 LangSmith 导出创建一个专用 GCS 存储桶。使用专用存储桶可以更轻松地授予有限范围的权限，而不会影响其他数据：

gcloud storage buckets create gs://YOUR_BUCKET_NAME \
  --location=US \
  --uniform-bucket-level-access

选择靠近 BigQuery 数据集的区域，以最大程度地减少延迟并避免跨区域出口费用。

2. 创建服务账号并授予访问权限

创建一个 LangSmith 将用于向 GCS 写入数据的 GCP 服务账号：

gcloud iam service-accounts create langsmith-bulk-export \
  --display-name="LangSmith Bulk Export"

授予服务账号对您的存储桶的写入访问权限。所需的最小权限是 storage.objects.create。授予 storage.objects.delete 是可选的，但推荐使用。LangSmith 使用它来清理目标位置验证期间创建的临时测试文件。如果此权限缺失， tmp/ 文件夹可能会留在您的存储桶中。

“存储对象管理员”预定义角色包含所有必需和推荐的权限：

gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET_NAME \
  --member="serviceAccount:langsmith-bulk-export@YOUR_PROJECT.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

要使用最小自定义角色，请仅授予：

• - storage.objects.create （必需）
• - storage.objects.delete （可选，用于测试文件清理）
• - storage.objects.get （可选但推荐，用于文件大小验证）
• - storage.multipartUploads.create （可选但推荐，用于大文件上传）

3. 生成 HMAC 密钥

LangSmith 使用 S3 兼容的 XML API 连接到 GCS，这需要 HMAC 密钥而不是服务账号 JSON 密钥。

为您的服务账号生成 HMAC 密钥：

gcloud storage hmac create \
  langsmith-bulk-export@YOUR_PROJECT.iam.gserviceaccount.com

保存输出中的 accessId 和 secret 。您也可以在 GCP 控制台中的 **Cloud Storage → 设置 → 互操作性 → 为服务账号创建密钥**.

4. 创建批量导出目标位置

在 LangSmith 中创建一个指向您的 GCS 存储桶的目标位置。设置 endpoint_url to https://storage.googleapis.com 以使用 GCS S3 兼容 API。

您将需要您的 LangSmith API 密钥 和 工作区 ID.

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": "GCS for BigQuery",
    "config": {
      "bucket_name": "YOUR_BUCKET_NAME",
      "prefix": "YOUR_PREFIX",
      "endpoint_url": "https://storage.googleapis.com"
    },
    "credentials": {
      "access_key_id": "YOUR_HMAC_ACCESS_ID",
      "secret_access_key": "YOUR_HMAC_SECRET"
    }
  }'

prefix 是存储桶内 LangSmith 将写入导出文件的路径。例如， langsmith-exports or data/traces。选择任何适合您存储桶布局的值。

LangSmith 通过执行测试写入来验证凭据，然后再保存目标。如果请求返回 400 错误，请参阅 调试目标错误.

保存 id 从响应中；您将在下一步需要它。

临时验证文件

在目标创建期间（和 凭据轮换）期间，LangSmith 会写入一个临时 .txt 文件到 YOUR_PREFIX/tmp/ 来验证写访问权限，然后尝试删除它。删除是尽力而为的：如果服务账号缺少 storage.objects.delete，则不会删除该文件，并且 tmp/ 文件夹将保留在您的存储桶中。

tmp/ 文件夹不会影响导出，但它将包含在广泛的 GCS URI 通配符中（例如， gs://YOUR_BUCKET_NAME/YOUR_PREFIX/*).

5. 创建批量导出任务

创建一个针对特定项目的导出。使用 format_version: v2_beta 以实现 BigQuery 兼容性——它生成 UTC 时区感知的时间戳，BigQuery 可以正确处理。

您将需要项目 ID（session_id），您可以从 **追踪项目** 列表中复制.

一次性导出：

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "bulk_export_destination_id": "YOUR_DESTINATION_ID",
    "session_id": "YOUR_PROJECT_ID",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-02-01T00:00:00Z",
    "format_version": "v2_beta",
    "compression": "snappy"
  }'

计划（重复）导出：

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "bulk_export_destination_id": "YOUR_DESTINATION_ID",
    "session_id": "YOUR_PROJECT_ID",
    "start_time": "2024-01-01T00:00:00Z",
    "interval_hours": 24,
    "format_version": "v2_beta",
    "compression": "snappy"
  }'

Snappy 压缩快速且被 BigQuery 广泛支持。有关所有可用选项，请参阅 批量导出追踪数据，包括字段过滤和过滤表达式。

输出文件结构

导出的文件使用 Hive 分区路径结构放入 GCS：

gs://YOUR_BUCKET_NAME/YOUR_PREFIX/export_id=<uuid>/tenant_id=<uuid>/session_id=<uuid>/resource=runs/year=<year>/month=<month>/day=<day>/<filename>.parquet

路径中的分区列（export_id, tenant_id, session_id, resource, year, month, day）在启用 Hive 分区检测时可用作 BigQuery 中的可查询列。

6. 将数据加载到 BigQuery

BigQuery 提供两种访问导出数据的方式。两种方式都需要先授予 BigQuery 服务账号对您 GCS 存储桶的读取权限。请根据您的需求选择：

• 外部表： 数据保留在 GCS 中，BigQuery 直接在原位置查询。BigQuery 中没有存储费用，但查询性能比原生存储慢。请参阅 所需角色.
• 原生表： 数据被复制到 BigQuery 存储中。查询速度更快，完全支持 BigQuery 功能，但会产生 BigQuery 存储费用。请参阅 所需权限.

创建表

凭证轮换

如需轮换 HMAC 密钥而不中断活动中的导出：

1. **在 GCP 中为同一服务账号生成新的 HMAC 密钥** 。
2. **调用 PATCH 端点** 并提供新凭证：

   curl --request PATCH \
     --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations/YOUR_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": "NEW_HMAC_ACCESS_ID",
         "secret_access_key": "NEW_HMAC_SECRET"
       }
     }'
   

LangSmith 会使用测试写入来验证新凭证，然后再保存。在验证期间，您的工作桶中可能会出现一个新的 tmp/ 文件（请参阅 临时验证文件).

1. **保持旧的 HMAC 密钥处于活动状态** 直到所有正在进行的导出运行完成。在过渡期间，两组凭证可以同时有效。
2. **删除旧的 HMAC 密钥** ，在 GCP 中确认没有正在进行的运行使用它们后。

有关完整详情，请参阅 轮换目标凭证.

故障排除

有关其他错误代码和导出状态详细信息，请参阅 监控和排查批量导出.