批量导出追踪数据

计划限制适用请注意，数据导出功能仅适用于 LangSmith Plus 或企业版。

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

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

开始前须知： 导出时间可能因数据量而异，并且 LangSmith 限制了可以并发运行的导出数量。批量导出有 72 小时的运行超时限制——详情请参阅自动重试行为。一旦启动，LangSmith 会自动处理导出流程的编排和弹性。

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)——从 追踪项目 列表中的单个项目视图中复制。
UTC ISO 8601 格式的 start_time 和 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",
    "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 字段将导出所有运行。

计划定期导出

需要 LangSmith Helm 版本 >= 0.10.42（应用版本 >= 0.10.109）

计划导出会定期收集运行并导出到配置的目标。要创建计划导出，请包含 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（1 周）之间（含）。
对于计划导出，必须省略 end_time；对于一次性导出，它仍然是必需的。
每个派生的导出覆盖 start_time 到 start_time + interval_hours，然后为每个后续运行前进 interval_hours。由于 end_time 是排除的，连续的导出不会重叠。
派生的导出在 end_time + 10 分钟 运行，以考虑在最近过去提交的带有 end_time 的运行。
派生的导出具有填充的 source_bulk_export_id 属性。如果需要，必须单独取消它们——取消源导出不会取消已派生的导出。
要停止计划导出，请取消它。

示例如果创建了一个计划批量导出，其 start_time=2025-07-16T00:00:00Z 且 interval_hours=6：

导出	开始时间	结束时间	运行时间
1	2025-07-16T00:00:00Z	2025-07-16T06:00:00Z	2025-07-16T06:10:00Z
2	2025-07-16T06:00:00Z	2025-07-16T12:00:00Z	2025-07-16T12:10:00Z
3	2025-07-16T12:00:00Z	2025-07-16T18:00:00Z	2025-07-16T18:10:00Z

限制导出字段

需要 LangSmith Helm 版本 >= 0.12.11（应用版本 >= 0.12.42）。在一次性导出和计划导出中均受支持。

您可以通过使用 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"
  }'

排除 inputs 和 outputs 可以显著提高导出性能并减小文件大小，特别是对于大型运行。仅在分析需要时才包含这些字段。

可导出的字段

默认情况下，批量导出为每个运行包含以下字段： 标识符与层次结构：

字段	描述
`id`	运行 ID
`tenant_id`	工作区/租户 ID
`session_id`	项目/会话 ID
`trace_id`	追踪 ID
`parent_run_id`	父运行 ID
`parent_run_ids`	所有父运行 ID 的列表
`reference_example_id`	如果属于数据集，则引用示例

基本元数据：

字段	描述
`name`	运行名称
`run_type`	运行类型（例如，“chain”、“llm”、“tool”）
`start_time`	开始时间戳（UTC）
`end_time`	结束时间戳（UTC）
`status`	运行状态（例如，“success”、“error”）
`is_root`	是否为根级运行
`dotted_order`	层次排序字符串
`trace_tier`	追踪层级/保留级别

运行数据：

字段	描述
`inputs`	运行输入（JSON）
`outputs`	运行输出（JSON）
`error`	如果失败，错误消息
`extra`	额外元数据（JSON）
`events`	运行事件（JSON）

标签与反馈：

字段	描述
`tags`	标签列表
`feedback_stats`	反馈统计（JSON）

令牌使用与成本：

字段	描述
`total_tokens`	总令牌数
`prompt_tokens`	提示令牌数
`completion_tokens`	完成令牌数
`total_cost`	总成本
`prompt_cost`	提示成本
`completion_cost`	完成成本
`first_token_time`	首次令牌时间

分区方案

数据使用以下 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 或 TIMEDOUT。导出时间可能因数据量而异。一旦状态变为 COMPLETED，Parquet 文件即可在您的存储桶中使用。有关如何列出运行、停止导出和诊断故障，请参阅监控和故障排除批量导出。

Edit this page on GitHub or file an issue.

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

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

1. 创建目标

2. 创建导出作业

计划定期导出

限制导出字段

可导出的字段

分区方案

3. 监控您的导出

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

​1. 创建目标

​2. 创建导出作业

​计划定期导出

​限制导出字段

​可导出的字段

​分区方案

​3. 监控您的导出

1. 创建目标

2. 创建导出作业

计划定期导出

限制导出字段

可导出的字段

分区方案

3. 监控您的导出