企业官网建设流程全解析

• 开发工具
• CLI
• 机器学习

huggingface_hub官方客户端在 templates/modelcard_template.md 中内置了一份功能完备的 Model Card（模型卡片）默认模板。本文以该模板为骨架，逐一拆解它的 YAML 元数据头、约 20 个 Markdown 章节与全部 Jinja2 变量，并结合huggingface_hub的ModelCard/ModelCardData/EvalResult源码与测试用例，讲解如何从模板一键生成模型卡片、校验、保存并推送到 Hugging Face Hub。读完本文，你将能熟练使用默认模板产出符合 Hub 规范、可直接检索与引用的高质量 Model Card，并掌握自定义模板的完整机制。

模板定位：仓库内 Model Card 的标准骨架

默认模板位于src/huggingface_hub/templates/目录下，同目录还有对应的数据集卡片模板 datasetcard_template.md。在 repocard.py 中，模板路径被定义为模块级常量（repocard.py#L29-L30）：

TEMPLATE_MODELCARD_PATH = Path(__file__).parent / "templates" / "modelcard_template.md" TEMPLATE_DATASETCARD_PATH = Path(__file__).parent / "templates" / "datasetcard_template.md"

而模型仓库的卡片文件约定为README.md（见 constants.py#L35 中的REPOCARD_NAME = "README.md"）。也就是说，模板渲染出的内容最终要写入模型仓库的README.md，Hub 会解析其 YAML 头部作为结构化元数据，并渲染 Markdown 正文作为模型的主页展示。

从类继承关系看，ModelCard继承自RepoCard（repocard.py#L336-L339），其card_data_class为ModelCardData、default_template_path即上述模型模板、repo_type为"model"。模板的核心渲染逻辑集中在基类RepoCard.from_template（repocard.py#L289-L333）：它会将card_data序列化为 YAML 字符串、加载 Jinja2 模板并填充所有变量，最终构造出一个完整的RepoCard实例。

模板的总体结构：YAML 元数据头 + Markdown 正文

整个模板由两大部分组成：

1. YAML front matter（元数据头）：以---包裹的{{ card_data }}占位符，由ModelCardData序列化后的 YAML 填充。Hub 依靠这部分做结构化解析、搜索过滤与排行榜接入。
2. Markdown 正文：从# Model Card for {{ model_id }}标题开始，按官方 Model Card 规范组织约 17 个大章节，几乎全部由 Jinja2 变量占位。

模板变量普遍采用{{ var | default("[More Information Needed]", true) }}的写法。这里的default过滤器是理解模板行为的关键：第二参数"[More Information Needed]"是缺省提示文本，第三参数true表示即使变量未定义（undefined）也触发默认值，而不是仅仅在值为空字符串/None 时兜底。这意味着调用ModelCard.from_template(card_data)而完全不传模板 kwargs 时，模板依然能渲染出结构完整、每处空缺标注 "More Information Needed" 的卡片。这一点在 tests/test_repocard.py 中test_repo_card_from_default_template等用例中被明确验证：card.text.strip().startswith("# Model Card for Model ID")，即默认模型名回退为模板标题中的Model ID。

模板变量总表

下表汇总了模板中全部可填写的 Jinja2 变量及其默认值，是逐节填写时的速查清单：

逐节拆解模板：结构、变量与填写指引

1. Model Card 标题与 Model Summary

模板以# Model Card for {{ model_id }}作为一级标题，model_id对应ModelCardData(model_name=...)或模板 kwargs 中的model_id。紧随其后的{{ model_summary }}用于一句话概括模型是做什么的（模板注释要求 "quick summary of what the model is/does"），通常是一段不超过两三行的简介，便于搜索引擎与 LLM 快速索引。

2. Model Details：基础信息与来源链接

Model Description（model_description）是模型的详细描述，模板注释要求给出比摘要更长的说明。随后是一组固定的信息项，每一项都以- **名称:**的 Markdown 列表形式出现：

• Developed by（developers）：开发主体；
• Funded by（funded_by，可选）：资助方；
• Shared by（shared_by，可选）：发布方；
• Model type（model_type）：模型类型，例如transformer、diffusion；
• Language(s) (NLP)（language）：训练数据或元数据所用语言，通常使用 ISO 639-1/639-2/639-3 代码，也支持code、multilingual等特殊值；
• License（license）：许可证标识，如apache-2.0、mit；
• Finetuned from model（base_model，可选）：微调所基于的基座模型在 Hub 上的 ID（多基座时可为列表）。

Model Sources（可选）提供三个链接位：Repository（repo）、Paper（paper）、Demo（demo）。

3. Uses：明确使用边界

该章节要求从三个角度回答"模型该不该、能不能这样用"：

• Direct Use（direct_use）：无需微调、不接入更大系统时的直接用途；
• Downstream Use（downstream_use，可选）：微调后或嵌入更大应用/生态时的用途；
• Out-of-Scope Use（out_of_scope_use）：明确不适用的场景，包括滥用、恶意用途和模型无法正常工作的情形。

4. Bias, Risks, and Limitations：偏见、风险与限制

bias_risks_limitations同时承载技术性与社会技术性限制的描述。其下的Recommendations（bias_recommendations）在模板中内置了一段默认建议文本，未填时渲染为：

Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.

这保证了即使作者未填写建议，读者也能看到规范化的风险提示。

5. How to Get Started with the Model

get_started_code用于放置模型的使用代码示例。模板正文固定渲染一句 "Use the code below to get started with the model."，下面由调用方注入可执行的 Python/推理代码块。

6. Training Details：训练数据与训练过程

• Training Data（training_data）：应尽量链接到对应的 Dataset Card，并简述数据内容、预处理与过滤方法；
• Training Procedure：
  • Preprocessing（preprocessing，可选）：数据预处理步骤；
  • Training Hyperparameters：模板内置一个信息项Training regime（training_regime），注释明确给出了推荐取值：fp32、fp16 mixed precision、bf16 mixed precision、bf16 non-mixed precision、fp16 non-mixed precision、fp8 mixed precision；
  • Speeds, Sizes, Times（speeds_sizes_times，可选）：吞吐量、训练起止时间、checkpoint 大小等。

7. Evaluation：评测协议与结果

• Testing Data, Factors & Metrics：
  • Testing Data（testing_data）：尽量链接 Dataset Card；
  • Factors（testing_factors）：评测按哪些子群体或领域进行细分（disaggregation）；
  • Metrics（testing_metrics）：所用指标及选择理由；
• Results（results）与Summary（results_summary）：评测结果正文与总结。

8. Model Examination（可选）

model_examination用于放置可解释性（interpretability）相关的工作。

9. Environmental Impact：环境足迹

模板要求用co2_emitted（单位：克 CO2e）报告碳排放，并建议用 Machine Learning Impact calculator（Lacoste et al., 2019，论文 arXiv:1910.09700）估算。需要填写的信息项包括：

• Hardware Type（hardware_type）：硬件型号；
• Hours used（hours_used）：使用时长；
• Cloud Provider（cloud_provider）：云服务商；
• Compute Region（cloud_region）：计算地域；
• Carbon Emitted（co2_emitted）：碳排放量。

10. Technical Specifications（可选）

• Model Architecture and Objective（model_specs）：架构与优化目标；
• Compute Infrastructure：
  • Hardware（hardware_requirements）：硬件要求；
  • Software（software）：软件/框架依赖。

11. Citation（可选）

提供BibTeX（citation_bibtex）与APA（citation_apa）两种格式的引用信息，供论文或博客读者引用模型。

12. Glossary / More Information / Authors / Contact（均可选）

• Glossary（glossary）：术语与计算口径说明；
• More Information（more_information）：补充信息；
• Model Card Authors（model_card_authors）：卡片作者；
• Model Card Contact（model_card_contact）：联系方式。

元数据头与card_data的序列化机制

模板第一行{{ card_data }}由CardData.to_yaml()的输出填充（repocard_data.py#L198-L220），其底层调用yaml_dump(self.to_dict(), sort_keys=False, ...)保留键的声明顺序，并对值为None的键自动过滤。ModelCardData的_to_dict（repocard_data.py#L393-L397）有一个重要转换：如果传入了eval_results与model_name，会在导出字典时把它们组装成model-index结构并删除原始键，这正是评价结果进入元数据的途径。

ModelCardData支持的常用构造参数（repocard_data.py#L271-L397）包括：base_model、datasets、eval_results、language、library_name、license（另有license_name/license_link组合用法）、metrics、model_name、pipeline_tag、tags以及任意额外的**kwargs（会原样进入元数据字典）。其中tags会被_to_unique_list去重保序。

在解析一侧，RepoCard.content的 setter（repocard.py#L85-L110）通过REGEX_YAML_BLOCK正则（与 Hub 服务端保持同步的 YAML 块匹配规则，repocard.py#L32-L34）切分元数据头与正文：匹配成功则用yaml.safe_load解析为字典并交给ModelCardData；若无元数据块则发出警告并以空元数据初始化。

从默认模板生成卡片并发布：完整工作流

以下代码演示了最典型的用法（与 docs/source/en/guides/model-cards.md 中的实践一致）：

from huggingface_hub import ModelCard, ModelCardData card_data = ModelCardData( language='en', license='mit', library_name='timm', tags=['image-classification', 'resnet'], datasets=['beans'], metrics=['accuracy'], ) card = ModelCard.from_template( card_data, model_id='my-cool-model', model_summary="A ResNet model fine-tuned on the beans dataset.", model_description="This model does x + y...", developers="Nate Raw", repo="https://github.com/huggingface/huggingface_hub", get_started_code="""```python from transformers import pipeline classifier = pipeline("image-classification", model="my-org/my-cool-model")

""", ) card.save('my_model_card.md')

`ModelCard.from_template` 的完整签名（[repocard.py#L341-L417](https://link.gitcode.com/i/cfc1457de15620f6250b3c2ea4527909#L341-L417)）允许通过 `template_path` 指定自定义模板文件，或通过 `template_str` 直接传入原始 Jinja2 字符串；其余 `**template_kwargs` 与 `card_data` 中的键合并后一起注入模板（模板 kwargs 优先级更高，见 [repocard.py#L324-L325](https://link.gitcode.com/i/cfc1457de15620f6250b3c2ea4527909#L324-L325)）。 生成后的卡片对象提供四个常用操作： - `card.data`：`ModelCardData` 实例，`.to_dict()` 得到元数据字典； - `card.text`：不含元数据头的正文； - `card.content`：含元数据头的完整内容； - `card.save(path)`（[repocard.py#L115-L133](https://link.gitcode.com/i/cfc1457de15620f6250b3c2ea4527909#L115-L133)）：写回本地文件并保留原换行风格，避免产生不必要的 diff。 修改 `card.data` 后，可以通过 `card.validate()`（[repocard.py#L189-L224](https://link.gitcode.com/i/cfc1457de15620f6250b3c2ea4527909#L189-L224)）调用 Hub 的 `/api/validate-yaml` 接口在线校验元数据合法性（400 响应会被转为 `ValueError`）。最后登录后推送： ```python card.push_to_hub(repo_id) # 直接提交 card.push_to_hub(repo_id, create_pr=True) # 以 Pull Request 形式提交

push_to_hub（repocard.py#L226-L287）会先自动validate()，再在临时目录写入README.md并通过upload_file提交，支持commit_message、commit_description、revision、create_pr、parent_commit等完整提交参数，返回提交 URL。

进阶一：把评测结果写入model-index

要在元数据中携带评测结果，只需在ModelCardData中传入model_name与一个或多个EvalResult（注意：传eval_results必须同时设置model_name，否则校验会抛ValueError，见 repocard_data.py#L254-L268）：

from huggingface_hub import ModelCard, ModelCardData, EvalResult card_data = ModelCardData( language='en', license='mit', model_name='my-cool-model', eval_results=[ EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='accuracy', metric_value=0.7, ), EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='f1', metric_value=0.65, dataset_config='default', dataset_split='test', dataset_revision='5503434ddd753f426f4b38109466949a1217c2bb', ), ], ) card = ModelCard.from_template(card_data)

EvalResult（repocard_data.py#L12-L162）的必填字段是task_type、dataset_type、dataset_name、metric_type、metric_value；可选字段包括task_name、dataset_config、dataset_split、dataset_revision、dataset_args、metric_name、metric_config、metric_args、verified、verify_token、source_name、source_url等。渲染时ModelCardData._to_dict会调用eval_results_to_model_index（repocard_data.py#L681-L770）按 "task + dataset 唯一标识" 分组生成规范model-index；反向解析则由model_index_to_eval_results完成（repocard_data.py#L561-L666）。

生成的元数据形如（可对照测试夹具 tests/fixtures/cards/sample_simple_model_index.md）：

language: en license: mit model-index: - name: my-cool-model results: - task: type: image-classification dataset: name: Beans type: beans metrics: - type: accuracy value: 0.7 - type: f1 value: 0.65

进阶二：用metadata_update原地维护卡片元数据

当 README.md 已存在时，可以不重建整张卡片，而用metadata_update（repocard.py#L688-L835）增量更新：

from huggingface_hub import metadata_update # 新增 pipeline_tag（README 不存在时会用默认模板创建新卡片） metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"}) # 覆盖已存在的字段必须显式 overwrite=True metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True) # 无写权限时以 PR 形式提交建议 metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)

该函数内部按repo_type选择ModelCard/DatasetCard/RepoCard，先尝试从 Hub 加载已有卡片（EntryNotFoundError时从默认模板新建空卡片，Space 无 README 时会抛错），随后对model-index与普通字段分别执行合并逻辑：相同评测指标的数值冲突在未设overwrite=True时会抛ValueError，其余新结果则追加进已有列表。

自定义模板：何时使用、如何接入

默认模板适合追求规范完整性的场景，但当你需要高度定制（例如精简卡片、融合组织风格）时，from_template提供了两条自定义路径。测试夹具 tests/fixtures/cards/sample_template.md 给出了一个最小示例：

--- {{card_data}} --- # {{ model_name | default("MyModelName", true)}} {{ some_data }}

传入方式对应ModelCard.from_template的两个参数（repocard.py#L405-L413）：

# 方式一：模板文件路径 card = ModelCard.from_template( card_data=card_data, template_path='./my_templates/modelcard.md', some_data='自定义内容', ) # 方式二：原始模板字符串（template_path 优先，同时提供时忽略 template_str） card = ModelCard.from_template( card_data=card_data, template_str="---\n{{ card_data }}\n---\n\n# {{ model_name }}\n\n{{ some_data }}", )

自定义模板同样是 Jinja2 语法，未定义的变量通过default(...)过滤器给出兜底。注意使用from_template的前提是环境安装了Jinja2，否则会抛出ImportError（repocard.py#L316-L322），可通过pip install Jinja2安装。

结语

modelcard_template.md并非一段普通 Markdown，而是一份经过严格设计的、可编程的卡片生成骨架：YAML 元数据头保证机器可读与可检索，约 20 个章节覆盖了从模型细节、使用边界、风险提示到训练评测、环境影响与引用的完整信息链，default过滤器机制则让卡片在信息不全时依然结构自洽。配合ModelCard.from_template、EvalResult/model-index与push_to_hub，你可以在几分钟内产出一份符合 Hugging Face Hub 规范的专业 Model Card——这正是开源社区高质量模型文档背后的"工业化底座"。

• 开发工具
• CLI
• 机器学习