> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 批量导出追踪数据

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

<Info>
  **计划限制适用**

  请注意，数据导出功能仅适用于 [LangSmith Plus 或企业版](https://www.langchain.com/pricing-langsmith)。
</Info>

LangSmith 的批量数据导出功能允许您将特定项目和日期范围内的追踪数据导出到 S3 兼容的存储桶，格式为 [Parquet](https://parquet.apache.org/docs/overview/)，字段与 [运行数据格式](/langsmith/run-data-format) 相匹配。这对于在 BigQuery、Snowflake、Redshift 或 Jupyter Notebooks 等工具中进行离线分析非常有用。

本页涵盖以下内容：

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

**开始前须知：** 导出时间可能因数据量而异，并且 LangSmith 限制了可以并发运行的导出数量。批量导出有 72 小时的运行超时限制——详情请参阅 [自动重试行为](/langsmith/data-export-monitor#automatic-retry-behavior)。一旦启动，LangSmith 会自动处理导出流程的编排和 [弹性](/langsmith/data-export-monitor#failure-modes-and-retry-policy)。

## 1. 创建目标

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

* 您的 [LangSmith API 密钥](/langsmith/create-account-api-key) 和 [工作区 ID](/langsmith/set-up-hierarchy#set-up-a-workspace)。
* 一个 S3 或 S3 兼容的存储桶，并已授予 LangSmith **写入权限**（请参阅 [所需权限](/langsmith/data-export-destinations#permissions-required)）。
* 存储桶名称、前缀，以及 AWS 区域（对于 AWS S3）或端点 URL（对于 GCS、MinIO 或其他 S3 兼容提供商）。
* 存储桶的访问密钥和秘密密钥。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 将在保存前验证目标和凭证的有效性。如果请求失败，请参考 [调试目标错误](/langsmith/data-export-destinations#debug-destination-errors)。

保存响应中的 `id`；创建导出作业时将需要它。

有关权限设置、特定提供商配置（AWS S3、GCS、MinIO）和凭证选项，请参阅 [管理批量导出目标](/langsmith/data-export-destinations)。

## 2. 创建导出作业

导出作业针对特定的项目和日期范围。您需要：

* 来自 [上一步](#1-创建目标) 的目标 `id`。
* 项目 ID (`session_id`)——从 [**追踪项目** 列表](https://smith.langchain.com) 中的单个项目视图中复制。
* UTC ISO 8601 格式的 `start_time` 和 `end_time`。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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` 表达式来缩小导出的运行集。有关语法，请参考我们的 [过滤查询语言](/langsmith/trace-query-syntax#filter-query-language) 和 [示例](/langsmith/export-traces#use-filter-query-language)。不设置 `filter` 字段将导出所有运行。

### 计划定期导出

<Note>
  需要 LangSmith Helm 版本 >= `0.10.42`（应用版本 >= `0.10.109`）
</Note>

计划导出会定期收集运行并导出到配置的目标。
要创建计划导出，请包含 `interval_hours` 并省略 `end_time`：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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` 属性。如果需要，必须单独取消它们——取消源导出 **不会** 取消已派生的导出。
* 要停止计划导出，请 [取消它](/langsmith/data-export-monitor#stop-an-export)。

**示例**

如果创建了一个计划批量导出，其 `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`）。在一次性导出和计划导出中均受支持。
</Note>

您可以通过使用 `export_fields` 参数限制包含哪些字段来提高导出速度并减小文件大小。省略时，将包含所有字段。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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` 可以显著提高导出性能并减小文件大小，特别是对于大型运行。仅在分析需要时才包含这些字段。
</Tip>

### 可导出的字段

默认情况下，批量导出为每个运行包含以下字段：

**标识符与层次结构：**

| 字段                     | 描述            |
| ---------------------- | ------------- |
| `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. 监控您的导出

使用来自 [上一步](#2-创建导出作业) 的 `id` 轮询导出状态：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 文件即可在您的存储桶中使用。

有关如何列出运行、停止导出和诊断故障，请参阅 [监控和故障排除批量导出](/langsmith/data-export-monitor)。

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\data-export.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>