---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - tracing
  - ingestion
topic: LangSmith Smith API Run 写入、批量、附件与幂等边界
sources:
  - https://docs.langchain.com/langsmith/smith-api/runs/create-a-run
  - https://docs.langchain.com/langsmith/smith-api/runs/ingest-runs-batch-json
  - https://docs.langchain.com/langsmith/smith-api/runs/ingest-runs-multipart
  - https://docs.langchain.com/langsmith/smith-api/runs/update-a-run
last_verified: 2026-08-11
---

# Run 写入、批量、附件与幂等

Run 是 LangSmith tracing 的基本记录；Trace 由共享 `trace_id` 的树形 Run 组成，顶层 Run 的 `id` 应与 `trace_id` 对齐。写入接口的成功状态是 **202 Accepted**，表示已接受进入异步 ingest 链路，不等于已可查、已聚合或已持久化所有大字段。

## 四个写入端点

| 能力 | 方法与路径 | 契约 |
|---|---|---|
| 创建单个 Run | `POST /api/v1/runs` | JSON `runs.Run`，202 |
| 更新 Run | `PATCH /api/v1/runs/{run_id}` | 只传变更字段；未知字段被忽略，202 |
| JSON 批量 | `POST /api/v1/runs/batch` | `post` 和/或 `patch` 数组，202 |
| Multipart 批量 | `POST /api/v1/runs/multipart` | Run、Feedback、大字段和二进制附件同批 ingest，202 |

它们均接受 API Key、Tenant 上下文或 Bearer 认证。客户端必须从已验证的 workspace 上下文决定 `session_id`/项目，不能相信浏览器自报的 tenant/project ID。

## Run 数据模型

`runs.Run` 覆盖：

- 标识与树关系：`id`、`trace_id`、`parent_run_id`、`dotted_order`；
- 归属：`session_id` 或 `session_name`；
- 执行：`name`、`run_type`、`start_time`、`end_time`、`status`、`error`；
- 载荷：`inputs`、`outputs`、`events`、`extra`、`serialized`；
- 关联：`reference_example_id`、`tags`、输入/输出附件映射。

`run_type` 枚为 `tool|chain|llm|retriever|embedding|prompt|parser`。OpenAPI 对该 ingest schema 没有声明 required 字段，不代表生产端可以不建立不变式：应在 SDK/网关层要求 UUID、项目归属、开始时间及正确的父子链，否则可能得到孤儿 Run、错树或难以补写的费用数据。

## JSON batch 和 multipart 的选择

JSON batch 是一个对象，`post` 和 `patch` 均为 Run 数组。官方建议数百个 Run 优先批量；但输入/输出很大或带附件时，multipart 更稳定。

Multipart 的 part name 是协议的一部分：

- `post.<run_id>` / `patch.<run_id>`：Run JSON；
- `post|patch.<run_id>.<field>`：将 `inputs|outputs|events|error|extra|serialized` 大字段移出主 JSON；
- `feedback.<run_id>`：Feedback JSON，必须带 `trace_id` 与 `session_id`；
- `attachment.<run_id>.<filename>`：与 Run 绑定的二进制文件。

每个 part 都必须有 `Content-Type`，且有 `Content-Length` header 或 `length` 参数。不允许 part 级 `Content-Encoding`；可在整个请求上使用 `gzip` 或 `zstd`。对 part name、run_id 和 filename 做白名单/长度校验，不应把 filename 当存储路径；附件还需内容类型、大小、扫毒、保留期和下载授权。

## 幂等、顺序与重试

客户端应在首次发送前生成稳定 `run_id`/`trace_id`，网络超时后使用同一 ID 重试，不要每次生成新 ID。`409` 通常是冲突信号，应先查已有 Run；`429` 和短暂 5xx/网络错误可带 jitter 有界退避；`400/403/413/422` 需修正请求、授权或拆分载荷，不应盲目重试。

202 后若立即读不到，应以短时有界轮询处理最终一致；父 Run 创建和子 Run 补写要保持 ID/树关系不变。PATCH 声明“未知字段被忽略”，所以调用方必须在本地做 schema 严格校验，否则拼写错误会以“成功但未更新”的形式潜伏。