---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - bulk-export
  - backfill
topic: LangSmith Smith API Bulk Exports 目的地、计划作业与 Backfill
sources:
  - https://docs.langchain.com/langsmith/smith-api/backfills/restart-a-backfill-job
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/cancel-bulk-export
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/create-bulk-export
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/create-bulk-export-destination
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/get-bulk-export
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/get-bulk-export-destination
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/get-bulk-export-destinations
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/get-bulk-export-run
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/get-bulk-export-runs
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/get-bulk-export-runs-filtered
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/get-bulk-exports
  - https://docs.langchain.com/langsmith/smith-api/bulk-exports/update-bulk-export-destination
last_verified: 2026-08-11
---

# Bulk Exports 目的地、计划作业与 Backfill

Bulk Export 将 workspace 内的 Traces/Experiments 按时间窗和 filter 输出到 S3 兼容目的地。它包含三层资源：Destination（去哪里）、Export（导出定义/计划）、Export Run（某个实际时间窗的执行）。

## Destination

| 能力 | 方法与路径 |
|---|---|
| 创建 | `POST /api/v1/bulk-exports/destinations` |
| 列表 / 读单个 | `GET .../destinations` / `GET .../destinations/{destination_id}` |
| 更新凭据 | `PATCH .../destinations/{destination_id}` |

当前 destination type 只有 `s3`。创建必填 display name 和 config，可带 static credentials；config 包含 endpoint URL、bucket、prefix、region、S3/botocore 额外参数、path/virtual addressing、是否把 bucket 加进 prefix，以及可选 AWS role ARN。响应只返回 `credentials_keys`，不回显密钥值。

优先使用短期 AssumeRole 和限定 bucket/prefix 的最小权限，不用长期静态 access key。自定义 endpoint 要防 SSRF/DNS rebinding，禁止私网/云元数据地址，限制 TLS、重定向、端口和 bucket 命名。变更凭据时用“新权限验证 → 切换 → 跑一个受控导出 → 撤销旧凭据”，不在日志或 Trace 中记录 credentials。

当前组内没有 Destination 删除端点，不要自行拼猜 DELETE；退役时先停所有 Export/调度，再撤销 role/key 和 bucket 权限。

## Export 定义与状态

| 能力 | 方法与路径 |
|---|---|
| 创建 | `POST /api/v1/bulk-exports` |
| 列表 / 读单个 | `GET /api/v1/bulk-exports` / `GET .../{bulk_export_id}` |
| 取消 | `PATCH /api/v1/bulk-exports/{bulk_export_id}`，body status 只允许 `Cancelled` |

创建必填 destination ID 和 `start_time`，可指定 `session_id` 或 `all_experiments`、end time、filter、`interval_hours`、导出字段。格式为 Parquet，版本 `v1|v2_beta`，压缩 `none|gzip|snappy|zstandard`。业务层强制明确且最小的作用域，不同时依赖含糊的 session/all-experiments 组合。

Export 状态：`Created|IntervalScheduled|Running|Completed|Failed|TimedOut|Cancelled`。`interval_hours` 会创建持续计划；列表中的 `source_bulk_export_id` 用来把派生执行关联回源计划。取消只是状态转换，不代表已写 S3 对象被删，也不保证正在上传的分片立即停止。

## Export Run 与对账

- `GET /api/v1/bulk-exports/{bulk_export_id}/runs`：按 export 列执行，offset/limit；
- `GET .../{bulk_export_id}/runs/{run_id}`：读单次执行；
- `GET /api/v1/bulk-exports/runs?source_bulk_export_id=...`：按计划源 ID 列派生执行。

Run 状态为 `Created|Running|Completed|Failed|TimedOut|Cancelled`，带 retry number、errors、start/end/finished time 和 metadata。metadata 包含目标 prefix、时间窗、执行 backend 及 progress/result。对每个时间窗保存 `(source export, run ID, start, end, prefix, status, retry)`，校验窗口无缝、S3 object/manifest 完整和行数/校验和。

文档未明确时间窗边界是 inclusive 还是 exclusive；不要凭经验推断。首次上线用边界时刻的受控 Run 做 contract test，将实测规则固定在下游去重键中。v2_beta 格式要做 schema evolution 兼容，消费端忽略未知列、不假定列顺序。

## 幂等、重试与失败恢复

创建 Destination/Export 没有文档化 idempotency key，超时后先 list/get 按业务指纹查重，不盲目再创一个计划。执行失败后以时间窗 + export ID 去重，只重跑未完成窗口；下游使用临时 prefix 写入，校验完成后再发布 manifest/成功标记，防止消费半成品。

## Restart Backfill 是独立的实例管理高风险接口

`POST /api/v1/platform/ops/backfills/restart` 需要 **instance admin**，body 中是 `backfill_name`。它会删除 backfill job 记录，使作业在下一次 cron tick **从头重启**；这不是普通 Export Run 的局部 retry。

执行前必须确认精确 backfill name、影响数据集/时间窗、历史进度、剩余时间/存储和下游幂等性，获得审批并保存重启前快照。HTTP 200 只表示重启请求已处理，作业要到 cron 后才开始；监控新 job ID、进度、重复写入和错误。