主题
监控并排查批量导出
监控批量导出状态、管理进行中的导出，并排查失败。
一旦你创建了一个导出作业，你就可以使用本页的 API 来跟踪其进度、检查单个运行，并在需要时停止它。本页还涵盖 LangSmith 如何自动处理失败，以及当导出在耗尽重试后失败时该怎么做。
本页涵盖：
NOTE
对于自托管、GCP EU、GCP APAC 和 AWS US SaaS
对于自托管安装、GCP EU（eu.api.smith.langchain.com）、GCP APAC（apac.api.smith.langchain.com）或 AWS US（aws.api.smith.langchain.com），请更新下方请求中的 LangSmith URL。
监控导出状态
要监控一个导出作业的状态，使用以下 cURL 命令：
bash
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'将 {export_id} 替换为你想要监控的导出的 ID。此命令检索指定导出作业的当前状态。
列出某个导出的运行
一个导出通常被分成多个运行，每个运行对应一个要导出的特定日期分区。 要列出与某个特定导出关联的所有运行，使用以下 cURL 命令：
bash
curl --request GET \
--url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}/runs' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-Tenant-Id: YOUR_WORKSPACE_ID'此命令获取与指定导出相关的所有运行，提供诸如运行 ID、状态、创建时间、导出行数等详情。
列出所有导出
要检索所有导出作业的列表，使用以下 cURL 命令：
bash
curl --request GET \
--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'此命令返回所有导出作业的列表，附带其当前状态和创建时间戳。
停止一个导出
要停止一个现有的导出，使用以下 cURL 命令：
bash
curl --request PATCH \
--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' \
--data '{
"status": "Cancelled"
}'将 {export_id} 替换为你希望取消的导出的 ID。注意，一个作业一旦被取消就无法重启， 你将需要改为创建一个新的导出作业。
失败模式与重试策略
LangSmith 批量导出会自动处理瞬时失败和基础设施问题，以确保韧性。
每个批量导出被划分为多个运行，其中每个运行处理一个特定日期分区的数据（通常按天组织）。运行被独立地处理，这实现了：
- 不同时间段的并行处理。
- 每个运行的独立重试逻辑。
- 若被中断，则从特定检查点恢复。
你导出中的每个运行（日期范围）都有自己的失败处理和重试预算。如果一个运行在耗尽所有重试后失败，整个导出会被标记为 FAILED。
自动重试行为
导出作业会用以下行为自动重试瞬时失败：
- 最大重试次数：每个运行 20 次重试（可能变化）。
- 重试延迟：尝试之间 30 秒（固定，无指数退避）。
- 运行超时：每个运行最多 4 小时。
- 整体工作流超时：整个导出 72 小时。
失败场景
| 失败类型 | 原因 | 自动重试？ | 需要的动作 |
|---|---|---|---|
| 基础设施中断 | 部署、服务器重启、worker 崩溃 | 是，自动带着剩余重试重新入队。 | 无，作业自动恢复。 |
| 运行超时 | 单个运行超过 4 小时限制 | 是，最多重试 20 次（可能变化）。 | 若持续发生，缩小日期范围、添加过滤器，或限制导出字段。 |
| 工作流超时 | 整个导出超过 72 小时 | 否 | 缩小导出范围（日期范围、过滤器）或拆分为更小的导出。 |
| 存储/目的地错误 | 无效凭据、缺失 bucket、权限问题 | 否 | 修复目的地配置并创建新导出。 |
| 目的地被删除 | 导出期间 bucket 被移除 | 否 | 重新创建目的地并重启导出。 |
| 终态处理错误 | 数据序列化问题、资源耗尽 | 是，最多重试 20 次（可能变化）。 | 检查运行错误详情；可能需要调查。 |
NOTE
任何单个运行失败（在耗尽所有重试之后）都会导致整个导出失败。
导出状态生命周期
导出可以有以下状态：
| 状态 | 描述 |
|---|---|
CREATED | 导出已被创建但尚未开始处理。 |
RUNNING | 导出正在积极处理各个运行。 |
COMPLETED | 所有运行都成功导出。 |
FAILED | 一个或多个运行在耗尽重试后失败。 |
CANCELLED | 导出被用户手动取消。 |
TIMEDOUT | 导出超过了 48 小时的工作流超时。 |
单个运行可以有相同的可能状态：CREATED、RUNNING、COMPLETED、FAILED、CANCELLED 或 TIMEDOUT。
并发与速率限制
为确保系统稳定，导出受以下限制约束：
- 每个导出的最大并发运行：45
- 每个工作区的最大并发导出：15
如果你有多个导出正在运行，新的运行作业会排队直到容量可用。
自托管：调优批量导出的并发和负载大小
在 LangSmith 自托管上，上述并发限制是默认值。要在批量导出期间调优 pod 内存使用，请在 langsmith-backend 服务上配置以下环境变量：
| 环境变量 | 默认值 | 描述 |
|---|---|---|
BULK_EXPORT_MAX_CONCURRENT_RUNS | 5 | 单次调度过程中，在单个导出内并行入队的分区运行最大数。减小它以在处理大日期分区时限制峰值内存。 |
DATA_EXPORT_RUN_LIMIT | 500 | 分页遍历导出窗口时，每次查询从运行存储抓取页大小（最大行数）。 |
DATA_EXPORT_MAX_BATCH_PAYLOAD_SIZE_KB | 100000 (100 MB) | 导出运行期间一个批次被刷新前累计的最大负载大小（KB）。减小它以降低每个批次的内存占用。 |
示例：内存受限部署的保守设置
yaml
# In your Helm values
BULK_EXPORT_MAX_CONCURRENT_RUNS: "10"
DATA_EXPORT_RUN_LIMIT: "5"
DATA_EXPORT_MAX_BATCH_PAYLOAD_SIZE_KB: "512"降低这些值会减少并行度并可能增加总导出时间，但会降低每个 pod 的峰值内存使用。如果你在内存受限的节点上遇到内存不足（OOM）错误，这些设置会有帮助。
进度跟踪与可恢复性
导出系统为每个运行维护详细的进度元数据：
- 数据流中最新的游标位置。
- 已导出的行数。
- 已写入的 Parquet 文件列表。
这种进度跟踪实现了：
- 优雅恢复：如果一个运行被中断（例如被一次部署），它会从最后一个检查点恢复，而非从头开始。
- 进度监控：通过 API 跟踪已导出数据有多少。
- 高效重试：失败的运行不会重新导出那些已成功写入的数据。
排查失败的导出
如果你的导出失败，请遵循以下步骤：
- 检查导出状态：使用
GET /api/v1/bulk-exports/{export_id}端点 检索导出详情和状态。 - 查看运行错误：你可以使用 List Runs API 来监控你的运行。每个运行都包含一个
errors字段，带有按重试尝试（例如retry_0、retry_1）为键的详细错误消息。 - 核实目的地访问：确保你的目的地 bucket仍然存在，且凭据有效。
- 检查运行大小：如果你看到超时错误，你的日期分区可能包含太多数据。限制导出字段可能有帮助。
- 查看系统限制：确保你没有触及并发限制（每个导出 5 个运行，每个工作区 3 个导出）。
对于存储相关的错误，你可以在重试导出之前使用 AWS CLI 或 gsutil 测试你的目的地配置。