研究提案

数据集 Context Card：Agent 可解析的数据履历规范

提出一种面向 AI 原生数据团队的结构化数据集描述规范，弥补现有 Model Card / Data Card 在 Agent 决策场景下的不足，并给出完整的 schema 设计与自动化维护策略。

数据工程 Agent 数据质检 schema 设计 AI 原生

数据集 Context Card：Agent 可解析的数据履历规范

一、现有方案的局限

HuggingFace 的 Model Card 和 Data Card 在社区推广上取得了不小的成功。它们让人类研究者在五分钟内对一个模型或数据集建立基本认知：这是什么、用来干什么、有没有已知偏见。但当我们问”Agent 能从中读取什么？“时，答案令人沮丧——几乎什么都不能。

问题不在于内容，而在于格式假设：现有的 Card 本质上是为人眼设计的 Markdown 文档。它的核心信息散落在自然语言段落里，没有机器可直接消费的字段，没有版本化的处理步骤，更没有与训练 run 的关联索引。

具体来看，当前方案存在三个致命缺陷：

1. 非结构化叙述，Agent 无法可靠提取。 “This dataset was collected from web crawls in 2023” 和 “数据来源于2023年网络爬取” 在语义上等价，但 Agent 读取时必须做 NLP 解析，准确率不稳定，无法直接驱动决策逻辑。

2. 缺失数据工程关键字段。 过滤率、每步清洗的代码版本、与具体训练 run 的映射关系——这些对数据工程师每天都要用到的字段，在现有规范里完全缺席。

3. 静态快照，无法追踪演化。 数据集会被反复清洗和版本迭代。一份没有变更历史的 Card 只描述了某个时间点，无法支持”这批数据在上次训练后有没有被进一步过滤”这样的查询。

AI 原生数据团队的提案（ai-native-data-team-v2）指出每个数据集应维护一份”数据履历”，但没有定义履历的数据结构。这个 schema 的缺位，正是本文要填补的。

二、Agent 真正需要什么信息

在数据质检和配比决策场景中，Agent 的工作可以分解为几类典型任务：

  • 质检：判断这批数据是否满足当前训练目标的质量门槛
  • 配比：在多个数据集之间分配采样权重
  • 溯源：当模型出现某类问题时，定位可能的数据来源
  • 预测：根据历史训练结果，预估加入这批数据后的能力变化

要完成这些任务，Agent 需要一个分层信息模型：

来源层（Provenance Layer）

Agent 需要知道数据从哪里来、什么时候采集的、用什么策略筛选的。这决定了数据的”先天质量上界”：

  • 采集时间范围（影响时效性和知识截止点）
  • 来源域（domain）及其权重分布
  • 采集策略（全量爬取？关键词过滤？种子 URL 扩散？）
  • 原始质量估计（去重前的重复率、语言分布、内容类型分布）

处理层（Processing Layer）

原始数据经过多轮清洗才能进入训练。Agent 需要理解每一步做了什么、过滤掉了多少、以及用的是哪个版本的代码——这直接决定能否复现：

  • 清洗步骤列表（有序，附 commit hash 或代码链接）
  • 每步的输入/输出样本数及过滤率
  • 已知问题（如某步骤引入了特定偏差、某批次数据异常）

训练历史层（Training History Layer）

数据集的”价值”不只在于它自身的质量，还在于它在实际训练中的表现历史：

  • 出现过的训练 run ID 列表
  • 每次 run 中的采样配比
  • 对应的能力评估结果（按评测集维度）

这一层让 Agent 可以做因果推断：「上次以 15% 配比加入这批数学数据，GSM8K 提升了 3.2 点」。

元认知层（Meta-Cognition Layer）

这是最”软”但往往最有用的一层——对数据集的主观评估，通常来自数据工程师的经验：

  • 这个数据集”擅长”什么（能力标签）
  • “有问题”的典型样本示例（及问题类型）
  • 推荐使用场景和不推荐使用场景

三、Context Card Schema 设计

基于上述分层模型，给出完整的 YAML schema 示例：

# dataset-context-card.yaml
# Context Card v1.0 - Agent-readable dataset descriptor

id: "math-instruct-v3"
version: "3.2.1"
created_at: "2025-11-01T08:00:00Z"
updated_at: "2026-03-15T14:30:00Z"
maintainers:
  - id: "u_alice"
    role: "owner"

# ── 来源层 ──────────────────────────────────────────
provenance:
  collection_period:
    start: "2024-06-01"
    end: "2025-10-31"
  sources:
    - domain: "math.stackexchange.com"
      weight: 0.35
      strategy: "full_crawl"
    - domain: "arxiv.org/cs.LG"
      weight: 0.25
      strategy: "keyword_filter"
      keywords: ["theorem", "proof", "lemma"]
    - domain: "synthetic_cot_pipeline_v2"
      weight: 0.40
      strategy: "generative"
      generator_model: "gpt-4o-2024-08"
  raw_quality_estimate:
    dedup_ratio_before: 0.23        # 去重前重复率
    language_distribution:
      zh: 0.15
      en: 0.82
      other: 0.03
    content_type_distribution:
      qa_pair: 0.60
      long_form_reasoning: 0.30
      code_with_math: 0.10

# ── 处理层 ──────────────────────────────────────────
processing:
  pipeline_id: "clean-math-v3"
  steps:
    - step: 1
      name: "language_filter"
      description: "保留中英文，过滤其他语言"
      code_ref: "git@gongfeng:data/pipelines#a3f2c91"
      input_count: 12_400_000
      output_count: 12_008_000
      filter_rate: 0.032
    - step: 2
      name: "deduplication"
      description: "MinHash LSH 去重，jaccard 阈值 0.85"
      code_ref: "git@gongfeng:data/pipelines#a3f2c91"
      input_count: 12_008_000
      output_count: 9_856_000
      filter_rate: 0.179
    - step: 3
      name: "quality_classifier"
      description: "fastText 质量分类器，过滤低质内容"
      code_ref: "git@gongfeng:data/pipelines#b71e004"
      input_count: 9_856_000
      output_count: 8_100_000
      filter_rate: 0.178
      model_ref: "quality-clf-math-v2.bin"
    - step: 4
      name: "format_normalization"
      description: "统一 LaTeX 格式，修复 Unicode 异常"
      code_ref: "git@gongfeng:data/pipelines#b71e004"
      input_count: 8_100_000
      output_count: 8_097_000
      filter_rate: 0.0004
  final_count: 8_097_000
  known_issues:
    - issue_id: "ISS-042"
      severity: "medium"
      description: "step3 质量分类器对竞赛数学（olympiad）有轻微偏低打分，估计约 3% 的高质量竞赛题被错误过滤"
      affected_step: 3
      status: "open"
      reported_by: "u_bob"
      reported_at: "2026-01-10"

# ── 训练历史层 ──────────────────────────────────────
training_history:
  - run_id: "train-run-20251120"
    mix_ratio: 0.12
    mix_strategy: "uniform_sampling"
    eval_results:
      gsm8k: 0.812
      math_500: 0.641
      minerva: 0.387
    notes: "首次引入该数据集，数学能力显著提升"
  - run_id: "train-run-20260115"
    mix_ratio: 0.18
    mix_strategy: "difficulty_weighted"
    eval_results:
      gsm8k: 0.841
      math_500: 0.678
      minerva: 0.412
    notes: "提高配比后进一步提升，但代码能力略有下降 (-0.8 HumanEval)"

# ── 元认知层 ──────────────────────────────────────────
meta_cognition:
  strengths:
    - tag: "multi_step_reasoning"
      confidence: 0.9
    - tag: "algebra"
      confidence: 0.85
    - tag: "proof_writing"
      confidence: 0.75
  weaknesses:
    - tag: "geometry_visual"
      confidence: 0.8
      note: "缺乏图形辅助的几何题"
    - tag: "combinatorics_olympiad"
      confidence: 0.6
      note: "见 ISS-042"
  typical_bad_samples:
    - sample_id: "ms3-bad-001"
      content_preview: "答案直接给出数字，无推理过程..."
      issue_type: "missing_reasoning_chain"
    - sample_id: "ms3-bad-002"
      content_preview: "LaTeX 公式残缺，\\frac{ 未闭合..."
      issue_type: "format_corruption"
  recommended_use_cases:
    - "数学推理能力训练（SFT/RL）"
    - "思维链（CoT）数据增强"
  not_recommended_for:
    - "几何视觉推理（缺图形数据）"
    - "金融数学（领域覆盖不足）"

四、自动化维护策略

Context Card 的可持续性取决于维护成本——如果所有字段都要手动填写，它最终会烂掉。字段应按照可自动化程度分级：

完全自动（Auto）：由数据处理流水线在运行时写入，零人工成本：

  • processing.steps[*].input_count / output_count / filter_rate
  • processing.final_count
  • training_history[*].run_id / mix_ratio / eval_results
  • provenance.raw_quality_estimate.*（由质量统计脚本生成）
  • version、updated_at（git hook 触发）

半自动（Semi-Auto）：工具辅助生成草稿，人工确认：

  • processing.steps[*].description（从代码注释提取）
  • meta_cognition.strengths / weaknesses（由分析 Agent 基于训练历史推断，需人工审核）
  • known_issues（由数据质检 CI 自动检出，人工补充 severity 和 description）

必须人工（Manual）：无法从现有信号中可靠推断：

  • meta_cognition.typical_bad_samples（需人眼判断”典型性”）
  • recommended_use_cases / not_recommended_for（需业务判断）
  • known_issues[*].severity（需人工定级）

这套分级原则可以用一句话总结：凡是代码运行过程中就能知道的，都让代码写；凡是需要理解”为什么”的，才需要人介入。

五、与 AI 原生数据团队提案的关系

ai-native-data-team-v2 提案的核心主张是：数据工程应该像软件工程一样可追踪、可测试、可迭代。提案列出了”数据履历”作为基础设施之一，但停留在概念层面。

Context Card 是该提案信息层的具体实现，填补了以下空白：

提案主张Context Card 对应字段
数据来源可追溯provenance.*
处理过程可复现processing.steps[*].code_ref
质量可量化processing.steps[*].filter_rate，known_issues
与训练结果关联training_history.*
支持 Agent 决策整体结构化 schema

更重要的是，Context Card 将”数据履历”从一个记录工具升级为一个决策接口。当 Agent 需要为新一轮训练选择数据配比时，它可以直接查询每个数据集的 training_history，检索哪些配比在目标评测集上有过正向效果，而不需要人工整理报告。

这是 AI 原生数据团队与传统数据团队的本质区别：数据不只是给人看的文件，而是 Agent 可以直接消费的结构化知识。Context Card 就是这个知识的载体。

本文是 ai-native-data-team-v2 提案的配套规范文档，建议与该提案一同阅读。schema 版本：v1.0，后续迭代将保持向后兼容。