批量导出追踪数据

将 LangSmith 追踪数据以 Parquet 格式导出到 S3 兼容的存储桶。

计划限制适用

请注意，数据导出功能仅适用于 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.