批量导出追踪数据

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

INFO

套餐限制适用

对于在 2026 年 8 月 3 日之后注册的客户，批量导出仅在 LangSmith Enterprise 套餐上可用。在 2026 年 8 月 3 日或之前注册的客户，可以在 Plus 或 Enterprise 套餐上使用批量导出，截止到 2027 年 2 月 1 日。

LangSmith 的批量数据导出让你能够把某个特定项目和日期范围的追踪数据，以 Parquet 格式导出到一个 S3 兼容的存储桶，字段与运行数据格式相匹配。这对在 BigQuery、Snowflake、Redshift 或 Jupyter Notebook 等工具中做离线分析很有用。

本页介绍如何：

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

开始之前： 取决于数据量，导出可能需要一些时间，且 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）或 "all_experiments": true——从Tracing Projects 列表中单个项目的视图复制项目 ID。
• 一个 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 字段会导出所有运行。

NOTE

LangSmith Cloud 限制：每工作区每小时 250 次批量导出创建

在 LangSmith cloud 上，每个工作区每小时最多可创建 250 次批量导出。这一配额包含一次性导出以及由计划批量导出派生的导出，因此有许多活动计划的工作区会自动消耗掉部分每小时配额。

如果你的工作区达到该限制，新的创建请求会被拒绝并返回 429，直到早先的创建超出滚动的 60 分钟窗口。要提高该限制，请通过 support.langchain.com 联系支持。

自托管 LangSmith 默认不强制此限制。

导出所有实验

NOTE

自托管：目前仅在 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。

NOTE

Cloud 限制：每次导出 250 个实验

在 LangSmith cloud 上，每次 all_experiments 导出最多包含 250 个实验。要导出更多：

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

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

计划周期性导出

NOTE

需要 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 属性。如有需要，它们必须被单独取消——取消源导出不会取消已派生的导出。
• 要停止一个计划导出，取消它。

NOTE

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

限制导出的字段

NOTE

需要 LangSmith Helm 版本 0.12.11 或更高（应用版本 0.12.42 或更高）。在一次性和计划导出中都受支持。

你可以通过使用 export_fields 参数限制包含哪些字段来提升导出速度并缩小文件大小。如果你省略 export_fields，除 feedbacks 外的所有字段都会被包含。

反馈评论是选择加入的。要包含它们，请显式地把 feedbacks 连同其他相关字段一起添加到 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"
  }'

TIP

排除 inputs 和 outputs 能显著提升导出性能并缩小文件大小，对大型运行尤其如此。只有当你的分析确实需要这些字段时才包含它们。

压缩

设置 compression 字段以控制导出的 Parquet 文件如何被压缩。省略时，LangSmith 使用 zstandard。

允许的值：zstandard、gzip、snappy、none。加载到 BigQuery 时使用 snappy，参阅导出追踪数据到 BigQuery。

NOTE

从 LangSmith 0.16.0 起，当省略 compression 时，自托管 LangSmith 也默认为 zstandard。这与之前默认为 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）。有关聚合限制，参阅下面的说明。
feedbacks	反馈评论和键（JSON）

NOTE

feedback_stats 聚合限制

feedback_stats 字段只为字符串类型的反馈包含值细分。具有非字符串值（数值、布尔、复杂类型）的反馈会被排除在这些细分之外。要分析非字符串反馈值，请单独导出原始反馈数据。

Token 用量与成本：

字段	描述
total_tokens	总 token 数
prompt_tokens	提示 token 数
completion_tokens	补全 token 数
total_cost	总成本
prompt_cost	提示成本
completion_cost	补全成本
first_token_time	首 token 时间

分区方案

数据使用以下 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 文件即可在你的存储桶中使用。

参阅监控并排查批量导出以了解如何列出运行、停止导出并诊断失败。

---