批量导出追踪数据 - Docs by LangChain

计划限制适用请注意，数据导出功能仅支持 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)——从 追踪项目 列表中的单个项目视图复制此 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)。有关聚合限制，请参阅以下注释。

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

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​1. 创建目标

​2. 创建导出任务

​计划定期导出

​限制导出字段

​可导出字段

​分区方案

​3. 监控您的导出

1. 创建目标

2. 创建导出任务

计划定期导出

限制导出字段

可导出字段

分区方案

3. 监控您的导出