数据集导入（Phase 2 基线）

最后更新：2025-11-09 · 负责人：Codex

FastAPI 后端提供了数据集导入能力。本文整理了 Phase 2 相关的后端行为、API 契约与运维约束。

概览

/datasets 路由目前包含三个关键端点：

POST /datasets/hf/preview：拉取 Hugging Face 数据集的元信息（features、info、sample rows），但不持久化。
POST /datasets/hf/import：按列映射把 HF 数据集实体化到关系型存储中。
POST /datasets/upload：导入由 v2 工具链生成的 .eval752.zip 包，并写入全部 sections/items。

所有端点都会返回 DatasetSummary，供前端更新本地缓存。

Hugging Face 工作流

Preview

POST /datasets/hf/preview
Content-Type: application/json
{
  "path": "lmsys/chatbot_arena",
  "split": "train[:50]",
  "limit": 10,
  "token": "hf_xxxx" // optional
}

响应结构：

{
  "features": [{"name": "prompt", "dtype": "string"}],
  "samples": [{"prompt": "…"}],
  "num_rows": 5000,
  "info": {"description": "Arena prompts", "citation": "…"}
}

limit 只限制预览样本数；切片语法（例如 train[:100]）直接交由 Hugging Face 数据集加载器处理。

Import

POST /datasets/hf/import
Content-Type: application/json
{
  "name": "chatbot-arena-2024",
  "description": "Arena prompts (Oct 2024 snapshot)",
  "config": {
    "path": "lmsys/chatbot_arena",
    "split": "train[:100]",
    "revision": "refs/heads/main"
  },
  "mapping": {
    "prompt_column": "prompt",
    "answer_column": "reference_answer",
    "default_type": "freeform",
    "meta_columns": {"source": "dataset", "difficulty": "level"},
    "criteria_columns": ["grading_rubric"],
    "choices_column": null
  }
}

导入流程会以 limit=None 加载 HF 数据集，把每一行转换成 JSONL v2.3 结构，计算确定性的 SHA-256 version_hash，并持久化成一个名为 default 的 Section，其中包含全部 Item。生成后的 Dataset.schema 结构如下：

{
  "source": "hf",
  "config": {"path": "…", "split": "…"},
  "features": {"prompt": "string"},
  "info": {"description": "…"},
  "mapping": {"prompt_column": "prompt", …}
}

校验规则：

缺少列会返回 400，例如 Column \prompt` not found in dataset row`。
choices_column 可以接收 JSON 数组或原始值。
assets_column 必须能解析为对象。
Asset 条目会被归一化为单一内部结构：
- mime_type 使用规范字段名（兼容旧输入中的 content_type）
- 嵌入式归档文件会还原为 encoding=base64 + data
- 远程图片 URL 继续保留为 url 元数据，可流向多模态 provider
当返回的 sample rows 中包含可用图片 URL 或嵌入式 asset 元数据时，HF preview 面板可以显示样例图片。

`.eval752.zip` 上传

上传端点接收 multipart form data：

POST /datasets/upload
Content-Type: multipart/form-data
name=imported-eval752
file=@dataset.zip

归档至少要包含一个符合 v2.3 schema 的 sections/*.jsonl 文件。可选文件包括 manifest.json（name/version hash）和 meta.json（description、default judge prompts 等）。导入器会：

解析每个 section 文件，并把其中每条记录转换为 DatasetItem。
对所有 sections/items 计算 version_hash。
按字典序持久化 sections，同时保留 JSON Lines 原始内容。
将原始 manifest/meta blob 存入 Dataset.schema（{"source": "eval752_zip", "package": {…}}）。

无效包（例如缺少 section 文件、JSON 格式错误）会返回带描述信息的 400。如果包里包含 assets/ 文件且 section JSONL 条目引用了这些资源，导入器会把它们重新还原为嵌入式 asset 元数据，这样上传后的数据集仍然能向 provider 发送图片并在 UI 中预览。

导出 `.eval752.zip`

Phase 2 引入了专门的打包服务 DatasetPackagingService，用于把数据集以及可选的某次完成运行打包成 specs/1_specs.md 中定义的可移植 .eval752.zip 归档。导出器会写入：

manifest.json：数据集标识、section 清单、生成器版本，以及可选的 run 元数据。
meta.json：保存数据集 notes/schema；如果包含 run，也会写入 run summary。
sections/*.jsonl：按 JSONL v2.3 结构保留所有 item。
run_config.json 与 results.jsonl：当指定某次 run 时，打包净化后的 LightEval 配置与评分结果，供离线重放。
assets/ 与 checkers/：从数据集元数据中解析出的文件。

归档转换 CLI

scripts/ 目录下提供了一个转换工具：

python scripts/convert_llmset_to_eval752.py source.llmset.zip --name "Converted Logic Set"

该脚本会读取 .llmset.zip，解析其中的 prompts/checkers/assets，默认输出 source.llmset.eval752.zip。转换器会把原始 manifest/meta blob 保留在新包的 meta.json.schema 中以便追溯，同时把 item 规范化为 JSONL v2.3 结构（system prompts 进入 inputs.system_prompt，judge prompts 放到 meta.judge_prompt， assets 获得稳定路径与已解码的 blob）。

后续 API 端点也会暴露同一套服务，让 SPA 能直接从数据集和运行详情页提供 “Download eval752 package”。

存储布局回顾

datasets：高层元数据（name、version_hash、schema、notes）
sections：数据集的有序子集（order_index 从 0 开始）
items：单条 JSONL 记录（payload、answer、checker、assets）

编写 Playwright 场景时，建议先请求 /datasets，提前填充 TanStack Query 缓存，再进入数据集详情页。

后续事项 / TODO

支持大体量 HF 数据集的流式导入，而不是一次性载入内存（Phase 2 stretch）
支持 HF 导入时写入多个 sections（按列衍生或手动分组）
在打包流程最终确定后，为 .eval752.zip 增加加密签名校验
在 /datasets 响应中暴露数据集摘要（item 数、tags），用于 UI 卡片

#数据集导入（Phase 2 基线）

#概览

#Hugging Face 工作流

#Preview

#Import

#.eval752.zip 上传

#导出 .eval752.zip

#归档转换 CLI

#存储布局回顾

#后续事项 / TODO