监控和排查批量导出问题

创建导出任务后，你可以使用本页中的 API 跟踪其进度、检查单个运行，并在需要时停止导出。本页还介绍了 LangSmith 如何自动处理故障，以及导出在重试次数耗尽后失败时应采取的措施。本页涵盖：

针对特定导出监控导出状态和列出运行。
在工作区中列出所有导出。
停止导出。
故障模式和重试策略，包括自动重试行为、故障场景、状态生命周期、并发限制和进度跟踪。
排查失败的导出。

适用于自托管、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 命令：

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 命令：

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 命令：

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 命令：

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 小时。

故障场景

故障类型	原因	是否自动重试？	所需操作
基础设施中断	部署、服务器重启、工作进程崩溃	是，会自动重新排队，并使用剩余的重试次数。	无，任务会自动恢复。
运行超时	单个运行超过 4 小时限制	是，最多重试 20 次（可能会更改）。	如果问题持续存在，请缩小日期范围、添加筛选条件或限制导出的字段。
工作流超时	整个导出超过 72 小时	否	缩小导出范围（日期范围、筛选条件），或拆分为多个较小的导出任务。
存储/目标位置错误	凭据无效、存储桶缺失、权限问题	否	修复目标位置配置并创建新的导出任务。
目标位置已删除	导出过程中存储桶被删除	否	重新创建目标位置并重新启动导出。
终端处理错误	数据序列化问题、资源耗尽	是，最多重试 20 次（可能会更改）。	检查运行错误详细信息，可能需要进一步调查。

任何单个运行失败（在所有重试次数均耗尽后）都会导致整个导出失败。

导出状态生命周期

导出可能具有以下状态：

Status	Description
`CREATED`	导出已创建，但尚未开始处理。
`RUNNING`	导出正在积极处理运行。
`COMPLETED`	所有运行均已成功导出。
`FAILED`	一个或多个运行在耗尽重试次数后失败。
`CANCELLED`	导出已由用户手动取消。
`TIMEDOUT`	导出超过了 48 小时的工作流超时限制。

单个运行也可能具有以下状态：CREATED、RUNNING、COMPLETED、FAILED、CANCELLED 或 TIMEDOUT。

并发和速率限制

为确保系统稳定性，导出受以下限制约束：

每个导出的最大并发运行数：45
每个工作区的最大并发导出数：15

如果你有多个正在运行的导出，新运行任务会排队等待，直到有可用容量。

自托管：调整批量导出并发数和负载大小

在 LangSmith Self-hosted 中，并发限制采用默认值。要调整批量导出期间 Pod 的内存使用量，请在 langsmith-backend 服务上配置以下环境变量：

Environment variable	Default	Description
`BULK_EXPORT_MAX_CONCURRENT_RUNS`	`5`	在单个导出中，每次调度过程中并行入队的最大分区运行数。处理大型日期分区时，降低此值可以限制内存峰值。
`DATA_EXPORT_RUN_LIMIT`	`500`	分页读取导出时间窗口时，每次查询从运行存储中获取的页面大小（最大行数）。
`DATA_EXPORT_MAX_BATCH_PAYLOAD_SIZE_KB`	`100000` (100 MB)	导出运行期间，在刷新批次前允许累积的最大负载大小（KB）。降低此值可以减少每个批次的内存占用。

内存受限部署的保守设置示例

# 在 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} endpoint 获取导出详细信息和状态。
查看运行错误：你可以使用 List Runs API 监控运行。每个运行都包含一个 errors 字段，其中按重试尝试次数记录详细错误消息（例如 retry_0、retry_1）。
验证目标位置访问权限：确保你的目标存储桶仍然存在，并且凭据有效。
检查运行大小：如果看到超时错误，日期分区中可能包含过多数据。此时可以尝试限制导出的字段。
检查系统限制：确保没有达到并发限制（每个导出 5 个运行、每个工作区 3 个导出）。

对于存储相关错误，可以在重试导出前，使用 AWS CLI 或 gsutil 测试目标位置配置。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Viewing & managing traces

Bulk export trace data

Messages view

Data type reference

监控导出状态

列出导出的运行

列出所有导出

停止导出

故障模式和重试策略

自动重试行为

故障场景

导出状态生命周期

并发和速率限制

自托管：调整批量导出并发数和负载大小

进度跟踪和可恢复性

排查失败的导出

​监控导出状态

​列出导出的运行

​列出所有导出

​停止导出

​故障模式和重试策略

​自动重试行为

​故障场景

​导出状态生命周期

​并发和速率限制

​自托管：调整批量导出并发数和负载大小

​进度跟踪和可恢复性

​排查失败的导出

监控导出状态

列出导出的运行

列出所有导出

停止导出

故障模式和重试策略

自动重试行为

故障场景

导出状态生命周期

并发和速率限制

自托管：调整批量导出并发数和负载大小

进度跟踪和可恢复性

排查失败的导出