---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - dataset
  - evaluation
topic: LangSmith Smith API Dataset 版本、实验、共享与导入导出
sources:
  - https://docs.langchain.com/langsmith/smith-api/datasets/clone-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/create-comparative-experiment
  - https://docs.langchain.com/langsmith/smith-api/datasets/create-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/delete-comparative-experiment
  - https://docs.langchain.com/langsmith/smith-api/datasets/delete-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/delete-datasets
  - https://docs.langchain.com/langsmith/smith-api/datasets/diff-dataset-versions
  - https://docs.langchain.com/langsmith/smith-api/datasets/download-dataset-csv
  - https://docs.langchain.com/langsmith/smith-api/datasets/download-dataset-jsonl
  - https://docs.langchain.com/langsmith/smith-api/datasets/download-dataset-openai
  - https://docs.langchain.com/langsmith/smith-api/datasets/download-dataset-openai-ft
  - https://docs.langchain.com/langsmith/smith-api/datasets/fetch-experiment-runs-for-dataset-examples
  - https://docs.langchain.com/langsmith/smith-api/datasets/fetch-shared-experiment-runs-for-dataset-examples
  - https://docs.langchain.com/langsmith/smith-api/datasets/generate
  - https://docs.langchain.com/langsmith/smith-api/datasets/get-dataset-splits
  - https://docs.langchain.com/langsmith/smith-api/datasets/get-dataset-version
  - https://docs.langchain.com/langsmith/smith-api/datasets/get-dataset-versions
  - https://docs.langchain.com/langsmith/smith-api/datasets/read-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/read-dataset-share-state
  - https://docs.langchain.com/langsmith/smith-api/datasets/read-datasets
  - https://docs.langchain.com/langsmith/smith-api/datasets/read-datasets-stream
  - https://docs.langchain.com/langsmith/smith-api/datasets/read-examples-with-runs
  - https://docs.langchain.com/langsmith/smith-api/datasets/share-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/studio-experiment
  - https://docs.langchain.com/langsmith/smith-api/datasets/unshare-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/update-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/update-dataset-splits
  - https://docs.langchain.com/langsmith/smith-api/datasets/update-dataset-version
  - https://docs.langchain.com/langsmith/smith-api/datasets/upload-csv-dataset
  - https://docs.langchain.com/langsmith/smith-api/datasets/upload-experiment
last_verified: 2026-08-11
---

# Smith API：Dataset 版本、实验、共享与导入导出

Dataset 不是一张可随意覆盖的样本表，而是评估资产的版本边界。它同时承载输入/输出 schema、数据类型、transformations、splits、版本标签、实验关联和分享状态；生产系统应保存 `dataset_id + as_of/version tag`，不能只保存可变名称。

## 资源模型

`POST /api/v1/datasets` 创建数据集，核心字段包括：

- `name` 与可选描述；
- `inputs_schema_definition`、`outputs_schema_definition`；
- `data_type`，默认 `kv`；
- `externally_managed`，默认 `false`；
- `transformations`、`extra`、`tags` 与可选客户端生成 ID。

读取有三种形态：单个读取、带多条件/分页的列表，以及 JSON Patch 流。流式读取面向大列表和 UI 增量同步，消费者必须按顺序应用 patch，并在断线时从完整快照重新建立状态，不能把 patch 当独立对象缓存。

`PATCH /datasets/{dataset_id}` 对可选字段区分“未提供”与显式 `null`。SDK/网关若在序列化时自动补 null，可能无意清空 schema、描述或设置；更新 DTO 应启用 missing-field 语义。

## 版本与 splits

每次样本变化会形成可按时间点观察的数据集状态：

- `GET .../versions` 列版本；
- `GET .../version` 以 `as_of` 读取版本；
- `GET .../diff` 返回 added、modified、removed；
- `PUT .../versions` 给某个 `as_of` 设置版本 tag；
- split 接口读取并以 add/remove 方式更新集合。

版本 tag 是对历史时间点的命名引用，不是复制一份数据。CI 评估建议固定 tag 或精确时间；若永远使用 `latest`，基准集漂移会让同一代码版本的结果不可复现。split 更新同样应记录变更审计，避免训练集/测试集串漏。

## 克隆、生成与导入

克隆支持指定源/目标数据集、`as_of`，并按 example、split 或 tag 选取子集。这适合从只读基准派生实验分支；目标名称与幂等键应由调用方控制，重试前先查询，避免重复克隆。

`generate` 从既有数据生成合成样本。合成数据必须保留 provenance、生成模型/提示版本与人工抽检结果，不能与人工 gold set 混为一谈。

导入路径包括：

- multipart CSV 上传，可映射输入、输出、元数据列；
- 上传已有 experiment，把运行结果转成评估资产；
- Studio experiment 入口；
- 从实验导入时明确项目、数据集以及是否使用 reference output。

大文件上传要设置大小上限、内容类型校验、超时和失败重试策略；先校验再落正式数据集，避免半成功批次污染版本。

## 导出格式

官方接口覆盖 CSV、普通 JSONL、OpenAI Evals JSONL 与 OpenAI fine-tuning JSONL，均可按 `as_of` 固定版本。注意 JSONL 下载页的描述文字仍写成 CSV，这是文档文本错误；应以端点名、响应 Content-Type 和实际集成测试为准。

导出可能包含输入、参考输出、metadata 与附件引用，属于潜在敏感数据。生产下载要做最小权限、短期存储、访问审计和脱敏，不能把分享 token 或导出链接写进公开日志。

## 实验与对比实验

Dataset 是 experiment 的参照轴：

- `create-comparative-experiment` 把多个 experiment 放进同一对比对象；
- 删除 comparative experiment 只删除对比视图，不应被理解为删除原始 runs；
- `read-examples-with-runs` 把 examples 与实验 runs 对齐；
- V2 experiment-runs 接口返回 `{items, next_cursor}`，默认 20、最大 100，example IDs 上限 1000，experiments 必填；
- shared 版本用 share token 读取对应实验数据。

对比必须固定同一 dataset version，并检查每个 example 是否都有候选 run。否则均值可能来自不同样本集合，形成无效排名。

## 分享模型

`share-dataset` 生成公开访问状态，可选 `share_projects`；`read-dataset-share-state` 查询当前状态；`unshare-dataset` 撤销。分享 token 应按 bearer secret 管理：

1. 默认不开启；
2. 发布前检查 inputs、outputs、feedback、trace 与附件是否含 PII/密钥；
3. 分享后记录负责人、用途和到期复核；
4. 撤销后验证旧 token 已失效，并清理下游缓存。

## 删除与批量操作

单删和批量删都是破坏性动作；批量删除最多 100 个 ID。调用方应先解析精确目标、保存审计清单，并把“部分成功”作为可能结果处理。不要用名称模糊匹配后直接删除。

## 生产落地清单

- 评估任务固定 `dataset_id + version/tag`，结果中回写两者。
- schema 在写入和评估前双重验证；`externally_managed` 数据由唯一上游负责。
- 导入、生成、split、tag、分享和删除均写审计事件。
- cursor 分页循环到 `next_cursor=null`，不要假设一页完整。
- 公开分享视为数据发布流程，而不是普通读权限。
- 对 API 文档中的格式/路径歧义做契约测试，以当前 OpenAPI 与真实响应为准。

## 与其他笔记的关系

样本级写入、附件和硬删除见 [[02-Example写入附件验证与删除语义]]；人工审核队列见 [[03-Annotation-Queue审核调度与状态机]]；实验 evaluator、视图和优化见 [[04-Evaluator实验视图优化与Playground配置]]。