正在从事模型托管工作的开发者，大概率都遇到过这类尴尬场景：好不容易把模型文件上传完毕，结果仓库首页仅显示一个孤零零的文件列表，既没有说明模型用途、使用限制，也没有提及数据来源和许可信息；又或者模型卡虽然能打开，但任务、支持库等标签一个都没出现。遇到这种情况，完全不必慌张，先检查 README.md 顶部的 metadata，再仔细阅读模型卡正文即可——这两个区域分别负责「机器如何识别模型」和「读者能否判断模型是否适用」。
Hugging Face Hub 会自动将模型仓库根目录下的 README.md 渲染成大家看到的 Model card（模型卡）。文件正文使用 Markdown 编写即可，最顶部还可以放置一段 YAML 格式的 metadata。正文的作用是清晰说明模型本身、应用场景、限制与偏差、训练信息、所用数据集和评测结果；而 metadata 则负责检索、筛选、标签展示、模型关系、页面组件以及部分 API 的运行逻辑。
先看发布后的模型卡应该是什么样
随便打开一个公开的模型仓库，默认显示的 Model card 标签页，就是 README.md 渲染出来的效果。页面顶部的任务、支持库、文件格式、相关论文、许可协议等标签，大多来自 metadata 或者 Hub 自动识别的结果；右侧还会根据仓库里的文件和 metadata，展示模型大小、张量类型等信息。
- 入口：目标模型仓库的 Model card 页面。动作：先记录顶部现有的标签，再向下滑动检查用途、限制、训练数据和评测说明是否完整。成功标志：页面有通顺可读的正文，任务、许可等标签与模型实际情况相符。失败处理：如果 Model card 一片空白，就切换到 Files and versions 页面，检查根目录下是否存在
README.md；如果标签不对，优先检查README.md顶部的 YAML 配置。
从 Files and versions 找到 README.md
点击仓库导航栏中的 Files and versions。模型卡的源文件必须命名为 README.md，并且必须放置在模型仓库的根目录下。如果缺少这个文件，自己的仓库可以直接新建 README.md；如果使用 Git 操作，也可以在本地仓库根目录创建好后再推送到远端。
- 入口：模型仓库顶部的 Files and versions 页面。动作：在根目录中找到
README.md，同时确认旁边的提交记录是否为你预期的版本。成功标志：文件列表中能看到README.md，点击进入后可以看到 Preview 和 Code 两个选项卡。失败处理：如果README.md放在子目录中，就移动到仓库根目录；如果没有写权限，不要直接修改别人的仓库，使用 Contribute 功能发起变更，或者联系仓库所有者。 - 入口：自己仓库的文件操作区，或者本地的 Git 工作目录。动作：新建一个
README.md，先编写顶部的 YAML 配置，再撰写模型说明的正文内容。成功标志：保存或推送后能看到新的提交记录，Model card 标签页开始正常渲染内容。失败处理：如果网页要求登录，先登录账号；如果本地推送被拒绝，检查仓库地址、访问令牌和写权限是否正确，不要反复强制覆盖远端分支。
网页端选 Metadata UI 还是直接改 YAML
在自己的模型页面，点击模型卡右上角的 Edit model card，编辑器会同时显示 README.md 正文编辑区和 Metadata UI 配置面板。这个 UI 能自动补全常用取值，还能校验部分字段，初次配置时非常方便；如果遇到 UI 未覆盖的字段，再切换到源码模式直接编辑 YAML 即可。
查看别人的公开仓库时，README 页面会显示 Contribute 按钮，这个入口用于提交协作变更，不代表你获得了仓库的写权限。下图中的 Preview、Code、Raw、History 和 Contribute 都在同一条工具栏上，metadata 的解析结果则单独显示在正文的上方。
- 入口：自己的 Model card 页面右上角的 Edit model card 按钮。动作：先在 Metadata UI 中填写语言、许可、任务、支持库和数据集等信息，再检查一遍 README 正文。成功标志：所有字段都能正常选择或自动补全，保存后返回模型页，能看到对应的标签显示出来。失败处理：如果某个字段在 UI 中找不到，不要强行塞入 tags 中，切换到 YAML 模式按照官方的字段名来填写。
- 入口：
README.md文件页的 Code 选项卡或 Contribute 按钮。动作：查看源码，如有需要修改后再提交。成功标志：自己的仓库会生成一条新的提交记录；别人的仓库会生成一个可审阅的 Pull Request。失败处理：如果跳出登录页面，说明当前会话未登录；如果提示权限拒绝，说明不能直接写入，记得先保存好改动内容，改用协作流程提交。
把 YAML 放在文件最顶部
metadata 必须从 README.md 的第一行开始编写，使用三条短横线（---）作为开头和结尾的标记。结束分隔线写完之后，再编写模型卡的正文内容。列表项要使用统一的缩进，字段名后面留一个空格，仓库 ID 要写成「所属账号/组织名 + 仓库名」的格式。
---
language:
- zh
- en
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
datasets:
- my-org/my-dataset
base_model: my-org/base-model
tags:
- instruction-tuned
---
# 模型名称
这里开始写用途、限制、训练信息和评测结果。在真实仓库的 Code 视图中，能直接看到这组边界标记：第一行是三横线，license、pipeline_tag、library_name 和 tags 等字段都在结束分隔线的前面。Preview 只展示解析好的 metadata，要排查缩进、拼写、分隔线等问题，需要使用 Code 视图才方便。
- 入口：
README.md的 Code 视图，或者本地的文本编辑器。动作：将 YAML 内容移到文件第一行，并用成对的三横线包裹起来。成功标志：Preview 页面的顶部会出现独立的 metadata 区块，正文中不再把字段当成普通文字显示。失败处理：如果 metadata 原样出现在正文中，先检查第一行前面是否有空格、空行或不可见字符，再检查结束的分隔线是否漏写。 - 入口：页面的保存按钮，或者本地的 Git 提交流程。动作：提交修改后的
README.md，然后等待模型页面重新渲染。成功标志：Model card 能正常打开，顶部的标签与 YAML 中的配置一一对应。失败处理：如果渲染失败，先回滚到上一条能用的提交，再逐个添加字段；一次只改一组字段，方便定位问题。
核心字段怎样填才不误导
library_name 与 pipeline_tag
library_name 要填写实际能加载这个模型的库名。官方文档建议用户主动显式填写；2024 年 8 月之后创建的仓库，仅凭 config.json 已经不能保证 Hub 会默认将其识别为 transformers 库的模型。pipeline_tag 填写模型的主要任务，例如文本生成。这个字段会影响任务标签、模型筛选、页面组件以及部分底层 API 的行为，因此不要同时填入多个互相冲突的主任务。
入口：Metadata UI 中的库和任务字段，或者 README 中的 YAML 配置。动作：选择真实支持的库，并且只填写一个主任务。成功标志：模型页顶部出现对应的库和任务标签，页面的组件与任务类型匹配。失败处理：如果任务值无效，优先在 Metadata UI 中重新选择；如果自动推断的结果不符合模型用途，就用 YAML 中的 pipeline_tag 明确覆盖自动识别结果。
license、datasets 与 language
license 要使用有效的许可标识，同时确保仓库中的 LICENSE 文件与页面上的说明一致。如果是自定义许可，就填写 other，并补充许可名称和许可说明的位置。datasets 填写 Hub 上真实存在的数据集仓库 ID，language 使用标准的语言标识列表。这些字段填写正确后，模型页会展示许可信息，并将训练数据链接到对应的数据集页面。
入口：Metadata UI，或者 YAML 中的 license、datasets、language 字段。动作：逐项填写可核验的标识。成功标志：许可标签显示正确，数据集名称能被 Hub 识别，使用语言筛选也能搜索到这个模型。失败处理：如果数据集未被识别，核对账号/组织名、仓库名以及大小写是否正确；如果许可不在常用列表中，使用官方支持的自定义许可结构，不要自己编造 license 的值。
base_model 与模型关系
如果是微调模型、适配器、量化模型或合并模型，都应该填写 base_model 字段。只有一个上游来源时就填写一个 Hub 模型 ID，合并模型可以填写多个 ID；Hub 通常会自动推断出 finetune、adapter、quantized 或 merge 等关系，如果担心推断错误，也可以使用 base_model_relation 明确指定关系类型。
入口：README 的 YAML 配置中的 base_model 字段。动作：填写真实的上游模型 ID，如果觉得关系可能被误判，就补充 base_model_relation 字段。成功标志：模型页会出现 Model tree（模型树），在上游模型的衍生列表中也能找到当前模型。失败处理：如果模型树未出现，检查上游 ID 是否完整、是否将多个 ID 错误写在同一行，以及 relation 的值与模型实际类型是否一致。
正文不能只剩一串标签
metadata 解决机器识别的问题，正文仍然需要回答读者关心的判断问题。至少需要写清楚模型能做什么、适合和不适合用在哪些场景、有哪些已知的限制和偏差、训练参数或实验条件是什么、使用了什么数据集、评测方法和结果如何。涉及数值时，一定要附带对应的任务、数据集、指标和测试条件，不要只写一句「效果很好」就了事。
入口：README.md 中，YAML 结束分隔线之后的正文区域。动作：按照读者做决策的顺序，补充用途、限制、训练细节、数据集和评测等内容。成功标志：完全不了解这个项目的人，仅看模型卡就能判断这个模型是否适合下载、部署或继续评估。失败处理：如果资料不全，就明确标注哪些实验条件尚未提供，不要靠推测瞎填；涉及安全、偏差或使用边界的内容，一定要将限制放在显眼位置。
保存后按这条路线排错
- 入口：Model card 页面顶部的标签。动作：对照检查
language、license、library_name、pipeline_tag、datasets和base_model这几个字段。成功标志：所有标签和模型关系，都与 YAML 中的配置一致。失败处理：缺少哪个标签，就回到 Code 视图只检查对应的字段即可，不要一上来就把整份 README 全部重写。 - 入口：README Preview 页面的 metadata 区块。动作：确认所有字段都被正确解析，没有混入正文中。成功标志：metadata 单独显示在一块区域，正文从模型标题和说明部分开始。失败处理：如果字段跑到正文中，检查首行格式、成对的分隔线、缩进、冒号以及列表的短横线是否正确。
- 入口：Files and versions 页面的 History 选项，或者本地的 Git 日志。动作：对比出错前后的几次 README 提交记录。成功标志：能够定位到是哪个最小的改动引入了问题。失败处理：实在查不出来的话，先恢复到上一条能用的提交，再一小步一小步地添加字段，每次添加后都查看模型页的渲染情况。
模型卡完成核对
README.md放在模型仓库的根目录下，Model card 能正常渲染。- YAML 配置从文件第一行开始，并且由成对的三横线包裹。
library_name、pipeline_tag、license、datasets、language这些字段，都与模型的实际情况一致。- 微调、适配器、量化或合并类的模型，已经填写了
base_model，关系也没有标错。 - 正文中包含了用途、限制、训练信息、数据集、评测方法和结果等内容。
- 保存之后，已经检查过顶部标签、Preview 的 metadata、Model tree 和提交记录。
- 没有写权限时，使用 Contribute 或 Pull Request 提交变更，没有尝试绕过仓库权限。
