---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - example
  - attachments
topic: LangSmith Smith API Example 写入、附件、验证与删除语义
sources:
  - https://docs.langchain.com/langsmith/smith-api/examples/count-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/create-example
  - https://docs.langchain.com/langsmith/smith-api/examples/create-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/delete-example
  - https://docs.langchain.com/langsmith/smith-api/examples/delete-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/hard-delete-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/legacy-update-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/read-example
  - https://docs.langchain.com/langsmith/smith-api/examples/read-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/update-example
  - https://docs.langchain.com/langsmith/smith-api/examples/update-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/upload-examples
  - https://docs.langchain.com/langsmith/smith-api/examples/upload-examples-from-csv
  - https://docs.langchain.com/langsmith/smith-api/examples/validate-example
  - https://docs.langchain.com/langsmith/smith-api/examples/validate-examples
last_verified: 2026-08-11
---

# Smith API：Example 写入、附件、验证与删除语义

Example 是 Dataset 的版本化记录，通常由 `inputs`、可选 `outputs`、metadata、split、来源 run/trace 和附件组成。它既是评估输入，也是 gold/reference output 的载体；写入管道必须把数据契约、来源和删除级别明确分开。

## 创建与来源复用

单条与 bulk 创建都接受 `dataset_id`，并可提供：

- `inputs`、`outputs`、`metadata`；
- `split`，默认 `base`，也可为多个 split；
- 客户端指定 `id` 与 `created_at`；
- `source_run_id`、session/start time、trace 等来源；
- `use_source_run_io` 与 `use_source_run_attachments`；
- `use_legacy_message_format`。

从 run 复用 I/O 或附件时，来源 run 是数据血缘，不是永久授权。复制前仍要检查目标 Dataset 的敏感级别和保留策略。客户端生成 UUID 可用于幂等，但服务重试必须复用同一个 ID；每次重试生成新 ID 会制造重复样本。

## 查询与历史快照

单读和列表都支持 `as_of`，默认 `latest`。列表最大 100 条，可按 ID、dataset、metadata、全文、split 和服务端 filter 筛选，还支持列选择、顺序和随机种子；count 使用相同过滤维度但不返回对象。

随机抽样若要复现，固定 `random_seed`，并固定 dataset version。`select` 应最小化：列表页只读 ID/时间/名称时不要拉完整 inputs、outputs 和附件 URL，既降低成本也减少数据暴露。

## 两套更新路径

普通 `PATCH /examples/{id}` 更新 inputs、outputs、metadata、split 和附件操作；`overwrite=false` 表示调用方必须理解合并语义，不能假设是整对象替换。

旧 bulk PATCH 被官方标为 legacy。涉及附件时，应使用 dataset-scoped 的 multipart 端点：

```text
PATCH /api/v1/platform/datasets/{dataset_id}/examples
```

multipart 的 part 名以 example ID 为前缀：主 JSON、`.inputs`、`.outputs`、`.attachments_operations` 以及 `.attachment.{name}`。附件操作支持保留、重命名和新增。动态 part 名很容易在通用 HTTP 客户端里被错误转义，集成测试应覆盖 Unicode 文件名、重复名称、空附件和大文件边界。

## 上传

平台上传端点用 multipart 一次写入多条 example 和二进制附件，成功返回 `as_of`、数量与 IDs。CSV 专用旧入口要求 file、input keys，并可提供 output/metadata keys；官方建议非 CSV 使用更高效的平台端点。

上传流程建议：

1. 客户端先做 schema、大小、MIME 与病毒扫描；
2. 调用 validate 或在隔离 Dataset 预导入；
3. 记录请求批次与生成的 `as_of`；
4. 逐 ID 核对数量和附件；
5. 失败批次不要盲目整批重放，先确认哪些 ID 已落库。

## validate 并不等于持久化

单条和 bulk validate 返回规范化的 ExampleValidationResult，但不创建数据。它们适合在正式写入前检查 dataset、I/O、split、来源与 overwrite 参数。API 页面没有展示 request body schema时，客户端生成代码可能产生空 body；应以当前 OpenAPI/SDK 和真实 422 响应验证契约，不能因为文档页只有 response 就假设无需输入。

## 软删除与硬删除

删除有完全不同的语义：

| 操作 | 影响 |
|---|---|
| 单/批量 `DELETE /examples` | 仅从 Dataset 的 `latest` 版本软删除；历史版本仍可见 |
| 平台 hard delete | 对所有版本把 inputs、outputs、metadata 置空，并删除附件；保留 example ID、dataset ID、创建时间 |

硬删除最多 1000 个 IDs，且请求中的 `hard_delete` 当前只接受 `true`。正文、输出和 metadata 立即清空，但附件文件最多可能需要 7 天才物理删除。因此：

- 合规删除回执应区分“逻辑内容已清空”和“附件物理清理完成”；
- 不应承诺即时彻底删除；
- 删除任务要保存不含原文的 ID 审计、请求时间和复核时间；
- CDN、导出物和下游缓存需要单独处置。

## 一致性与安全边界

- Dataset 和 Example ID 都要在服务端租户范围内校验，不能相信客户端组合。
- inputs/outputs 可能包含 prompt injection、PII 或密钥；进入人工审核、导出、公开分享前做分类和脱敏。
- 附件 URL 可能是时效签名 URL，不应持久化为永久资源地址。
- 409 要按冲突处理，不能统一当临时网络错误无限重试。
- 更新和删除后以返回的 `as_of` 或重新读取确认结果；UI 本地状态不能替代服务端事实。

## 选择接口

| 需求 | 推荐入口 |
|---|---|
| 少量 JSON 创建 | 单条或 bulk JSON create |
| 多条且带附件 | dataset-scoped multipart upload |
| 带附件更新 | dataset-scoped multipart PATCH |
| CSV 初始化 | CSV upload |
| 上线前预检 | validate / validate bulk |
| 从最新集移除 | soft delete |
| 合规清除全部版本内容 | hard delete，并跟踪 7 天附件窗口 |

Dataset 的版本、导出与分享边界见 [[01-Dataset版本实验共享与导入导出]]。