将跟踪数据导出到 BigQuery

套餐限制适用批量导出功能仅适用于 LangSmith Plus 或 Enterprise 套餐。

LangSmith 可以将跟踪数据以 Parquet 格式导出到 Google Cloud Storage (GCS) 存储桶。之后，您可以将数据作为外部表（从 GCS 中直接查询）或原生表（复制到 BigQuery 存储空间）加载到 BigQuery 中。本指南涵盖以下内容：

设置 GCS 存储桶和供 LangSmith 使用的 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. 创建服务账号并授予访问权限

创建一个 GCP 服务账号，LangSmith 将使用该账号向 GCS 写入数据：

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

授予该服务账号对存储桶的写入权限。所需的最小权限是 storage.objects.create。授予 storage.objects.delete 是可选的，但建议授予。LangSmith 会使用此权限清理由目标验证期间创建的临时测试文件。如果没有此权限，您的存储桶中可能会保留 tmp/ 文件夹。预定义的 “Storage Object Admin” 角色包含所有必需和建议的权限：

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，该 API 要求使用 HMAC 密钥，而不是服务账号 JSON 密钥。为您的服务账号生成 HMAC 密钥：

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

从输出中保存 accessId 和 secret。您也可以在 GCP 控制台中，通过 Cloud Storage → Settings → Interoperability → Create a key for a service account 生成 HMAC 密钥。

4. 创建批量导出目标

在 LangSmith 中创建一个指向 GCS 存储桶的目标。将 endpoint_url 设置为 https://storage.googleapis.com，以使用兼容 S3 的 GCS 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 或 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），可以从跟踪项目列表中的项目视图复制该 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"
  }'

批量导出默认使用 zstandard 压缩。此示例设置为 snappy，因为 Snappy 速度快，并且受到 BigQuery 的广泛支持。有关所有可用选项，请参阅批量导出跟踪数据，其中包括字段筛选和筛选表达式。

在自托管 LangSmith中，默认值为 gzip。设置 FF_BULK_EXPORT_DEFAULT_COMPRESSION 环境变量可以更改默认值。

输出文件结构

导出的文件会按照 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

启用 Hive 分区检测后，路径中的分区列（export_id、tenant_id、session_id、resource、year、month、day）可作为 BigQuery 中可查询的列使用。

6. 将数据加载到 BigQuery

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

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

创建表

External table
Native table

外部表直接从 GCS 查询数据，而不会将数据复制到 BigQuery 中。

在 BigQuery 控制台中，在 Explorer 窗格中展开您的项目和数据集。
点击数据集的 Actions 菜单（三个点），然后选择 Create table。
在 Source 下：
- 将 Create table from 设置为 Google Cloud Storage。
- 将文件路径设置为 gs://YOUR_BUCKET_NAME/YOUR_PREFIX/export_id=*。使用 export_id=* 可将 BigQuery 的范围限定为 Hive 分区导出目录，并排除 LangSmith 在目标验证期间写入的 tmp/ 文件夹（请参阅临时验证文件）。
- 将 File format 设置为 Parquet。
勾选 Source data partitioning，然后：
- 将 Source URI prefix 设置为 gs://YOUR_BUCKET_NAME/YOUR_PREFIX。
- 将 Partition inference mode 设置为 Automatically infer types。
在 Destination 下：
- 选择您的项目和数据集。
- 输入表名称，例如 langsmith_runs。
- 将 Table type 设置为 External table。
在 Schema 下，启用 Auto-detect。
点击 Create table。

分区路径列（export_id、tenant_id、session_id、resource、year、month、day）可作为可查询列使用。在查询中按 year、month 或 day 进行筛选，以启用分区裁剪。

原生表会将 Parquet 数据传输到 BigQuery 存储空间中，以获得完整的查询性能。

前往 Google Cloud 控制台中的数据传输页面，然后选择 + Create transfer。
对于 Source type，选择 Google Cloud Storage。
输入 Transfer name。如有需要，之后可以编辑该传输任务。
选择 Schedule option。如果不希望重复导出，可以选择 On demand，然后手动触发导出任务。
在 BigQuery 控制台中，在 Explorer 窗格中展开您的项目和数据集。
点击数据集的 Actions 菜单（三个点），然后选择 Create table。
在 Source 下：
- 将 Create table from 设置为 Google Cloud Storage。
- 将文件路径设置为 gs://YOUR_BUCKET_NAME/YOUR_PREFIX/export_id=*。使用 export_id=* 可排除 LangSmith 在目标验证期间写入的 tmp/ 文件夹（请参阅临时验证文件）。
- 将 File format 设置为 Parquet。
勾选 Source data partitioning，然后：
- 将 Source URI prefix 设置为 gs://YOUR_BUCKET_NAME/YOUR_PREFIX。
- 将 Partition inference mode 设置为 Automatically infer types。
在 Destination 下：
- 选择您的项目和数据集。
- 输入表名称，例如 langsmith_runs。
- 将 Table type 设置为 Native table。
在 Advanced options 下，对于新表，将 Write preference 设置为 Write if empty。
点击 Create table。

BigQuery 会运行加载任务来复制数据。Hive 分区列会作为表中的普通列出现。有关可用数据列的完整列表，请参阅可导出字段。

凭据轮换

要在不中断活动导出的情况下轮换 HMAC 密钥，请执行以下操作：

在 GCP 中为同一个服务账号生成新的 HMAC 密钥。

使用新凭据调用 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/ 文件（请参阅临时验证文件）。

在所有正在执行的导出任务完成之前，保持旧 HMAC 密钥处于活动状态。在过渡期间，两组凭据可以同时有效。
确认没有正在执行的任务使用旧 HMAC 密钥后，在 GCP 中删除旧 HMAC 密钥。

有关完整详情，请参阅轮换目标凭据。

故障排除

现象	可能原因	解决方法
创建目标时出现 `400 Access denied`	HMAC 凭据缺少写入权限	确认服务账号对存储桶拥有 `storage.objects.create` 权限
出现 `400 Key ID you provided does not exist`	HMAC 访问 ID 无效	在 GCP 中重新生成 HMAC 密钥
出现 `400 Invalid endpoint`	端点 URL 格式错误	使用准确的 `https://storage.googleapis.com`
BigQuery 表没有行	导出尚未完成	使用 `GET /api/v1/bulk-exports/{export_id}` 检查导出状态
BigQuery 分区裁剪未生效	源 URI 前缀不正确	确保源 URI 前缀在第一个分区键之前结束，例如 `gs://BUCKET/PREFIX`
BigQuery 读取了 `tmp/` 文件	文件路径通配模式过于宽泛	在文件路径中使用 `export_id=`，而不是 ``

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

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Viewing & managing traces

Bulk export trace data

Messages view

Data type reference

前提条件

1. 创建 GCS 存储桶

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

3. 生成 HMAC 密钥

4. 创建批量导出目标

临时验证文件

5. 创建批量导出任务

输出文件结构

6. 将数据加载到 BigQuery

创建表

凭据轮换

故障排除

​前提条件

​1. 创建 GCS 存储桶

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

​3. 生成 HMAC 密钥

​4. 创建批量导出目标

​临时验证文件

​5. 创建批量导出任务

​输出文件结构

​6. 将数据加载到 BigQuery

​创建表

​凭据轮换

​故障排除

前提条件

1. 创建 GCS 存储桶

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

3. 生成 HMAC 密钥

4. 创建批量导出目标

临时验证文件

5. 创建批量导出任务

输出文件结构

6. 将数据加载到 BigQuery

创建表

凭据轮换

故障排除