---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langsmith
  - datasets
  - security
  - evaluation
topic: LangSmith 数据集、版本、Schema、转换与自定义渲染安全
sources:
  - https://docs.langchain.com/langsmith/manage-datasets-in-application
  - https://docs.langchain.com/langsmith/manage-datasets-programmatically
  - https://docs.langchain.com/langsmith/manage-datasets
  - https://docs.langchain.com/langsmith/custom-output-rendering
  - https://docs.langchain.com/langsmith/example-data-format
  - https://docs.langchain.com/langsmith/dataset-json-types
  - https://docs.langchain.com/langsmith/dataset-transformations
last_verified: 2026-08-11
---
# 数据集、版本、Schema 与安全边界

## 数据模型

Dataset 是一组 Example。Example 的稳定字段包括 `id`、`name`、创建/修改时间、`inputs`、`outputs`、`dataset_id`、可选 `source_run_id` 与 `metadata`。`outputs` 在评估数据中承担 reference output；也可以保存人工写出的 assertions，供 evaluator 从 `reference_outputs["assertions"]` 读取。

数据集可从 UI 手工创建、CSV/JSONL 导入、Playground、生产 traces、run rule、annotation queue 或合成生成；SDK 可创建、批量添加、查询、更新与删除。大批量 examples 应用 bulk API，避免逐条请求造成延迟、限流和部分成功难以恢复。

## Schema 与转换

LangSmith 允许任意 JSON，但建议为 inputs/outputs 定义标准 JSON Schema，尽早阻止字段漂移。预置 `$ref` 包括 OpenAI 风格的 Message 与 Tool 类型。

Schema 字段可以绑定入库前 transformation：

- `remove_system_messages`：去除 system message；
- `convert_to_openai_message`：把 LangChain/常见 trace 消息转换成 OpenAI 标准格式；
- `convert_to_openai_tool`：提取并标准化 tool definitions；
- `remove_extra_fields`：移除 schema 未声明字段。

Chat Model 预置 schema 会抽取 messages 和 tools，便于跨 provider 复现实验。它主要兼容 LangChain `BaseChatModel` traces 与 LangSmith OpenAI wrapper；其他 graph state 或自定义 run 需要显式 schema 和 transformation。转换发生在写入时，因此规则变更不应被误认为会自动重写全部历史数据。

## 版本、split 与 metadata

- 每次增加、更新或删除 example 都自动产生 dataset version；历史版本只读。
- 用语义 tag（如 `prod`）固定重要版本；CI 明确传 `as_of`/`asOf`，不要隐式依赖 latest。
- split 表示训练/验证、难度、领域或 staged rollout 等评估分组；一个 example 技术上可属于多个 split。
- metadata 表示来源、标签、版本等逐样本属性，用于筛选与分析。多个筛选条件按 AND 组合。
- 可以把 experiment 中满足条件的 traces 回流到 dataset，形成失败样本闭环。

## UI 与 SDK 边界

- Playground 不能内联创建含嵌套 key 的 dataset；嵌套结构需到 dataset 页面编辑。
- 在 Playground 删除 Reference Output 列不可逆，应先确认是否真的要变成 reference-free 数据集。
- annotation queue 只有 run item 能导出到 dataset；thread item 可收集 rubric feedback，但不能直接导出。
- 合成 examples 需要现有样本和 schema，生成后仍要人工选择/编辑；系统会按 schema 校验并在 source metadata 标记 synthetic。
- dataset 可以导出 CSV、JSONL 或 OpenAI fine-tuning 格式；导出并不自动完成脱敏或许可审查。

## 高风险操作：公开分享

公开分享 dataset 会让**所有持链接者**访问 examples、experiments、关联 runs 和 feedback，即使没有 LangSmith 账户；该功能仅 Cloud 提供。发布前必须执行敏感数据、客户内容、密钥、内部 prompt、许可与数据驻留审查。取消分享只撤销后续访问，不能收回已下载或缓存的数据。

## 自定义输出渲染

自定义 HTML renderer 通过 `postMessage` 接收：

```text
type: output | reference
data: 实际或参考输出
metadata.inputs: 生成输出的输入
```

配置优先级为 annotation queue > dataset > tracing project；消息最多发送 6 次，间隔按 100、200、400、800、1600、3200ms 指数退避。

文档示例只用于演示数据显示，没有校验 `event.origin`。生产 renderer 必须把页面视为处理潜在敏感数据的受信应用：校验 origin/source 和消息 schema，使用 `textContent` 而非不可信 HTML，部署严格 CSP，禁止第三方脚本外传输入/输出，并将 renderer URL 纳入变更与供应链审查。这是基于浏览器安全模型的实施要求，不是示例自动提供的保护。

## 运维检查表

- dataset、schema、transformation 和 evaluator 版本应共同记录；否则无法重现实验。
- 大批量写入要记录幂等键、失败项和重试结果。
- 生产 trace 进入 dataset 前做脱敏与采样审查。
- CI 固定 dataset tag、模型版本、prompt 版本、并发与 repetition。
- public share、renderer 与导出都属于数据出域操作，必须有权限与审计日志。