数据集、版本、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 接收：

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 与导出都属于数据出域操作，必须有权限与审计日志。