LangSmith 的批量数据导出功能可让您将特定项目和日期范围内的追踪数据导出到 S3 兼容的存储桶中，格式为 Parquet 格式，与 运行数据格式中的字段匹配。这对于在 BigQuery、Snowflake、Redshift 或 Jupyter Notebooks 等工具中进行离线分析非常有用。

本页面涵盖以下内容：

• - 创建导出目标
• - 创建和配置导出作业，包括计划导出和字段过滤
• - 监控导出进度

开始之前： 根据数据量，导出可能需要一些时间，且 LangSmith 限制了可同时运行的导出数量。批量导出的运行时超时为 72 小时——请参阅 自动重试行为 了解更多详情。启动后，LangSmith 负责编排和 导出流程的弹性 automatically.

1. 创建目标

目标用于指定 LangSmith 写入导出数据的位置。在发出此请求之前，您需要准备：

• - 您的 LangSmith API 密钥 和 工作区 ID.
• - 一个 S3 或 S3 兼容的存储桶，且 **写入权限** 已授予 LangSmith（请参阅 所需权限).
• - 存储桶名称、前缀，以及 AWS 区域（用于 AWS S3）或端点 URL（用于 GCS、MinIO 或其他 S3 兼容提供商）。
• - 存储桶的访问密钥和密钥。

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"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

凭据以加密形式安全存储。在保存之前，API 会验证目标位置和凭据的有效性。如果请求失败，请参阅 调试目标错误.

保存 id 从响应中获取；在创建导出作业时需要用到。

请参阅 管理批量导出目标 了解权限设置、提供商特定配置（AWS S3、GCS、MinIO）以及凭据选项。

2. 创建导出作业

导出作业针对特定项目（或工作区中的所有实验）和日期范围。您需要：

• - 目标 id 来自 上一步.
• - 项目 ID（session_id) or "all_experiments": true——从 **追踪项目** 列表中复制项目 ID.
• - A start_time 和 end_time 采用 UTC ISO 8601 格式。

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": "project_uuid",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-03T00:00:00Z",
    "format_version": "v2_beta"
  }'

该 start_time 是包含性的且 end_time 是排除性的。导出将包含所有满足以下条件的运行 run.start_time >= start_time 和 run.start_time < end_time.

保存响应中的 id 以监控导出的进度。

您可以选择添加一个 filter 表达式来缩小导出的运行集合。请参阅我们的 过滤查询语言 和 示例 了解语法。如果不设置 filter 字段，将导出所有运行。

导出所有实验

要导出工作区中的所有实验而不是针对单个项目 session_id，请设置 all_experiments: true。LangSmith 会在您针对数据集运行评估时创建实验，任何具有 reference_dataset_id 设置的跟踪项目都符合条件。

all_experiments 和 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",
    "all_experiments": true,
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-02-01T00:00:00Z",
    "format_version": "v2_beta"
  }'

LangSmith 在运行时解析实验会话集，因此导出会在您提交任务后、编排器开始处理前获取您创建的任何实验。

相同的 all_experiments 标志适用于 计划导出——包含 interval_hours 和排除 end_time 而不是提供 end_time.

计划定期导出

计划导出定期收集运行并导出到配置的目的地。要创建计划导出，请包含 interval_hours 并省略 end_time:

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": "project_uuid",
    "start_time": "2024-01-01T00:00:00Z",
    "interval_hours": 1,
    "format_version": "v2_beta"
  }'

• - interval_hours 必须介于 1 到 168（一周）之间（含）。
• - end_time 计划导出必须省略此字段；一次性导出仍需要此字段。
• - 每个生成的导出覆盖 start_time to start_time + interval_hours，然后前进 interval_hours 用于每个后续运行。因为 end_time 是排他的，连续的导出不会重叠。
• - 生成的导出运行于 end_time + 10 minutes 以考虑最近提交的运行 end_time 。
• - 生成的导出具有 source_bulk_export_id 属性填充。如果需要，必须单独取消——取消源导出 **不会** 取消已生成的导出。
• - 要停止计划导出， 取消它.

示例

如果使用以下内容创建计划批量导出 start_time=2025-07-16T00:00:00Z 和 interval_hours=6:

限制导出字段

您可以使用以下方式限制包含的字段来提高导出速度并减小文件大小 export_fields 参数。省略时，包含所有字段。

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": "project_uuid",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-03T00:00:00Z",
    "export_fields": ["id", "name", "run_type", "start_time", "end_time", "status", "total_tokens", "total_cost"],
    "format_version": "v2_beta"
  }'

可导出字段

默认情况下，批量导出包含以下每个运行的字段：

标识符和层级：

基本元数据：

运行数据：

标签和反馈：

令牌使用量和成本：

分区方案

数据使用以下 Hive 分区结构导出到您的存储桶：

<bucket>/<prefix>/export_id=<export_id>/tenant_id=<tenant_id>/session_id=<session_id>/runs/year=<year>/month=<month>/day=<day>

3. 监控您的导出

使用 id 从 上一步:

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

轮询导出状态 status 响应中的字段将是以下之一 CREATED, RUNNING, COMPLETED, FAILED, CANCELLED, or TIMEDOUT。根据数据量，导出可能需要一些时间。一旦状态为 COMPLETED，Parquet 文件将在您的存储桶中可用。

请参阅 监控和排查批量导出 关于如何列出运行、停止导出和诊断失败。