模型卡怎样记录训练数据和限制条件

模型卡（Model Card）不是一句“这是一个文本生成模型”的简介，而是模型随仓库一起维护的说明文档。它要让使用者知道模型是什么、用什么数据训练、适合做什么、在哪些场景可能失败，以及评估结果是在什么条件下得到的。

官方文档：https://huggingface.co/docs/hub/model-cards

最实用的写法是：用 README.md 顶部的 YAML 元数据负责检索和关联，用正文负责解释数据来源、训练过程、用途、限制、评估方法与建议。没有掌握的信息要明确写成待补充，不要用推测填空。

模型卡先回答哪些问题

一份可用的模型卡至少要回答五类问题：模型由谁开发、它解决什么任务、训练数据从哪里来、怎样评估、使用时有哪些限制。Hugging Face Hub 会把模型仓库中的 README.md 渲染成模型卡，顶部可以放 YAML 元数据，下面再写人类可读的说明。

这里有一个重要边界：模型卡是文档和责任说明，不是模型质量保证书。它可以把已知证据、已知风险和推荐用法放在一起，但不能代替使用者针对自己数据和业务场景做测试。

用 YAML 元数据记录可检索信息

顶部 YAML 适合记录比较稳定、能被平台识别或筛选的字段，例如语言、许可证、数据集、基础模型、任务类型和库名称。下面是一个可以按真实项目改写的最小骨架：

---
language:
  - zh
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
datasets:
  - org/example-corpus
base_model: org/base-model
tags:
  - instruction-tuning
---

# 模型名称

datasets 应使用数据集在 Hub 上的仓库标识；如果模型是微调、适配器或量化版本，可以用 base_model 建立来源关系。许可证、语言和任务标签影响发现与使用判断，所以不能为了让页面看起来完整而随意填写。

训练数据要写清范围，而不只是列名称

训练数据部分至少写三件事：数据集名称或来源、覆盖范围、主要处理动作。只有一句“使用公开数据训练”通常不够，因为读者仍不知道语言、时间范围、过滤规则和可能遗漏的内容。

## 训练数据

- 数据来源：`org/example-corpus`，版本或提交号：`待补充`。
- 覆盖范围：中文技术问答，暂未覆盖图片和音频输入。
- 预处理：去除重复样本，按文档长度截断；过滤规则见 `scripts/filter_notes.md`。
- 未确认项：原始数据中的授权状态仍需由数据维护者补充确认。

如果训练数据来自多个数据集，应分别写出贡献、混合方式和采样策略；如果只能确认部分来源，就把已确认范围和未确认范围分开。数据卡可以进一步描述数据集的内容、许可证、语言、规模和偏差，模型卡则应链接到对应数据卡，而不是把所有细节压成一句宣传语。

训练过程要让别人知道模型学到了什么

训练过程不需要变成完整实验日志，但要给出足以理解结果的上下文。例如基础模型、微调方式、分词或图像预处理、训练轮数、关键超参数、硬件或检查点信息。对无法公开的内容，可以说明原因并标注缺失项。

## 训练过程

- 初始化：基于 `org/base-model` 微调。
- 输入处理：使用项目默认 tokenizer，最大长度为 `4096`；特殊 token 配置见仓库文件。
- 优化设置：学习率、批大小和训练轮数记录在实验配置中。
- 可复现线索：保留训练配置文件、数据版本和代码提交号。

# Python 示例：把模型卡中的关键记录整理为可审阅字典
records = {
    "data_version": "待补充",  # 中文注释：没有确认版本时不要填猜测值
    "base_model": "org/base-model",  # 中文注释：记录模型来源关系
    "preprocessing": ["deduplicate", "truncate"],  # 中文注释：说明输入如何被处理
}
print(records)

上面的示例只是文档字段的组织方式，不代表某个具体模型已经采用这些参数。文章中的代码或配置不能替代项目自己的训练记录，尤其不能把示例值直接当成真实实验结果。

把限制条件写成可判断的失败场景

限制条件最好写成“在什么输入或场景下可能出现什么问题”，然后给出减轻风险的建议。比如：长文本超过上下文窗口时结果会截断；训练数据中某类语言或领域样本不足时，相关任务表现可能不稳定；模型可能生成看似合理但未经核实的内容。

可以把三类信息分开写：

限制不要只写“效果可能有差异”。更好的表述是“该模型没有在某类数据上评估，因此不应把当前指标外推到该场景”，并在后面补上测试、过滤、人工审核或降级策略。

训练数据、评估与限制要能互相对上

评估结果必须带上下文：任务是什么、使用哪个数据集、指标是什么、结果来自哪次实验。一个单独的准确率数字无法说明模型是否适合你的输入，也不能证明训练数据覆盖了所有目标用户。

如果使用 Hugging Face Hub 支持的结构化评估元数据，可以在 YAML 中维护 model-index。正文仍然要解释评估设置和结果来源，避免读者只能看到一个无法复现的数字。

---
model-index:
  - name: example-model
    results:
      - task:
          type: text-generation
        dataset:
          name: Example benchmark
        metrics:
          - type: exact_match
            value: 0.0
            name: Exact Match
            # 中文注释：示例数值仅表示字段位置，正式发布前必须替换为真实结果
            verified: false
---

上段中的 0.0 是字段示意，不应被当成模型实测结果。实际项目应填入可追溯的评估值、评估代码或实验链接；如果还没有结果，就删掉示例值并写明“评估待补充”。

发布前用一张清单维护模型卡

1. 模型名称、版本、开发者和仓库来源是否明确？
2. 语言、许可证、任务类型、数据集和基础模型元数据是否与仓库实际内容一致？
3. 训练数据是否写了范围、处理动作和版本，而不是只有一个泛称？
4. 训练配置、预处理和评估结果是否保留了必要上下文？
5. 限制条件是否对应真实的失败场景，偏差与风险是否有缓解建议？
6. 未知信息是否明确标记，没有把示例值、推测或宣传话术写成事实？

模型卡的价值在于降低使用者的猜测成本：他们可以沿着数据集、训练过程、评估结果和限制条件逐项判断模型是否适合自己的任务。文档不必一次写完，但每次新增训练数据、改变基础模型或更新评估结果，都应同步更新对应章节。

常见问题

模型卡和数据集卡有什么区别？

模型卡描述模型如何构建、评估和使用；数据集卡描述数据集的内容、来源、许可证、规模和使用注意。两者可以互相链接，但不能用数据集卡代替模型卡的限制说明。

不知道完整训练数据时能不能发布模型卡？

可以，但要明确列出已知范围、未知项和原因，不能把“公开数据”当成完整来源说明。后续确认数据版本或过滤规则后，应更新模型卡。

只写评估分数够不够？

不够。还需要写任务、数据集、指标、评估设置和结果来源；同时把指标不能覆盖的场景写进限制条件。