TRL 模型卡模板全解析lm_model_card.md 如何为训练后的模型自动生成 README【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl本文以 TRL 仓库中的模型卡模板 lm_model_card.md 为主体完整解析这份 Jinja2 模板的结构、全部占位变量及其渲染规则并结合 BaseTrainer.create_model_card 与 generate_model_card 的源码实现说明 TRL 是如何在一次训练结束后自动为产出的模型生成带 Quick start 示例、框架版本清单与 BibTeX 引用的 Model Card即 Hub 仓库 README的。读完后你可以理解模板中每个{{ 变量 }}的取值来源与条件渲染逻辑并知道如何按需调用generate_model_card或替换模板文件来自定义模型卡内容。模板的定位与整体结构TRL 在训练结束时自动为模型仓库生成一份 Model Card 草稿。这份卡片以 Markdown 模板为骨架存放于trl/templates/目录除 lm_model_card.md 外同级还有两个姊妹模板rm_model_card.md用于奖励模型RewardTrainer 中通过_template_file rm_model_card.md显式指定见 reward_trainer.pycompletions_dataset_card.md用于 GRPO 等算法训练过程中落盘的 completions 数据集卡片记录step、prompt、completion、各奖励函数得分与advantage等列并给出用datasets和 Polars 加载 parquet 的示例。lm_model_card.md 本身是一份标准 Jinja2 模板全文如下可直接在仓库中查看原文--- {{ card_data }} --- # Model Card for {{ model_name }} This model is a fine-tuned version of [{{ base_model }}](https://huggingface.co/{{ base_model }}){% if dataset_name %} on the [{{ dataset_name }}](https://huggingface.co/datasets/{{ dataset_name }}) dataset{% endif %}. It has been trained using [TRL](https://github.com/huggingface/trl). ## Quick start python from transformers import pipeline question If you had a time machine, but could only go to the past or the future once and never return, which would you choose and why? generator pipeline(text-generation, model{{ hub_model_id }}, device_mapauto) output generator([{role: user, content: question}], max_new_tokens128, return_full_textFalse)[0] print(output[generated_text])Training procedure{% if wandb_url %}...Weights Biases 徽标链接...{% endif %} {% if trackio_url %}...Trackio Space 徽标链接...{% endif %} {% if comet_url %}...Comet 实验徽标链接...{% endif %}This model was trained with {{ trainer_name }}{% if paper_id %}, a method introduced in {{ paper_title }}{% endif %}.Framework versionsTRL: {{ trl_version }}Transformers: {{ transformers_version }}Pytorch: {{ pytorch_version }}Datasets: {{ datasets_version }}Tokenizers: {{ tokenizers_version }}Citations{% if trainer_citation %}Cite {{ trainer_name }} as:{{ trainer_citation }} {% endif %} Cite TRL as: bibtex software{vonwerra2020trl, ...}从结构上看模板由五个部分组成YAML 前置元数据{{ card_data }}、模型概述、Quick start 推理示例、Training procedure含实验追踪徽标、训练方法与框架版本清单、以及 Citations 引用段。其中三处使用 {% if %} 条件渲染dataset_name、各追踪平台 URL、trainer_citation/paper_id——也就是说未提供的可选信息会自动从最终卡片中消失而不会留下空占位符。 ## 模板变量清单与取值来源 模板中出现的变量分为两类由调用方传入的“身份信息”和由渲染函数自动收集的“环境信息”。结合 [generate_model_card](https://link.gitcode.com/i/554eb9859e2cda62ad4eaf1df9e8898e) 的签名全部变量如下表 | 变量 | 类型/可空 | 说明 | | --- | --- | --- | | card_data | 自动构造 | 序列化的 ModelCardData 对象渲染为 YAML front matter | | model_name | 必填 | 训练产出模型的名称即卡片标题 | | base_model | 可空 | 底模 Hub ID渲染为指向模型页的链接 | | dataset_name | 可空 | 训练数据集 Hub ID触发 {% if dataset_name %} 分支 | | hub_model_id | 必填 | username/model_id 形式的 Hub 模型 ID注入 Quick start 代码 | | trainer_name | 必填 | 训练器名称如 DPO、GRPO取自 Trainer 类的 _name | | trainer_citation | 可空 | 该训练方法对应的 BibTeX 条目取自 Trainer 类 _paper[citation] | | paper_title / paper_id | 可空 | 方法论文标题与 ArXiv IDYYMM.NNNNN 格式渲染为论文链接 | | wandb_url / trackio_url / comet_url | 可空 | 对应实验追踪平台徽标三者独立开关 | | trl_version 等 5 个版本变量 | 自动收集 | 训练环境中 TRL、Transformers、PyTorch、Datasets、Tokenizers 的实际版本 | card_data 的构造细节值得注意在 [utils.py](https://link.gitcode.com/i/ae8a4506c9e0f650b583cd493dc7407d) 中ModelCardData 固定写入 library_nametransformers、licencelicensetags 以 generated_from_trainer 开头再拼上调用方传入的 tags。这个标签是 Hub 识别“该模型由训练器自动产出”的依据。 渲染路径方面模板文件通过包内相对路径定位 python template_pathstr(pkg_resources.files(trl).joinpath(ftemplates/{template_file}))也就是说模板必须位于安装后的trl包内templates/子目录template_file参数只传文件名不传时默认回落到lm_model_card.md。自动版本采集与渲染流程generate_model_card 的核心动作是调用 huggingface_hub 的ModelCard.from_template一次性把上述变量注入模板。其中五个版本变量并非来自参数而是在调用处直接通过version(trl)、version(transformers)、version(torch)、version(datasets)、version(tokenizers)从当前训练进程的环境中实时读取见 utils.py。这保证了 Framework versions 一节记录的是“真实产生这份权重的环境”而不是模板里写死的值。测试用例 TestGenerateModelCard 对渲染结果做了双向断言test_full所有参数齐备时断言卡片文本中同时出现底模链接、pipeline(text-generation, modelusername/my_hub_model, device_mapauto)示例代码、datasets: username/my_datasetfront matter 字段、三个平台徽标 URL、trainer_name、BibTeX 块以及My Paper论文链接test_val_nonebase_model、dataset_name与各 URL 全部为None时断言卡片仍能正常渲染出模型名与 Quick start 代码验证了{% if %}分支对空值的安全降级。这两组测试基本覆盖了模板的条件渲染边界也可以作为你自己调用generate_model_card时的行为参照。Trainer 侧的调用链create_model_card模板最终由训练器在训练收尾时触发。调用链为Trainer 子类定义 _name / _paper / _template_file→ BaseTrainer.create_model_card → generate_model_card → 写入 output_dir/README.md。BaseTrainer.create_model_card 在生成前做了四件准备工作只在主进程执行if not self.is_world_process_zero(): return分布式训练下避免多进程重复写卡片推断底模通过get_config_model_id(self.model.config)从模型 config 中提取原始 Hub ID只有当它是一个真实的 Hub ID而非本地目录时才作为base_model传入模板否则置None——这解释了为什么从本地 checkpoint 继续训练时卡片里不出现底模链接自动聚合 tags归一化调用方传入的tags并自动追加三类标签——检测到 Unsloth 时加unsloth、环境变量存在JOB_ID时加hf_jobs、以及合并self._tag_names。若 Trackio 处于活动状态还会把带 URL 参数的trackio:space_url标签注入 tags使 Hub 页面可直接跳转到对应 Space收集实验 URLwandb_url直接取wandb.run.url当 wandb 可用且有活跃 run 时trackio_url由 get_trackio_space_url 从当前 run 的_space_id拼出comet_url由 get_comet_experiment_url 取运行中实验的url属性。三个平台均“可用且有活跃实验”时才出徽标与模板中的条件渲染一一对应。每个 Trainer 子类通过三个类属性声明自己的卡片元数据。以 DPOTrainer 为例_name DPO _paper { title: Direct Preference Optimization: Your Language Model is Secretly a Reward Model, id: 2305.18290, citation: textwrap.dedent(\ inproceedings{rafailov2023direct, ...}), }create_model_card随后把self._name、self._paper.get(citation)、self._paper.get(title)、self._paper.get(id)分别填入trainer_name、trainer_citation、paper_title、paper_id最后执行model_card.save(os.path.join(self.args.output_dir, README.md))即模型卡直接落盘为输出目录下的README.md配合push_to_hub后成为 Hub 模型页面的正文。GRPOTrainer、DistillationTrainer 等均以同样方式定义_name与_paper。而_template_file的机制则让不同训练器可以复用create_model_card但换用不同模板BaseTrainer默认_template_file None落到lm_model_card.mdRewardTrainer 覆写为rm_model_card.md从而在 Quick start 中给出适合奖励模型的用法示例。实践要点手动生成卡片不经过 Trainer 时可直接调用generate_model_card(base_model..., model_name..., hub_model_id..., dataset_name..., tags..., wandb_url..., trackio_url..., comet_url..., trainer_name..., trainer_citation..., template_file..., paper_title..., paper_id...)返回值是 huggingface_hub 的ModelCard对象可用.save(README.md)落盘。可选参数缺省为None时对应段落自动省略见 test_val_none 的行为。自定义模板向template_file传入trl/templates/下的其他文件名即可切换卡片版式如奖励模型场景前提是该文件已存在于包内模板目录。Quick start 段的可读性模板中的示例固定使用text-generationpipeline 与 chat 格式输入、max_new_tokens128它面向聊天式微调模型如果你的模型是纯文本续写或 VLM可复制模板后修改该代码段。引用段trainer_citation非空时卡片会先给出训练方法的 BibTeX随后无条件附上 TRL 的software{vonwerra2020trl, ...}条目两者均为模板内置行为。小结lm_model_card.md 是 TRL “训练即可发布”流程的最后一公里它用 Jinja2 条件渲染把底模/数据集链接、可运行的 Quick start 代码、实验追踪徽标、训练方法出处论文链接 BibTeX与训练环境五个核心库的实测版本组织成一份可直接成为 Hub README 的模型卡而 BaseTrainer.create_model_card 与 generate_model_card 负责在主进程安全地采集这些信息并完成渲染落盘。理解了这套模板变量契约与调用链你就能在查看任何 TRL 训练产物的 README 时准确判断其中每个字段的数据来源也能按 tests/test_utils.py 给出的方式验证自定义模板的渲染结果。【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TRL 模型卡模板全解析：lm_model_card.md 如何为训练后的模型自动生成 README
TRL 模型卡模板全解析lm_model_card.md 如何为训练后的模型自动生成 README【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl本文以 TRL 仓库中的模型卡模板 lm_model_card.md 为主体完整解析这份 Jinja2 模板的结构、全部占位变量及其渲染规则并结合 BaseTrainer.create_model_card 与 generate_model_card 的源码实现说明 TRL 是如何在一次训练结束后自动为产出的模型生成带 Quick start 示例、框架版本清单与 BibTeX 引用的 Model Card即 Hub 仓库 README的。读完后你可以理解模板中每个{{ 变量 }}的取值来源与条件渲染逻辑并知道如何按需调用generate_model_card或替换模板文件来自定义模型卡内容。模板的定位与整体结构TRL 在训练结束时自动为模型仓库生成一份 Model Card 草稿。这份卡片以 Markdown 模板为骨架存放于trl/templates/目录除 lm_model_card.md 外同级还有两个姊妹模板rm_model_card.md用于奖励模型RewardTrainer 中通过_template_file rm_model_card.md显式指定见 reward_trainer.pycompletions_dataset_card.md用于 GRPO 等算法训练过程中落盘的 completions 数据集卡片记录step、prompt、completion、各奖励函数得分与advantage等列并给出用datasets和 Polars 加载 parquet 的示例。lm_model_card.md 本身是一份标准 Jinja2 模板全文如下可直接在仓库中查看原文--- {{ card_data }} --- # Model Card for {{ model_name }} This model is a fine-tuned version of [{{ base_model }}](https://huggingface.co/{{ base_model }}){% if dataset_name %} on the [{{ dataset_name }}](https://huggingface.co/datasets/{{ dataset_name }}) dataset{% endif %}. It has been trained using [TRL](https://github.com/huggingface/trl). ## Quick start python from transformers import pipeline question If you had a time machine, but could only go to the past or the future once and never return, which would you choose and why? generator pipeline(text-generation, model{{ hub_model_id }}, device_mapauto) output generator([{role: user, content: question}], max_new_tokens128, return_full_textFalse)[0] print(output[generated_text])Training procedure{% if wandb_url %}...Weights Biases 徽标链接...{% endif %} {% if trackio_url %}...Trackio Space 徽标链接...{% endif %} {% if comet_url %}...Comet 实验徽标链接...{% endif %}This model was trained with {{ trainer_name }}{% if paper_id %}, a method introduced in {{ paper_title }}{% endif %}.Framework versionsTRL: {{ trl_version }}Transformers: {{ transformers_version }}Pytorch: {{ pytorch_version }}Datasets: {{ datasets_version }}Tokenizers: {{ tokenizers_version }}Citations{% if trainer_citation %}Cite {{ trainer_name }} as:{{ trainer_citation }} {% endif %} Cite TRL as: bibtex software{vonwerra2020trl, ...}从结构上看模板由五个部分组成YAML 前置元数据{{ card_data }}、模型概述、Quick start 推理示例、Training procedure含实验追踪徽标、训练方法与框架版本清单、以及 Citations 引用段。其中三处使用 {% if %} 条件渲染dataset_name、各追踪平台 URL、trainer_citation/paper_id——也就是说未提供的可选信息会自动从最终卡片中消失而不会留下空占位符。 ## 模板变量清单与取值来源 模板中出现的变量分为两类由调用方传入的“身份信息”和由渲染函数自动收集的“环境信息”。结合 [generate_model_card](https://link.gitcode.com/i/554eb9859e2cda62ad4eaf1df9e8898e) 的签名全部变量如下表 | 变量 | 类型/可空 | 说明 | | --- | --- | --- | | card_data | 自动构造 | 序列化的 ModelCardData 对象渲染为 YAML front matter | | model_name | 必填 | 训练产出模型的名称即卡片标题 | | base_model | 可空 | 底模 Hub ID渲染为指向模型页的链接 | | dataset_name | 可空 | 训练数据集 Hub ID触发 {% if dataset_name %} 分支 | | hub_model_id | 必填 | username/model_id 形式的 Hub 模型 ID注入 Quick start 代码 | | trainer_name | 必填 | 训练器名称如 DPO、GRPO取自 Trainer 类的 _name | | trainer_citation | 可空 | 该训练方法对应的 BibTeX 条目取自 Trainer 类 _paper[citation] | | paper_title / paper_id | 可空 | 方法论文标题与 ArXiv IDYYMM.NNNNN 格式渲染为论文链接 | | wandb_url / trackio_url / comet_url | 可空 | 对应实验追踪平台徽标三者独立开关 | | trl_version 等 5 个版本变量 | 自动收集 | 训练环境中 TRL、Transformers、PyTorch、Datasets、Tokenizers 的实际版本 | card_data 的构造细节值得注意在 [utils.py](https://link.gitcode.com/i/ae8a4506c9e0f650b583cd493dc7407d) 中ModelCardData 固定写入 library_nametransformers、licencelicensetags 以 generated_from_trainer 开头再拼上调用方传入的 tags。这个标签是 Hub 识别“该模型由训练器自动产出”的依据。 渲染路径方面模板文件通过包内相对路径定位 python template_pathstr(pkg_resources.files(trl).joinpath(ftemplates/{template_file}))也就是说模板必须位于安装后的trl包内templates/子目录template_file参数只传文件名不传时默认回落到lm_model_card.md。自动版本采集与渲染流程generate_model_card 的核心动作是调用 huggingface_hub 的ModelCard.from_template一次性把上述变量注入模板。其中五个版本变量并非来自参数而是在调用处直接通过version(trl)、version(transformers)、version(torch)、version(datasets)、version(tokenizers)从当前训练进程的环境中实时读取见 utils.py。这保证了 Framework versions 一节记录的是“真实产生这份权重的环境”而不是模板里写死的值。测试用例 TestGenerateModelCard 对渲染结果做了双向断言test_full所有参数齐备时断言卡片文本中同时出现底模链接、pipeline(text-generation, modelusername/my_hub_model, device_mapauto)示例代码、datasets: username/my_datasetfront matter 字段、三个平台徽标 URL、trainer_name、BibTeX 块以及My Paper论文链接test_val_nonebase_model、dataset_name与各 URL 全部为None时断言卡片仍能正常渲染出模型名与 Quick start 代码验证了{% if %}分支对空值的安全降级。这两组测试基本覆盖了模板的条件渲染边界也可以作为你自己调用generate_model_card时的行为参照。Trainer 侧的调用链create_model_card模板最终由训练器在训练收尾时触发。调用链为Trainer 子类定义 _name / _paper / _template_file→ BaseTrainer.create_model_card → generate_model_card → 写入 output_dir/README.md。BaseTrainer.create_model_card 在生成前做了四件准备工作只在主进程执行if not self.is_world_process_zero(): return分布式训练下避免多进程重复写卡片推断底模通过get_config_model_id(self.model.config)从模型 config 中提取原始 Hub ID只有当它是一个真实的 Hub ID而非本地目录时才作为base_model传入模板否则置None——这解释了为什么从本地 checkpoint 继续训练时卡片里不出现底模链接自动聚合 tags归一化调用方传入的tags并自动追加三类标签——检测到 Unsloth 时加unsloth、环境变量存在JOB_ID时加hf_jobs、以及合并self._tag_names。若 Trackio 处于活动状态还会把带 URL 参数的trackio:space_url标签注入 tags使 Hub 页面可直接跳转到对应 Space收集实验 URLwandb_url直接取wandb.run.url当 wandb 可用且有活跃 run 时trackio_url由 get_trackio_space_url 从当前 run 的_space_id拼出comet_url由 get_comet_experiment_url 取运行中实验的url属性。三个平台均“可用且有活跃实验”时才出徽标与模板中的条件渲染一一对应。每个 Trainer 子类通过三个类属性声明自己的卡片元数据。以 DPOTrainer 为例_name DPO _paper { title: Direct Preference Optimization: Your Language Model is Secretly a Reward Model, id: 2305.18290, citation: textwrap.dedent(\ inproceedings{rafailov2023direct, ...}), }create_model_card随后把self._name、self._paper.get(citation)、self._paper.get(title)、self._paper.get(id)分别填入trainer_name、trainer_citation、paper_title、paper_id最后执行model_card.save(os.path.join(self.args.output_dir, README.md))即模型卡直接落盘为输出目录下的README.md配合push_to_hub后成为 Hub 模型页面的正文。GRPOTrainer、DistillationTrainer 等均以同样方式定义_name与_paper。而_template_file的机制则让不同训练器可以复用create_model_card但换用不同模板BaseTrainer默认_template_file None落到lm_model_card.mdRewardTrainer 覆写为rm_model_card.md从而在 Quick start 中给出适合奖励模型的用法示例。实践要点手动生成卡片不经过 Trainer 时可直接调用generate_model_card(base_model..., model_name..., hub_model_id..., dataset_name..., tags..., wandb_url..., trackio_url..., comet_url..., trainer_name..., trainer_citation..., template_file..., paper_title..., paper_id...)返回值是 huggingface_hub 的ModelCard对象可用.save(README.md)落盘。可选参数缺省为None时对应段落自动省略见 test_val_none 的行为。自定义模板向template_file传入trl/templates/下的其他文件名即可切换卡片版式如奖励模型场景前提是该文件已存在于包内模板目录。Quick start 段的可读性模板中的示例固定使用text-generationpipeline 与 chat 格式输入、max_new_tokens128它面向聊天式微调模型如果你的模型是纯文本续写或 VLM可复制模板后修改该代码段。引用段trainer_citation非空时卡片会先给出训练方法的 BibTeX随后无条件附上 TRL 的software{vonwerra2020trl, ...}条目两者均为模板内置行为。小结lm_model_card.md 是 TRL “训练即可发布”流程的最后一公里它用 Jinja2 条件渲染把底模/数据集链接、可运行的 Quick start 代码、实验追踪徽标、训练方法出处论文链接 BibTeX与训练环境五个核心库的实测版本组织成一份可直接成为 Hub README 的模型卡而 BaseTrainer.create_model_card 与 generate_model_card 负责在主进程安全地采集这些信息并完成渲染落盘。理解了这套模板变量契约与调用链你就能在查看任何 TRL 训练产物的 README 时准确判断其中每个字段的数据来源也能按 tests/test_utils.py 给出的方式验证自定义模板的渲染结果。【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考