sentence-transformers CrossEncoder 模型卡模板全解析：为 Reranker 自动生成专业 README 的完整机制

sentence-transformers CrossEncoder 模型卡模板全解析为 Reranker 自动生成专业 README 的完整机制【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers本指南围绕 sentence-transformers/cross_encoder/model_card_template.md 展开剖析该 Jinja2 模板的结构、数据来源与自动填充机制。读完本文你将掌握CrossEncoder跨编码器 / Reranker模型卡在训练与保存时如何自动生成 README.mdCrossEncoderModelCardData各字段如何配置与自动推断以及save_pretrained/push_to_hub如何把训练数据、超参数、评估指标与使用示例渲染成可直接发布的模型卡。模型卡与模板的定位为什么 CrossEncoder 需要专用模板模型卡Model Card是随模型一同发布的说明文档向使用者交代模型的类型、底座、训练数据、超参数、评估结果与环境信息。在 sentence-transformers 中模型卡不是手写的而是由一个 Jinja2 模板 结构化数据对象渲染而成。本项目为四类模型各准备了一份模板基础模型卡sentence_transformers/base/model_card_template.md跨编码器模型卡本文主角sentence_transformers/cross_encoder/model_card_template.md句向量模型卡sentence_transformers/sentence_transformer/model_card_template.md多向量 / 稀疏编码器模型卡sentence_transformers/multi_vector_encoder/model_card_template.md、sentence_transformers/sparse_encoder/model_card_template.mdCrossEncoder 模板之所以需要独立存在是因为跨编码器模型的语义与句向量模型截然不同它不产出向量嵌入而是直接对文本对打分相关性分数 / 分类 logits因此模板中不存在Output Dimensionality、Similarity Function之类的字段取而代之的是Number of Output Labels并在 Usage 一节生成model.predict(pairs)与model.rank(query, documents)两种调用方式对应源码 cross_encoder/model.py 中的predict与rank接口。在仓库中模板被CrossEncoderModelCardData通过template_path Path(__file__).parent / model_card_template.md引用见 cross_encoder/model_card.py也就是说模板与数据类放在同一目录保证打包发布后模板始终可定位。模板骨架Frontmatter 元数据 正文段落模板以 YAML Frontmatter 开头紧接标题与简介再依次展开 Model Details、Usage、Evaluation、Training Details、Citation 等小节。它采用 Jinja2 条件渲染{% if %}/{% for %}字段为空时对应段落会被省略或替换为 HTML 注释占位符如!-- - **Base model:** Unknown --避免生成信息缺失的粗糙卡片。YAML Frontmatter 与{{ card_data }}Frontmatter 主体是一个占位符{{ card_data }}渲染时由数据类的to_yaml()方法填充。哪些字段进入 YAML 由 base/model_card.py 中的YAML_FIELDS常量控制YAML 字段含义language模型语言如en或[en, de, nl]license许可证如apache-2.0、mit、cc-by-nc-sa-4.0library_name固定为sentence-transformerstags标签CrossEncoder 默认[sentence-transformers, cross-encoder, reranker]训练时还会追加generated_from_trainer、loss:XXX、dataset_size:N等datasets训练/评估数据集 ID 列表从 Hub 校验后收集metrics评估指标名列表pipeline_tag单标签模型为text-ranking多标签为text-classificationwidget/model-index推理示例与结构化评估索引eval_results_to_model_index生成co2_eq_emissionsCodeCarbon 采集的碳排放数据安装codecarbon时才有base_model底座模型 IDto_yaml()只保留YAML_FIELDS中非 None 且非空的键所以未提供 license 时不会输出空字段见base/model_card.py的to_yaml实现。标题与简介标题回退逻辑为{{ model_name if model_name else Cross Encoder model }}。简介段落模板第 9 行会根据数据自动组合语义若提供了base_model介绍为finetuned from [base_model]否则介绍为trained若提供了带名称的训练数据集逐个列出带id的渲染为数据集链接多个数据集用逗号 / and 连接当名称拼接总长超过 200 字符时退化为只显示数据集数量结尾统一为It computes scores for pairs of texts, which can be used for {{ task_name }}.task_name未手动指定时会在register_model阶段自动推断单标签模型num_labels 1为text reranking and semantic search多标签为text pair classification同时pipeline_tag分别推断为text-ranking与text-classification见 cross_encoder/model_card.py 的register_model。Model Details模型档案与全架构打印Model Details Model Description一节逐行输出Model Type:Cross EncoderBase model:底座模型及其 revision。若指定了base_model_revision会以注释形式附注!-- at revision ... --否则回退为 Unknown 占位注释Maximum Sequence Length:{{ model_max_length }} tokens来自model.max_seq_lengthNumber of Output Labels:{{ model_num_labels }} label(s)由get_model_specific_metadata()注入model.num_labelsSupported Modalities:如Text、Image等多模态跨编码器支持由模型modalities格式化而来Training Dataset(s):与简介同源的训练数据集列表Language(s):字符串或列表两种形态均可渲染License:用户指定Model Sources小节固定列出指向 SBERT 官方文档、Cross Encoder 文档、GitHub 仓库以及 Hugging Face Cross Encoder 模型筛选页的链接为读者提供继续深入了解的入口。Full Model Architecture把{{ model_string }}即str(model)打印出的模块结构放进代码块让使用者一眼看到 Transformer backbone 与分类头的完整堆叠。Usage可复制的打分与排序示例模板在 Direct Usage (Sentence Transformers) 下固定给出安装命令pip install -U sentence-transformers随后的{{ usage_snippet }}由数据类的generate_usage_snippet()动态生成cross_encoder/model_card.py并区分两种形态单标签排序 / 打分场景num_labels 1——同时包含predict与rankfrom sentence_transformers import CrossEncoder # Download from the Hub model CrossEncoder(your_model_id) # Get scores for pairs of inputs pairs [ [How many calories in an egg, There are on average between 55 and 80 calories in an egg depending on its size.], [How many calories in an egg, Egg whites are very low in calories, have no fat, no cholesterol, and are loaded with protein.], [How many calories in an egg, Most of the calories in an egg come from the yellow yolk in the center.], ] scores model.predict(pairs) # 输出 scores 的实际数值由 run_usage_snippet 提前推理并写入 # Or rank different texts based on similarity to a single text ranks model.rank( How many calories in an egg, [ There are on average between 55 and 80 calories in an egg depending on its size., Egg whites are very low in calories, have no fat, no cholesterol, and are loaded with protein., Most of the calories in an egg come from the yellow yolk in the center., ], ) # [{corpus_id: ..., score: ...}, {corpus_id: ..., score: ...}, ...]多标签num_labels 1——只生成predict输出形状注释为(n, num_labels)且不生成rank段。这一点在测试TestGenerateUsageSnippetCrossEncoder::test_cross_encoder_multi_label中有明确断言见 tests/cross_encoder/test_model_card.py。示例文本的默认值是三组蛋的卡路里问答run_usage_snippet中硬编码如果训练/评估数据集可用set_widget_examples会从数据集中挑选前两个文本类或图像/音频类列作为真实的示例对query/answer让模型卡的使用示例与训练数据同源。若模型支持多模态如文本 图像对save_usage_example_assets会把非文本输入保存到assets/目录并在代码片段中用相对路径引用。Evaluation 与 Training Details训练过程的可追溯记录Evaluation / Metrics若有评估结果eval_metrics非空模板为每个评估器渲染一节评估器描述如 Binary Classification数据集名称单个或多个评估器类名以sentence_transformers.开头的会转成指向对应评估器文档的链接及其 JSON 配置指标 Markdown 表格——主指标用加粗标出同一类评估器在多个数据集上的结果会被合并为多列format_eval_metrics的分组逻辑。这些结果同时被转换为model-index结构化元数据便于 Hub 展示与检索。Training Datasets / Evaluation Datasets模板对每个数据集输出数据由compute_dataset_metrics与extract_dataset_metadata计算见base/model_card.py数据集名称、Hub ID 与 revisionrevision 取前 7 位样本规模size列名1 列 / 2 列 / 多列三种连接格式近似统计表字符串列给出 min/mean/max 字符数与 token 数数值列给出 min/mean/max图像/音频/视频列给出分辨率、时长与采样率基于前min(size, 100)个样本分块统计以控制内存3 条示例样本损失函数全限定名链接到对应损失文档及其 JSON 配置参数。Training HyperparametersNon-Default Hyperparameters仅列出与默认值不同的超参数on_train_begin时对比default_args_dict得出All Hyperparameters完整超参列表折叠在details中避免卡片过长。Training Logs / 环境影响 / 训练时间训练日志以 Markdown 表格呈现Epoch / Step / Training Loss / Validation Loss / 评估指标保存的最佳 checkpoint 所在行整行加粗并附注The bold row denotes the saved checkpoint.format_training_logs实现超过 100 行时自动折叠安装codecarbon后自动采集能耗kWh与碳排放kg CO2并记录是否云端、GPU/CPU 型号与 RAM 大小get_codecarbon_data从CodeCarbonCallback提取Training / Evaluation / Total 三项耗时get_training_duration_dataFramework VersionsPython、Sentence Transformers、Transformers、PyTorch、Accelerate、Datasets、Tokenizers 的精确版本号get_versions()。数据从哪来CrossEncoderModelCardData 与训练回调模板本身只是壳所有{{ ... }}变量都来自CrossEncoderModelCardData继承BaseModelCardData。其用户可配置字段如下字段类型说明model_namestr卡片标题如 CrossEncoder based on answerdotai/ModernBERT-basemodel_idstr推送到 Hub 时的模型 ID如tomaarsen/ce-mpnet-base-ms-marcotask_namestr人类可读的任务描述不填则按num_labels自动推断train_datasets/eval_datasetsList[Dict][{name: SNLI, id: stanfordnlp/snli}]形式只给id时自动以 id 作为 namelanguagestr \| List[str]如en或[en, de, nl]licensestr如apache-2.0、mittagsList[str]默认[sentence-transformers, cross-encoder, reranker]local_files_onlybool为 True 时不访问 Hub 校验数据集与底座模型离线场景默认 Falsegenerate_widget_examplesbool是否从数据集生成 widget 示例并计算相似度默认 True使用方式是在构造模型时传入docstring 示例见cross_encoder/model_card.pyfrom sentence_transformers import CrossEncoder from sentence_transformers.cross_encoder.model_card import CrossEncoderModelCardData model CrossEncoder( microsoft/mpnet-base, model_card_dataCrossEncoderModelCardData( model_idtomaarsen/ce-mpnet-base-allnli, train_datasets[ {name: SNLI, id: stanfordnlp/snli}, {name: MultiNLI, id: nyu-mll/multi_nli}, ], eval_datasets[ {name: SNLI, id: stanfordnlp/snli}, {name: MultiNLI, id: nyu-mll/multi_nli}, ], licenseapache-2.0, languageen, ), )训练回调的自动填充训练阶段CrossEncoderModelCardCallback继承BaseModelCardCallback通过transformers.TrainerCallback的四个钩子把过程数据写回model_card_data实现在base/model_card.pyon_init_end追加generated_from_trainer标签若训练器挂了 CodeCarbon 回调则接管它从 Trainer 的数据集缓存推断训练/评估数据集的 name、id、revision 与统计信息登记损失函数set_losses并追加loss:XXX标签与各损失的 BibTeX 引用从数据集抽取 widget 示例on_train_begin记录全部超参数与非默认超参数忽略output_dir、logging_strategy、report_to等训练器管理字段并启动训练计时on_evaluate把验证损失与评估结果并入训练日志表格on_log把当前 step 的训练损失写入训练日志。CrossEncoderModelCardData.register_model负责绑定模型实例并推断task_name/pipeline_tagvalidate_datasets会请求 Hub 校验数据集 ID 是否存在不存在则告警并删除 id并在用户未指定语言时从数据集卡片信息中推断语言set_base_model通过get_model_info校验底座模型并在 Hub 上存在时记录 revision。model_id若不含组织/模型名形式缺少/会被警告并置空。生成与保存save_pretrained 与 push_to_hub模板渲染的入口是generate_model_card(model)base/model_card.pymodel_card ModelCard.from_template( card_datamodel.model_card_data, template_pathmodel.model_card_data.template_path, hf_emoji, )ModelCard.from_template会依次调用数据类的to_dict()收集模板所需的全部变量并做结果缓存与to_yaml()产出 Frontmatter。渲染完成后generate_model_card还会把assets/相对路径替换为 Hub 上的绝对资源 URL确保图片、音频、视频在 README 中可正常展示。该函数被两条保存链路调用见 base/model.pysave_pretrained(path, ..., create_model_cardTrue)保存模型权重与配置文件后把生成的卡片写入path/README.mdpush_to_hub(repo_id, ...)先把模型与卡片存到临时目录再推送到 Hub。replace_model_cardFalse时若远端已存在 README.md 则跳过卡片生成以避免覆盖已有内容。测试如何保障模板质量仓库用测试对模板与数据类做了严格约束见 tests/cross_encoder/test_model_card.pytest_model_card_base对 1 个 / 多个训练数据集、1 个 / 3 个标签的模型分别生成卡片断言关键子串存在且卡片中不允许出现连续两个以上空行test_model_card_set_transform使用set_transform后卡片中的列名必须反映变换后的列如new_anchor而非原始列名TestGenerateUsageSnippetCrossEncoder分别验证默认示例、自定义示例、多标签(n, num_labels)、无rank段与单标签(n,)、含rank段的代码片段生成逻辑以及多模态示例的资源 URL 转换。这些测试保证模板渲染不出畸形 Markdown、数据集统计与列名始终与真实数据一致、生成的代码示例可运行且形状注释正确。小结模板的扩展空间模板中保留了若干 HTML 注释占位符包括Out-of-Scope Use、Bias, Risks and Limitations、Recommendations、Glossary、Model Card Authors与Model Card Contact这是官方模型卡规范建议的完整结构。sentence-transformers 默认不填充这些偏社论的章节但模板文件完全可读可改——如果你需要为自己的组织定制更严格的模型卡规范例如补充风险说明与作者署名直接修改 model_card_template.md 并新增对应的数据字段即可渲染管线无需任何改动。这正是数据驱动模板 自动收集回调这套机制留给使用者的最大自由度。【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考