研究提案

[v2] 数据集 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 就是这个知识的载体。

🔄 [v2 改进]

采用路径：为什么数据团队应该用这个规范

原方案的最大缺失是：没有说清楚数据团队为什么应该采用 Context Card 而不是继续用 HuggingFace Data Card。这个问题不回答，规范就只是自说自话。

定位澄清：不是替代品，是「机器可读扩展层」

Context Card 的正确定位是 HuggingFace Data Card 的机器可读附加层，而非竞争关系：

  • HuggingFace Data Card：面向人类读者，叙述性，适合开源社区发布
  • Context Card：面向 Agent 消费，结构化，适合内部训练流水线

两者可以共存：对外发布时提交 HuggingFace Data Card，内部维护 Context Card 作为操作接口。

最小化采用路径（降低阻力）

不要求团队一次性实现全部四层。推荐的渐进式采用：

  • 阶段 0（试点，1天）：只实现 processing.steps 中的 input_count/output_count/filter_rate 三个字段——这是自动化成本最低的字段，pipeline 运行时即可写入
  • 阶段 1（2周）：增加 training_history 层——接入训练系统的 webhook，每次 run 结束自动写入配比和评测结果
  • 阶段 2（可选）：补充 provenance 和 meta_cognition 层

工具集成：Python SDK 示例

提供 SDK 让 pipeline 在运行时自动写入，消除手动维护成本：

from context_card import DatasetCard

card = DatasetCard.load("math-instruct-v3")

# 在 pipeline 每个 step 结束时自动调用
with card.processing_step("deduplication", code_ref="git#a3f2c91") as step:
    df_out = run_dedup(df_in)
    step.record(input_count=len(df_in), output_count=len(df_out))

card.save()  # 自动更新 version 和 updated_at

采用收益量化：实施阶段 0+1 后，数据团队可以：(1) 自动追踪每次 pipeline 变更对数据量的影响；(2) Agent 可直接查询历史训练效果做配比决策，减少人工整理报告的时间（估计每次训练 run 节省 2–4 小时的数据分析工作）。

🔄 [v2 改进]

Schema 版本化策略：保证历史数据不失效

一个规范的最大风险是字段频繁变更导致历史数据失效，进而引发工具链断层。本规范承诺以下版本化策略：

核心字段锁定原则

以下字段在 v1.x 全系列中锁定不变（breaking change 需发布 v2.0）：

  • id、version、created_at、updated_at
  • provenance.collection_period、provenance.sources[*].domain
  • processing.steps[*].step、.name、.input_count、.output_count、.filter_rate
  • training_history[*].run_id、.mix_ratio、.eval_results

扩展字段通过 extensions 命名空间处理

团队可以添加自定义字段，但必须放在 extensions 下，不污染核心命名空间：

extensions:
  my_team:
    custom_quality_score: 0.87
    internal_review_status: "approved"

向后兼容保证

  • 新增可选字段：向后兼容，旧解析器忽略即可
  • 删除/重命名字段：禁止在 minor 版本中执行，必须发布 deprecation notice 且提供 migration 脚本
  • 工具链在读取时遇到未知字段：忽略而非报错（宽松解析原则）

Schema 版本声明字段（新增至 YAML 根节点）：

_schema_version: "1.0"  # Context Card 规范版本，与数据集 version 字段分开

🔄 [v2 改进]

评估方案：量化验证「Context Card 对 Agent 决策有帮助」

「Agent 能读取 Context Card 做更好的决策」是核心 claim，但当前方案没有验证路径。以下是可操作的评估实验设计：

实验设计：有 Card vs 无 Card 的数据配比决策对比

  • 任务设定：给 Agent 一个目标（如「提升模型在 GSM8K 上的准确率同时保持 HumanEval 不下降超过 1%」），让它从 10 个候选数据集中决定各自的采样配比
  • 对照组（无 Card）：仅提供数据集名称和数据量，Agent 凭通用知识决策
  • 实验组（有 Card）：提供完整 Context Card，包含 training_history 中历史配比与评测结果
  • 重复次数：30 次随机化实验，避免 prompt 偶然性

主指标

  1. 配比决策准确率：与人工专家给出的「最优配比」的相关系数（Spearman’s ρ）
  2. 下游模型提升：按 Agent 决策的配比实际训练模型，在目标评测集上的分数 vs 基线（随机配比、人工配比）
  3. 决策一致性：同一目标下多次决策的方差（有 Card 应更低，因为有明确依据）

辅助指标

  • Agent 引用 training_history 字段的频率（验证 Card 被实际消费）
  • Agent 决策理由的可解释性评分（人工评估）

预期结论形式：「在 GSM8K 提升目标下，有 Context Card 的 Agent 配比决策使最终模型准确率比无 Card 基线高 X 点，配比决策与专家方案的相关系数从 0.3 提升至 0.7。」

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

原始版本：dataset-context-card-spec