开发工具CLI机器学习【免费下载链接】huggingface_hubThe official CLI and Python client for the Hugging Face Hub.项目地址https://gitcode.com/gh_mirrors/hu/huggingface_hub点击查看免费下载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-L30TEMPLATE_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.mdHub 会解析其 YAML 头部作为结构化元数据并渲染 Markdown 正文作为模型的主页展示。从类继承关系看ModelCard继承自RepoCardrepocard.py#L336-L339其card_data_class为ModelCardData、default_template_path即上述模型模板、repo_type为model。模板的核心渲染逻辑集中在基类RepoCard.from_templaterepocard.py#L289-L333它会将card_data序列化为 YAML 字符串、加载 Jinja2 模板并填充所有变量最终构造出一个完整的RepoCard实例。模板的总体结构YAML 元数据头 Markdown 正文整个模板由两大部分组成YAML front matter元数据头以---包裹的{{ card_data }}占位符由ModelCardData序列化后的 YAML 填充。Hub 依靠这部分做结构化解析、搜索过滤与排行榜接入。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 变量及其默认值是逐节填写时的速查清单所属章节变量默认值未提供时标题model_idModel ID摘要model_summary空字符串Model Detailsmodel_description空字符串Model Details 信息项developers/funded_by/shared_by/model_type/language/license/base_model[More Information Needed]Model Sourcesrepo/paper/demo[More Information Needed]Usesdirect_use/downstream_use/out_of_scope_use[More Information Needed]Bias/Risks/Limitationsbias_risks_limitations/bias_recommendations[More Information Needed]后者另有内置建议文本How to Get Startedget_started_code[More Information Needed]Training Detailstraining_data/preprocessing/training_regime/speeds_sizes_times[More Information Needed]Evaluationtesting_data/testing_factors/testing_metrics/results/results_summary[More Information Needed]results_summary为空串Model Examinationmodel_examination[More Information Needed]Environmental Impacthardware_type/hours_used/cloud_provider/cloud_region/co2_emitted[More Information Needed]Technical Specificationsmodel_specs/compute_infrastructure/hardware_requirements/software[More Information Needed]Citationcitation_bibtex/citation_apa[More Information Needed]收尾章节glossary/more_information/model_card_authors/model_card_contact[More Information Needed]逐节拆解模板结构、变量与填写指引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 Descriptionmodel_description是模型的详细描述模板注释要求给出比摘要更长的说明。随后是一组固定的信息项每一项都以- **名称:**的 Markdown 列表形式出现Developed bydevelopers开发主体Funded byfunded_by可选资助方Shared byshared_by可选发布方Model typemodel_type模型类型例如transformer、diffusionLanguage(s) (NLP)language训练数据或元数据所用语言通常使用 ISO 639-1/639-2/639-3 代码也支持code、multilingual等特殊值Licenselicense许可证标识如apache-2.0、mitFinetuned from modelbase_model可选微调所基于的基座模型在 Hub 上的 ID多基座时可为列表。Model Sources可选提供三个链接位Repositoryrepo、Paperpaper、Demodemo。3. Uses明确使用边界该章节要求从三个角度回答模型该不该、能不能这样用Direct Usedirect_use无需微调、不接入更大系统时的直接用途Downstream Usedownstream_use可选微调后或嵌入更大应用/生态时的用途Out-of-Scope Useout_of_scope_use明确不适用的场景包括滥用、恶意用途和模型无法正常工作的情形。4. Bias, Risks, and Limitations偏见、风险与限制bias_risks_limitations同时承载技术性与社会技术性限制的描述。其下的Recommendationsbias_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 Modelget_started_code用于放置模型的使用代码示例。模板正文固定渲染一句 Use the code below to get started with the model.下面由调用方注入可执行的 Python/推理代码块。6. Training Details训练数据与训练过程Training Datatraining_data应尽量链接到对应的 Dataset Card并简述数据内容、预处理与过滤方法Training ProcedurePreprocessingpreprocessing可选数据预处理步骤Training Hyperparameters模板内置一个信息项Training regimetraining_regime注释明确给出了推荐取值fp32、fp16 mixed precision、bf16 mixed precision、bf16 non-mixed precision、fp16 non-mixed precision、fp8 mixed precisionSpeeds, Sizes, Timesspeeds_sizes_times可选吞吐量、训练起止时间、checkpoint 大小等。7. Evaluation评测协议与结果Testing Data, Factors MetricsTesting Datatesting_data尽量链接 Dataset CardFactorstesting_factors评测按哪些子群体或领域进行细分disaggregationMetricstesting_metrics所用指标及选择理由Resultsresults与Summaryresults_summary评测结果正文与总结。8. Model Examination可选model_examination用于放置可解释性interpretability相关的工作。9. Environmental Impact环境足迹模板要求用co2_emitted单位克 CO2e报告碳排放并建议用 Machine Learning Impact calculatorLacoste et al., 2019论文 arXiv:1910.09700估算。需要填写的信息项包括Hardware Typehardware_type硬件型号Hours usedhours_used使用时长Cloud Providercloud_provider云服务商Compute Regioncloud_region计算地域Carbon Emittedco2_emitted碳排放量。10. Technical Specifications可选Model Architecture and Objectivemodel_specs架构与优化目标Compute InfrastructureHardwarehardware_requirements硬件要求Softwaresoftware软件/框架依赖。11. Citation可选提供BibTeXcitation_bibtex与APAcitation_apa两种格式的引用信息供论文或博客读者引用模型。12. Glossary / More Information / Authors / Contact均可选Glossaryglossary术语与计算口径说明More Informationmore_information补充信息Model Card Authorsmodel_card_authors卡片作者Model Card Contactmodel_card_contact联系方式。元数据头与card_data的序列化机制模板第一行{{ card_data }}由CardData.to_yaml()的输出填充repocard_data.py#L198-L220其底层调用yaml_dump(self.to_dict(), sort_keysFalse, ...)保留键的声明顺序并对值为None的键自动过滤。ModelCardData的_to_dictrepocard_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的 setterrepocard.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( languageen, licensemit, library_nametimm, tags[image-classification, resnet], datasets[beans], metrics[accuracy], ) card ModelCard.from_template( card_data, model_idmy-cool-model, model_summaryA ResNet model fine-tuned on the beans dataset., model_descriptionThis model does x y..., developersNate Raw, repohttps://github.com/huggingface/huggingface_hub, get_started_codepython from transformers import pipeline classifier pipeline(image-classification, modelmy-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.dataModelCardData 实例.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_prTrue) # 以 Pull Request 形式提交push_to_hubrepocard.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-L268from huggingface_hub import ModelCard, ModelCardData, EvalResult card_data ModelCardData( languageen, licensemit, model_namemy-cool-model, eval_results[ EvalResult( task_typeimage-classification, dataset_typebeans, dataset_nameBeans, metric_typeaccuracy, metric_value0.7, ), EvalResult( task_typeimage-classification, dataset_typebeans, dataset_nameBeans, metric_typef1, metric_value0.65, dataset_configdefault, dataset_splittest, dataset_revision5503434ddd753f426f4b38109466949a1217c2bb, ), ], ) card ModelCard.from_template(card_data)EvalResultrepocard_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_indexrepocard_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.mdlanguage: 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_updaterepocard.py#L688-L835增量更新from huggingface_hub import metadata_update # 新增 pipeline_tagREADME 不存在时会用默认模板创建新卡片 metadata_update(username/my-cool-model, {pipeline_tag: image-classification}) # 覆盖已存在的字段必须显式 overwriteTrue metadata_update(username/my-cool-model, {pipeline_tag: text-generation}, overwriteTrue) # 无写权限时以 PR 形式提交建议 metadata_update(someone/model, {pipeline_tag: text-classification}, create_prTrue)该函数内部按repo_type选择ModelCard/DatasetCard/RepoCard先尝试从 Hub 加载已有卡片EntryNotFoundError时从默认模板新建空卡片Space 无 README 时会抛错随后对model-index与普通字段分别执行合并逻辑相同评测指标的数值冲突在未设overwriteTrue时会抛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_datacard_data, template_path./my_templates/modelcard.md, some_data自定义内容, ) # 方式二原始模板字符串template_path 优先同时提供时忽略 template_str card ModelCard.from_template( card_datacard_data, template_str---\n{{ card_data }}\n---\n\n# {{ model_name }}\n\n{{ some_data }}, )自定义模板同样是 Jinja2 语法未定义的变量通过default(...)过滤器给出兜底。注意使用from_template的前提是环境安装了Jinja2否则会抛出ImportErrorrepocard.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机器学习【免费下载链接】huggingface_hubThe official CLI and Python client for the Hugging Face Hub.项目地址https://gitcode.com/gh_mirrors/hu/huggingface_hub点击查看免费下载相关推荐终极指南Qt-Material样式表模板如何从Jinja2模板渲染为惊艳界面终极指南Qt Material样式表模板如何从Jinja2模板渲染为惊艳界面 Qt Material是一个为PySide2、PySide6、PyQt5和PyQUI组件桌面应用深入解析 Cookiecutter 自定义 Jinja2 模板扩展从 hello 标签到钩子渲染全链路实战深入解析 Cookiecutter 自定义 Jinja2 模板扩展从 hello 标签到钩子渲染全链路实战 导读 本文围绕 Cookiecutter 测试夹具开发工具CLI代码生成Visdom深度解析从实时数据可视化到机器学习实验管理的实战指南Visdom深度解析从实时数据可视化到机器学习实验管理的实战指南 在机器学习和深度学习的研究与开发中数据可视化是理解模型行为、监控训练过程、分析实验结果的关数据可视化前端上一篇Cataclysm-DDA模组开发终极指南info.json规范与依赖管理详解下一篇Emoji Mart代码分割策略终极指南如何智能加载表情选择器功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考