BytesRouter

主题

LangSmith 文档版本 跟随上游 源快照 cfbe62e8 更新于 2026-10-18

将追踪数据导出到 BigQuery

使用批量导出到 GCS 将 LangSmith 追踪数据加载到 BigQuery。

INFO

套餐限制适用

对于在 2026 年 8 月 3 日之后注册的客户，批量导出仅在 LangSmith Enterprise 套餐上可用。在 2026 年 8 月 3 日或之前注册的客户，可以在 Plus 或 Enterprise 套餐上使用批量导出，截止到 2027 年 2 月 1 日。

LangSmith 可以将追踪数据以 Parquet 格式导出到 Google Cloud Storage (GCS) 存储桶。然后，你可以将其作为外部表（直接从 GCS 就地查询）或原生表（复制到 BigQuery 存储）加载到 BigQuery。

本指南涵盖：

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

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

前置条件

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

1. 创建 GCS 存储桶

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

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

选择靠近你的 BigQuery 数据集的区域，以最大限度减少延迟并避免跨区域外发流量费用。

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

创建一个 GCP 服务账户，供 LangSmith 用于将数据写入 GCS：

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

授予该服务账户对你存储桶的写入权限。最低要求的权限是 storage.objects.create。授予 storage.objects.delete 是可选的，但推荐这样做。LangSmith 使用它来清理在目标验证期间创建的临时测试文件。如果缺少此权限，你的存储桶中可能会残留一个 tmp/ 文件夹。

预定义角色 "Storage Object Admin" 涵盖了所有必需和推荐的权限：

bash
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 密钥：

bash
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 以使用 GCS 兼容 S3 的 API。

你将需要你的 LangSmith API key 和工作区 ID。

bash
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 会向 YOUR_PREFIX/tmp/ 写入一个临时 .txt 文件以验证写入权限，然后尝试删除它。删除是尽力而为的：如果服务账户缺少 storage.objects.delete，则该文件不会被删除，tmp/ 文件夹会保留在你的存储桶中。

tmp/ 文件夹不会影响导出，但它会被包含在宽泛的 GCS URI glob 中（例如 gs://YOUR_BUCKET_NAME/YOUR_PREFIX/*）。

5. 创建批量导出作业

创建一个针对特定项目的导出。使用 format_version: v2_beta 以获得 BigQuery 兼容性——它会生成 BigQuery 能够正确处理、带 UTC 时区信息的 timestamp。

你将需要项目 ID（session_id），你可以从 追踪项目列表中的项目视图复制它。

一次性导出：

bash
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"
  }'

计划（周期性）导出：

bash
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 广泛支持。有关所有可用选项，请参阅批量导出追踪数据，包括字段过滤和过滤表达式。

NOTE

在自托管 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 存储费用。请参阅所需权限。

创建表

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

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

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

凭据轮换

要在不中断进行中的导出的情况下轮换 HMAC 密钥：

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

  2. 使用新凭据调用 PATCH 端点：

    bash
    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/ 文件（请参阅临时验证文件）。

  3. 保持旧 HMAC 密钥处于活动状态，直到所有进行中的导出运行完成。在过渡窗口期间，两组凭据同时有效。

  4. 一旦确认没有进行中的运行在使用旧 HMAC 密钥，就在 GCP 中删除它们。

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

故障排查

症状可能原因修复
创建目标时出现 400 Access deniedHMAC 凭据缺少写入权限验证服务账户在存储桶上具有 storage.objects.create
400 Key ID you provided does not existHMAC access 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/ 文件文件路径 glob 过于宽泛在文件路径中使用 export_id=* 而非 *

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

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可