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

# 批量导出追踪数据

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

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

  请注意，数据导出功能仅支持 [LangSmith Plus 或 Enterprise 层级](https://www.langchain.com/pricing-langsmith)。
</Info>

LangSmith 的批量数据导出允许您将特定项目和日期范围内的追踪数据以 [Parquet](https://parquet.apache.org/docs/overview/) 格式导出到兼容 S3 的存储桶，其字段与 [运行数据格式](/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)。
* 一个已授予 LangSmith **写入权限** 的 S3 或兼容 S3 的存储桶（请参阅 [所需权限](/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-create-a-destination) 中的目标 `id`。
* 项目 ID (`session_id`)——从 [**追踪项目** 列表](https://smith.langchain.com) 中的单个项目视图复制此 ID。
* 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)。有关聚合限制，请参阅以下注释。 |

<Note>
  **`feedback_stats` 聚合限制**

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

**令牌使用情况和成本：**

| 字段                  | 描述     |
| ------------------- | ------ |
| `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-create-an-export-job) 中的 `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="terminal-2">
    [将这些文档](/use-these-docs) 通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/data-export.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>