批量导出追踪数据

适用套餐限制请注意，数据导出功能仅支持 LangSmith Plus 或 Enterprise 套餐。

LangSmith 的批量数据导出功能可以将特定项目和日期范围内的追踪数据，以 Parquet 格式导出到兼容 S3 的存储桶，字段与运行数据格式一致。这对于使用 BigQuery、Snowflake、Redshift 或 Jupyter Notebooks 等工具进行离线分析非常有用。本页面介绍如何：

创建导出目标
创建和配置导出任务，包括计划导出和字段筛选
监控导出进度

开始前须知： 导出可能需要一些时间，具体取决于数据量；LangSmith 还会限制可并发运行的导出数量。批量导出的运行超时时间为 72 小时——详情请参阅自动重试行为。导出启动后，LangSmith 会自动负责编排以及导出流程的弹性处理。

1. 创建目标

目标用于告知 LangSmith 将导出的数据写入何处。在发起此请求前，您需要准备：

您的 LangSmith API 密钥和工作区 ID。
一个已向 LangSmith 授予写入权限的 S3 或兼容 S3 的存储桶（请参阅所需权限）。
存储桶名称、前缀，以及 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）或 "all_experiments": true 二者之一——您可以从 Tracing Projects 列表中的项目详情视图复制项目 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 Cloud 限制：每个工作区每小时最多创建 250 个批量导出在 LangSmith Cloud 上，每个工作区每小时最多可以创建 250 个批量导出。此配额包括一次性导出和由计划批量导出创建的导出，因此，拥有多个活动计划的工作区会自动消耗部分每小时配额。如果工作区达到此限制，新的创建请求将被拒绝并返回 429，直到较早创建的请求超出滚动 60 分钟时间窗口。如需提高限制，请通过 support.langchain.com 联系支持团队。自托管 LangSmith 默认不强制执行此限制。

导出所有实验

自托管：目前仅在 v0.16.1rc1 预览版本中可用。在生产环境运行前，请等待 v0.16.1 稳定版本发布。

要导出工作区中的每个实验，而不是通过 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。

Cloud 限制：每个导出最多包含 250 个实验在 LangSmith Cloud 上，每个 all_experiments 导出最多包含 250 个实验。如需导出更多实验：

查询已完成的 all_experiments 导出，查看其中包含了哪些追踪项目，然后为剩余实验使用 session_id 创建标准批量导出。
或通过 support.langchain.com 联系支持团队，为您的工作区申请更高的限制。

自托管 LangSmith 没有单次导出限制。

计划定期导出

需要 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 minutes 时运行，以涵盖那些在最近过去的 end_time 提交的运行。
生成的导出会填充 source_bulk_export_id 属性。如需取消，必须单独取消这些导出——取消源导出不会取消已经生成的导出。
如需停止计划导出，请取消它。

LangSmith Cloud 限制：每个工作区最多有 200 个计划批量导出在 LangSmith Cloud 上，每个工作区同时最多可以有 200 个活动的计划（定期）批量导出，即配置了 interval_hours 值的导出。该限制限制的是计划数量，而不是计划运行的次数：一个已经产生数千次历史导出运行的计划，仍然只计为一个计划。一次性（非定期）批量导出不受此限制影响。如果工作区达到此限制，新的计划导出请求将被拒绝并返回 429，直到您取消现有计划。如需提高限制，请通过 support.langchain.com 联系支持团队。自托管 LangSmith 默认不强制执行此限制。

示例如果创建计划批量导出时设置 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 可以显著提高导出性能并减小文件大小，尤其是对于大型运行。只有在分析中需要这些字段时才应包含它们。

压缩

设置 compression 字段可以控制导出 Parquet 文件的压缩方式。如果省略，LangSmith 将使用 zstandard。允许的值：zstandard、gzip、snappy、none。将数据加载到 BigQuery 时，请使用 snappy，参见将追踪数据导出到 BigQuery。

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

可导出的字段

默认情况下，批量导出会为每个运行包含以下字段： 标识符和层级关系：

字段	描述
`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）。有关聚合限制，请参阅以下说明。

feedback_stats 聚合限制feedback_stats 字段仅包含字符串类型反馈的值细分。具有非字符串值（数字、布尔值、复杂类型）的反馈不会计入这些细分。要分析非字符串反馈值，请单独导出原始反馈数据。

令牌使用量和成本：

字段	描述
`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 文件即可在您的存储桶中使用。有关如何列出运行、停止导出和诊断故障，请参阅监控和排查批量导出问题。

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. 创建目标

2. 创建导出任务

导出所有实验

计划定期导出

限制导出字段

压缩

可导出的字段

分区方案

3. 监控导出

​1. 创建目标

​2. 创建导出任务

​导出所有实验

​计划定期导出

​限制导出字段

​压缩

​可导出的字段

​分区方案

​3. 监控导出

1. 创建目标

2. 创建导出任务

导出所有实验

计划定期导出

限制导出字段

压缩

可导出的字段

分区方案

3. 监控导出