模型卡片Model Card在机器学习项目里经常被当成最后一个不得不写的文档。项目验收需要它模型上架需要它审计合规也需要它但真正动手时它又是最容易被拖延的部分。原因不难理解训练指标散落在 TensorBoard 里数据集说明散落在数据手册里模型的使用限制和少部分判断性内容只有训练者自己清楚把它们整理成一份结构完整、可评审、可发布的 Markdown 文档工作量相当于再写一份实验总结。而 LLM 的文本生成能力恰好可以承担其中大部分工作。下面要解决的问题很具体怎么搭建一条从模型元数据到模型卡片的自动生成链路。默认情况下系统接收一份结构化的模型元数据 JSON通过精心设计的提示词让 LLM 生成符合规范的模型卡片 Markdown再用脚本校验章节完整性和关键指标最终输出可提交审阅的文档。读完可以把它改造成自己的模型发布流程。1. 先理解模型卡片到底在解决什么问题1.1 模型卡片不是 README而是一份可审计的模型说明书模型卡片的理念最早来自 2019 年提出的 Model Cards for Model Reporting。它的目标很朴素让一个不熟悉内部实验细节的人也能快速理解这个模型能做什么、不能做什么、用什么数据训练、效果如何、以及对哪些群体可能存在偏差。它和 README 最大的区别在于约束性。README 想怎么写就怎么写模型卡片却需要按固定章节组织内容。常见的模型卡片包含以下七部分章节回答的核心问题信息来源模型详情这是什么模型用什么底座谁发布的训练配置、日志预期用途适合什么场景禁止用于什么场景产品定义、算法评审训练数据数据来源、规模、清洗方式、划分比例数据文档、训练流程评估方法测试集怎么构建评估指标是什么评估脚本与配置量化评估结果整体指标是多少分群指标如何评估输出 JSON、报表伦理与公平性考量模型可能对哪些群体产生不公平影响人工分析、数据审计注意事项和推荐建议当前版本有哪些限制用户需要注意什么实验观察、线上反馈可以看到前几项内容高度结构化完全可以从工程信息中抽取后几项则需要判断力。这正是 LLM 自动生成的最佳场景让模型完成从事实到文字的转换再由人工去补足判断性内容。1.2 手动编写模型卡片的成本正在失控在实际项目中手动编写模型卡片会遇到三个非常现实的问题。第一个问题是信息分散。训练脚本里写的是学习率、batch size评估脚本输出的是 accuracy、f1数据集目录里有原始数据统计。要把这些分散信息汇总成一份文档往往需要翻多个系统而且每个人汇总出来的格式都不一样。第二个问题是更新滞后。模型从 v1.0 升级到 v1.1可能只改了数据量和训练轮数但文档经常忘记同步。等到审计时拿旧文档去解释新模型信息已经失真。第三个问题是审阅困难。人工写的模型卡片容易出现语气不一致、数据口径不统一、章节残缺。评审人员很难快速判断这份文档是否可信。LLM 自动生成并不能解决所有问题但它能把信息收集、格式排版、初稿生成这条链路自动化。工程团队可以把精力集中在真正的判断环节模型的使用边界、伦理影响和风险提示。1.3 自动生成要解决什么不解决什么明确边界很重要。LLM 自动生成模型卡片解决的是从结构化数据到规范初稿的转换问题。它不解决的是事实来源问题。如果输入给 LLM 的元数据本身就是错的生成出来的文档必然也是错的。因此整套系统的前提是先建立一份可靠的结构化元数据再让 LLM 在这个基础上做文本生成。设计上有一个原则必须守住模型卡片里出现的数字必须来自训练和评估系统的真实输出不能由 LLM 自由发挥。后面会看到这个原则会直接影响提示词设计和校验脚本的写法。2. 搭建生成链路前先把输入数据层设计好2.1 模型卡片需要哪些事实信息要让 LLM 生成一份合格的模型卡片不能只给它一个模型名字。需要把模型卡片需要的所有事实信息拆成结构化字段。一份最小可用的元数据 JSON 至少应该包含模型基础信息、训练数据、训练配置和评估结果四类内容。如果做分群评估还需要把测试集划分和分群指标也放进来因为模型卡片里的公平性分析依赖这些数据。建议的元数据结构如下{ model_name: sentiment-classifier, model_version: 1.2.0, model_type: fine-tuned transformer, base_model: bert-base-chinese, task: text-classification, language: zh, author: nlp-teamexample.com, release_date: 2025-03-10, framework: PyTorch, training_data: { source: internal review comments dataset, size: 120000, split: { train: 96000, validation: 12000, test: 12000 }, preprocessing: remove html tags, deduplicate, filter length512 }, training: { epochs: 3, learning_rate: 2e-05, batch_size: 32, runtime: 4h on single A100 }, evaluation: { accuracy: 0.921, precision: 0.89, recall: 0.87, f1: 0.88 }, evaluation_by_group: { short_text: { accuracy: 0.85 }, long_text: { accuracy: 0.94 } } }这份 JSON 的实际字段不需要和示例完全一致但建议保持两个原则一是所有人类可读的说明放在代码库中维护二是所有自动产生的数值从评估流程直接导出不要手工复制。2.2 数据来源如何对接不同团队的数据来源差异很大。学习环境里元数据可能是直接手写的 JSON 文件生产环境里推荐从以下系统自动采集数据类别推荐来源说明模型基础信息训练任务配置从实验管理平台读取如 MLflow、WB训练配置训练脚本参数由训练入口输出一份 training_config.json数据集信息数据版本管理记录数据集版本、规模、清洗规则评估结果评估脚本评估结束后输出 evaluation_result.json分群结果分群评估代码按业务维度或敏感属性切分后计算指标如果暂时没有实验管理平台也可以直接从训练脚本和评估脚本中生成两个中间文件。关键不是系统有多复杂而是让元数据成为训练和评估流程的自然产出物。2.3 学习环境和生产环境的数据差异学习环境跑通 Demo 时元数据可以直接手写甚至可以写死在代码里。但进入生产环境需要注意三件事。第一数据版本要可追溯。元数据里至少要有模型版本、数据集版本、生成时间三个字段否则无法回溯。第二敏感信息要脱敏。生产系统的训练数据里可能包含用户评论、内部业务名称这些信息不能原样进入外部 LLM 提示词。可以先在脚本里做替换或者用本地部署模型。第三数值口径要统一。不同评估脚本可能算出不同版本的 accuracy建议由统一的评估入口输出最终结果避免元数据出现同类指标两个数值的情况。3. 环境准备依赖、模型选型和目录结构3.1 Python 环境与依赖本项目的核心依赖非常少。最简情况下只需要openai一个库因为现在很多本地推理服务都提供 OpenAI 兼容接口。如果后续要扩展验证脚本可以再加pytest。创建一个虚拟环境并安装依赖python -m venv .venv source .venv/bin/activate pip install openai1.0.0如果希望后续使用.env文件管理密钥可以额外安装python-dotenvpip install python-dotenv不推荐在脚本中直接写死 API Key。使用环境变量是更稳妥的方式后面主脚本会演示如何读取。3.2 LLM 推理方式选择自动生成模型卡片对 LLM 的要求并不高它需要理解 JSON 字段、遵循输出格式、按 Markdown 组织文字。这个任务不需要最强模型但温度需要设置得低一些。实际项目中有两类选择。第一类是本地或私有化部署的推理服务比如通过 vLLM 部署的 Qwen 系列模型。这类模型参数从几十亿到上百亿都有优势是数据不出内网适合处理敏感训练信息。缺点是本地硬件部署有一定成本。第二类是商业 API 模型。优点是生成质量稳定接入快但要把元数据发到外部服务需要注意数据脱敏和合规审查。下面的示例代码统一走 OpenAI 兼容接口无论哪种服务只要提供base_url和api_key即可接入。3.3 项目目录结构推荐采用下面这种简单但清晰的结构model-card-generator/ ├── README.md ├── requirements.txt ├── .env.example ├── metadata/ │ └── sentiment_model.json ├── generator/ │ ├── __init__.py │ ├── prompt.py │ ├── validator.py │ └── generate.py └── output/ └── MODEL_CARD.mdmetadata目录存放输入元数据generator目录存放核心代码output目录存放生成的模型卡片。把代码和输出分离是为了后续接入 CI 时容易替换。4. 提示词设计用约束条件锁住输出结构4.1 系统提示词定义角色和硬性规则提示词是整个自动生成系统里最容易被低估的部分。很多初版脚本只写一句帮我生成模型卡片得到的输出结构自然五花八门。正确的做法是在系统提示词里明确角色、输出协议和禁止事项。SYSTEM_PROMPT 你是一个模型治理工程师的助手。你的任务是根据用户提供的结构化模型元数据生成一份可直接发布的模型卡片。 硬性要求 1. 只能使用用户提供的事实禁止编造任何指标、版本、日期和数据集信息。 2. 使用中文写作格式为 Markdown。 3. 必须包含以下七个章节顺序不能改变 - 模型详情 - 预期用途 - 训练数据 - 评估方法 - 量化评估结果 - 伦理与公平性考量 - 注意事项和推荐建议 4. 元数据中缺失的信息写“未提供”不要猜测。 5. 不要输出用户提问的复述不要输出客套语直接输出模型卡片内容。 注意最后一条。LLM 经常会在正文前输出好的根据你提供的元数据我生成了以下模型卡片这些内容在自动发布场景里非常碍事必须在系统提示词中明确禁止。4.2 用户提示词把结构化数据转成文本输入用户提示词相对简单核心是把 JSON 元数据完整放入上下文。这里需要注意 JSON 转义问题。在 Python 中使用json.dumps序列化字典并设置ensure_asciiFalse避免中文字符被转成\uXXXX。import json def build_user_prompt(metadata: dict) - str: metadata_json json.dumps(metadata, ensure_asciiFalse, indent2) return ( 请根据下面的结构化模型元数据生成模型卡片。\n 元数据内容如下\n\n f{metadata_json} )如果元数据量很大可以考虑把不参与文本生成的字段在加载时就剔除只保留必要字段。这样既能缩短上下文又能减少 LLM 被无关字段干扰的概率。4.3 采样参数如何设置调用 LLM 时有三个参数需要重点调整。temperature控制随机性。生成模型卡片不适合创造性表达建议设置在 0.1 到 0.3 之间避免同一份元数据生成两次结果差异过大。max_tokens控制最大生成长度。模型卡片通常有 1000 到 2000 字再算上 Markdown 符号建议设置在 2000 到 3000。如果设置过小输出会被截断章节不完整。response_format如果服务支持可以设置为 JSON 模式但在直接生成 Markdown 的方案里不需要。下面的调用示例使用 OpenAI 兼容接口from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyempty ) response client.chat.completions.create( modelqwen2.5-7b-instruct, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: build_user_prompt(metadata)} ], temperature0.2, max_tokens2500 )代码里的端点和模型名是示例。实际项目建议把base_url、api_key、model都放到环境变量中避免每次更换模型都要改代码。5. 核心代码从 JSON 到 Markdown 的完整链路5.1 主脚本读取元数据并调用生成接口下面实现一个完整的generate.py。它负责四件事读取元数据、构造提示词、调用 LLM、保存输出。import os import json import pathlib from openai import OpenAI from generator.prompt import SYSTEM_PROMPT, build_user_prompt from generator.validator import validate_model_card def load_metadata(path: str) - dict: with open(path, r, encodingutf-8) as f: return json.load(f) def generate_model_card( metadata: dict, output_path: str ) - str: endpoint os.getenv(LLM_ENDPOINT, http://127.0.0.1:8000/v1) api_key os.getenv(LLM_API_KEY, empty) model os.getenv(LLM_MODEL, qwen2.5-7b-instruct) client OpenAI(base_urlendpoint, api_keyapi_key) response client.chat.completions.create( modelmodel, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: build_user_prompt(metadata)} ], temperature0.2, max_tokens2500 ) content response.choices[0].message.content output_path pathlib.Path(output_path) output_path.parent.mkdir(parentsTrue, exist_okTrue) output_path.write_text(content, encodingutf-8) return content if __name__ __main__: metadata_path os.getenv(METADATA_PATH, metadata/sentiment_model.json) output_path os.getenv(OUTPUT_PATH, output/MODEL_CARD.md) metadata load_metadata(metadata_path) content generate_model_card(metadata, output_path) problems validate_model_card(content, metadata) if problems: for problem in problems: print(f[校验失败] {problem}) raise SystemExit(1) print(f模型卡片已生成{output_path})脚本在生成完 Markdown 后立即调用校验函数。如果校验失败直接以非零退出码结束。这个设计方便后续接入 CI校验不通过就不会生成最终产物。5.2 校验脚本检查章节完整性和关键指标最简单的校验脚本做两件事检查七个小节是否都存在检查元数据中的评估指标是否出现在生成的文本中。REQUIRED_SECTIONS [ 模型详情, 预期用途, 训练数据, 评估方法, 量化评估结果, 伦理与公平性考量, 注意事项和推荐建议 ] def validate_model_card(content: str, metadata: dict) - list[str]: problems [] for section in REQUIRED_SECTIONS: if section not in content: problems.append(f缺少章节[{section}]) eval_metrics metadata.get(evaluation, {}) for key, value in eval_metrics.items(): if isinstance(value, (int, float)) and str(value) not in content: problems.append(f评估指标 {key}{value} 没有出现在模型卡片中) return problems这里用字符串包含来校验数字是比较原始的方案。它的作用是抓漏项不能完全替代人工核对。更严格的方案会在后面第 8 节介绍让 LLM 先输出结构化 JSON再由模板渲染 Markdown。那样数字一致性可以从数据结构上保证。5.3 命令行运行方式写好脚本后通过命令行运行export LLM_ENDPOINThttp://127.0.0.1:8000/v1 export LLM_MODELqwen2.5-7b-instruct python -m generator.generate \ --metadata metadata/sentiment_model.json \ --output output/MODEL_CARD.md这里没有用argparse而是用环境变量传入路径。是为了让 CI 环境下更容易注入不同参数。如果要在本地多次调试也可以改成命令行参数两种方式都可以接受选择一致的风格即可。6. 运行验证用一份最小元数据生成模型卡片6.1 准备一份最小测试元数据为了验证链路先准备一份简单的元数据文件metadata/sentiment_model.json。内容不需要很复杂但必须覆盖模型信息、训练数据、评估指标三个核心部分。{ model_name: sentiment-classifier, model_version: 1.2.0, model_type: fine-tuned transformer, base_model: bert-base-chinese, task: text-classification, language: zh, training_data: { size: 120000, source: e-commerce review comments }, evaluation: { accuracy: 0.921, f1: 0.88 } }这份简化元数据缺少伦理考量等判断性信息正好可以在生成结果里看到 LLM 如何处理未提供的情况。6.2 预期输出结构运行脚本后output/MODEL_CARD.md应该是一份包含七个小节的完整 Markdown。格式大致如下# Model Card: sentiment-classifier ## 模型详情 该模型是一个基于 bert-base-chinese 微调的中文情感分类模型... ## 预期用途 主要适用于电商评论的正负面情感判断... ## 训练数据 训练数据来源为... ## 评估方法 评估指标采用 accuracy 和 f1... ## 量化评估结果 在测试集上的整体准确率为 0.921F1 值为 0.88... ## 伦理与公平性考量 当前元数据未提供分群评估结果因此无法对特定群体的表现差异进行完整分析... ## 注意事项和推荐建议 该模型仅针对电商评论场景训练在其他领域使用前需要额外验证...如果生成的文本中出现了0.921和0.88这两个数字但章节不完整校验脚本就会报错。这是一个设计合理的反馈闭环。6.3 生成后的质量检查清单脚本自动校验通过不代表文档可以直接发布。人工需要额外检查以下项目检查项通过标准检查方式章节完整性七个章节全部存在且顺序正确校验脚本数字一致性所有评估指标与元数据一致校验脚本 人工抽查语言可读性无客套语、无重复段落、无未替换占位符人工阅读假设合理性预期用途和局限性描述符合业务实际算法负责人确认数据敏感度没有泄露内部数据名或敏感样本发布前审阅这里的核心判断是自动生成负责快人工审阅负责准。两者缺一不可。7. 常见问题与排查路径7.1 输出格式混乱或章节缺失现象生成的 Markdown 里没有预期的二级标题或者出现了好的根据你提供的元数据等客套语。可能原因有三个系统提示词里没有明确禁止客套语温度设置过高导致输出风格不稳定max_tokens设置过小导致后半部分被截断。排查顺序建议从输入开始检查元数据是否加载完整字段是否为空。检查系统提示词是否明确列出了七个章节。检查max_tokens是否足够。检查温度是否大于 0.5如果是降到 0.2。解决方案给系统提示词增加不要输出与模型卡片无关的内容并将温度调整到 0.2 左右。如果问题仍然存在可以考虑使用 Few-shot 示例在消息序列中插入一组用户输入 理想输出作为示范。7.2 LLM 编造评估指标现象生成的模型卡片里出现了一个元数据中不存在的指标比如 accuracy 变成了 0.98而原始 JSON 里明明是 0.921。这是最严重的问题通常被称作幻觉。LLM 在开放生成时会根据训练语料中的概率补全内容尤其当元数据字段较少时它更容易自行想象。应对方式有三层。第一层在系统提示词中增加数字只能来自元数据禁止修改。第二层用校验脚本把关键数字回查一遍比如检查0.921是否出现在生成结果中。第三层更彻底的做法是改变生成方式让 LLM 只负责生成描述性文本所有数值由程序从元数据填充到模板中。这就是第 8 节要讲的模板缝合方案。7.3 输出被截断现象生成的 Markdown 到量化评估结果章节就结束了后面两个章节完全缺失。可能原因max_tokens设置过小或者单个 token 对应的中文字数较多时输出长度超出限制。排查方式查看 API 返回的finish_reason。如果等于length说明是长度被截断如果等于stop说明是模型自然结束。解决方案把max_tokens从 1500 提升到 3000。如果输出内容包含大量表格也可以考虑按章节拆分生成每个章节独立调用一次 LLM最后合并。7.4 Markdown 表格渲染异常现象生成的卡片中包含表格但表格列数不一致或者在本地预览时出现错位。可能原因LLM 对中英文混排表格的列宽处理不稳定偶尔会多出或漏掉一个分隔符。解决方案如果业务上不强制要求表格可以要求 LLM 用列表代替表格。如果必须有表格可以在系统提示词中给出一个固定的表格模板让 LLM 只填行内容。下面是排查链路汇总建议作为团队内部文档发布问题现象可能原因检查方式处理建议输出有客套语提示词未禁止查看输出开头系统提示词增加约束章节缺失max_tokens 不足查看 finish_reason调大 max_tokens数字被篡改模型幻觉校验脚本比对模板填充 人工审阅表格错位列数不一致本地预览用列表代替表格或固定模板8. 从脚本走向生产模板缝合与人工审阅8.1 更稳健的做法让 LLM 输出 JSON再渲染 Markdown直接让 LLM 生成 Markdown 的优点是简单缺点在于格式和内容耦合在一起一旦输出不规范后期处理很麻烦。生产环境推荐一种更稳健的方式两步生成。第一步让 LLM 根据元数据输出结构化 JSON字段由我们预先定义例如{ model_details: 模型描述文本, intended_use: 预期用途说明, training_data: 训练数据说明, ... }第二步程序读取这个 JSON用 Jinja2 或普通字符串模板渲染成最终 Markdown。这样有几个好处数字字段可以直接从元数据中注入不经过 LLM 手写格式由模板统一控制不会因为 LLM 状态差异而出现结构漂移校验脚本只需要检查 JSON Schema 是否合法比检查 Markdown 字符串可靠得多。8.2 生产环境还需要什么一个可用的自动生成脚本距离生产环境落地还有一段距离。至少还需要考虑下面几点。第一日志和审计。每次生成都应该记录模型版本、元数据哈希、LLM 模型名称、生成耗时方便事后回溯问题。第二人工审阅流程。模型卡片最终要通过评审才能发布。推荐用 Git 管理输出文档生成后由算法负责人提交 PR审阅通过后合并到发布分支。第三安全与权限。如果元数据包含敏感信息需要配置严格的访问权限。调用外部 API 时所有输入必须经过脱敏或过滤。第四异常处理。LLM 接口可能超时、限流、返回空内容。脚本要做重试和熔断不要把一次失败的生成结果直接写入正式文档。8.3 扩展方向这套链路可以往多个方向扩展。接入 CI在训练流程结束后自动运行生成脚本把新的模型卡片提交到代码仓库。适合模型频繁迭代的团队。多模型对比同一份元数据可以并行使用多个 LLM 生成多个版本由评审人员选择最优版本或者拼接不同模型的优点。RAG 增强如果模型卡片需要引用数据集文档、伦理审查意见可以先把这些资料向量化生成时检索相关片段再放入提示词减少 LLM 的幻觉概率。多语言版本中文模型卡片生成后可以让 LLM 翻译成英文版本但翻译结果同样需要人工审阅因为术语和业务限制不能丢。9. 可复用的发布前检查清单最后整理一份可以直接复制到团队文档中的检查清单。每次生成模型卡片时按这个顺序过一遍。元数据准备模型版本、数据集版本、训练配置、评估指标都是最新值并且有生成时间。提示词检查系统提示词明确禁止编造数字章节列表完整温度低于 0.3。输出校验七个章节全部存在所有关键指标都出现在卡片中无客套语和重复段落。敏感信息检查没有出现内部业务名称、未脱敏样本、非公开数据集名称。人工审阅重点审阅预期用途伦理与公平性考量注意事项这三部分不能只依赖 LLM。版本管理生成的模型卡片打上版本号记录生成命令、LLM 模型和审阅人。发布确认使用该模型卡片的下游团队确认内容与实际模型一致。模型卡片的自动生成不是把人工写文档这个环节消灭掉而是把机械劳动交给脚本把需要判断的内容留给工程师。落到自己的项目时建议先从一份最小元数据 JSON 开始跑通一条链路再把校验逐步加严。这个过程本身和训练模型一样值得投入。 用LLM自动生成模型卡片：从元数据到Markdown的完整链路
模型卡片Model Card在机器学习项目里经常被当成最后一个不得不写的文档。项目验收需要它模型上架需要它审计合规也需要它但真正动手时它又是最容易被拖延的部分。原因不难理解训练指标散落在 TensorBoard 里数据集说明散落在数据手册里模型的使用限制和少部分判断性内容只有训练者自己清楚把它们整理成一份结构完整、可评审、可发布的 Markdown 文档工作量相当于再写一份实验总结。而 LLM 的文本生成能力恰好可以承担其中大部分工作。下面要解决的问题很具体怎么搭建一条从模型元数据到模型卡片的自动生成链路。默认情况下系统接收一份结构化的模型元数据 JSON通过精心设计的提示词让 LLM 生成符合规范的模型卡片 Markdown再用脚本校验章节完整性和关键指标最终输出可提交审阅的文档。读完可以把它改造成自己的模型发布流程。1. 先理解模型卡片到底在解决什么问题1.1 模型卡片不是 README而是一份可审计的模型说明书模型卡片的理念最早来自 2019 年提出的 Model Cards for Model Reporting。它的目标很朴素让一个不熟悉内部实验细节的人也能快速理解这个模型能做什么、不能做什么、用什么数据训练、效果如何、以及对哪些群体可能存在偏差。它和 README 最大的区别在于约束性。README 想怎么写就怎么写模型卡片却需要按固定章节组织内容。常见的模型卡片包含以下七部分章节回答的核心问题信息来源模型详情这是什么模型用什么底座谁发布的训练配置、日志预期用途适合什么场景禁止用于什么场景产品定义、算法评审训练数据数据来源、规模、清洗方式、划分比例数据文档、训练流程评估方法测试集怎么构建评估指标是什么评估脚本与配置量化评估结果整体指标是多少分群指标如何评估输出 JSON、报表伦理与公平性考量模型可能对哪些群体产生不公平影响人工分析、数据审计注意事项和推荐建议当前版本有哪些限制用户需要注意什么实验观察、线上反馈可以看到前几项内容高度结构化完全可以从工程信息中抽取后几项则需要判断力。这正是 LLM 自动生成的最佳场景让模型完成从事实到文字的转换再由人工去补足判断性内容。1.2 手动编写模型卡片的成本正在失控在实际项目中手动编写模型卡片会遇到三个非常现实的问题。第一个问题是信息分散。训练脚本里写的是学习率、batch size评估脚本输出的是 accuracy、f1数据集目录里有原始数据统计。要把这些分散信息汇总成一份文档往往需要翻多个系统而且每个人汇总出来的格式都不一样。第二个问题是更新滞后。模型从 v1.0 升级到 v1.1可能只改了数据量和训练轮数但文档经常忘记同步。等到审计时拿旧文档去解释新模型信息已经失真。第三个问题是审阅困难。人工写的模型卡片容易出现语气不一致、数据口径不统一、章节残缺。评审人员很难快速判断这份文档是否可信。LLM 自动生成并不能解决所有问题但它能把信息收集、格式排版、初稿生成这条链路自动化。工程团队可以把精力集中在真正的判断环节模型的使用边界、伦理影响和风险提示。1.3 自动生成要解决什么不解决什么明确边界很重要。LLM 自动生成模型卡片解决的是从结构化数据到规范初稿的转换问题。它不解决的是事实来源问题。如果输入给 LLM 的元数据本身就是错的生成出来的文档必然也是错的。因此整套系统的前提是先建立一份可靠的结构化元数据再让 LLM 在这个基础上做文本生成。设计上有一个原则必须守住模型卡片里出现的数字必须来自训练和评估系统的真实输出不能由 LLM 自由发挥。后面会看到这个原则会直接影响提示词设计和校验脚本的写法。2. 搭建生成链路前先把输入数据层设计好2.1 模型卡片需要哪些事实信息要让 LLM 生成一份合格的模型卡片不能只给它一个模型名字。需要把模型卡片需要的所有事实信息拆成结构化字段。一份最小可用的元数据 JSON 至少应该包含模型基础信息、训练数据、训练配置和评估结果四类内容。如果做分群评估还需要把测试集划分和分群指标也放进来因为模型卡片里的公平性分析依赖这些数据。建议的元数据结构如下{ model_name: sentiment-classifier, model_version: 1.2.0, model_type: fine-tuned transformer, base_model: bert-base-chinese, task: text-classification, language: zh, author: nlp-teamexample.com, release_date: 2025-03-10, framework: PyTorch, training_data: { source: internal review comments dataset, size: 120000, split: { train: 96000, validation: 12000, test: 12000 }, preprocessing: remove html tags, deduplicate, filter length512 }, training: { epochs: 3, learning_rate: 2e-05, batch_size: 32, runtime: 4h on single A100 }, evaluation: { accuracy: 0.921, precision: 0.89, recall: 0.87, f1: 0.88 }, evaluation_by_group: { short_text: { accuracy: 0.85 }, long_text: { accuracy: 0.94 } } }这份 JSON 的实际字段不需要和示例完全一致但建议保持两个原则一是所有人类可读的说明放在代码库中维护二是所有自动产生的数值从评估流程直接导出不要手工复制。2.2 数据来源如何对接不同团队的数据来源差异很大。学习环境里元数据可能是直接手写的 JSON 文件生产环境里推荐从以下系统自动采集数据类别推荐来源说明模型基础信息训练任务配置从实验管理平台读取如 MLflow、WB训练配置训练脚本参数由训练入口输出一份 training_config.json数据集信息数据版本管理记录数据集版本、规模、清洗规则评估结果评估脚本评估结束后输出 evaluation_result.json分群结果分群评估代码按业务维度或敏感属性切分后计算指标如果暂时没有实验管理平台也可以直接从训练脚本和评估脚本中生成两个中间文件。关键不是系统有多复杂而是让元数据成为训练和评估流程的自然产出物。2.3 学习环境和生产环境的数据差异学习环境跑通 Demo 时元数据可以直接手写甚至可以写死在代码里。但进入生产环境需要注意三件事。第一数据版本要可追溯。元数据里至少要有模型版本、数据集版本、生成时间三个字段否则无法回溯。第二敏感信息要脱敏。生产系统的训练数据里可能包含用户评论、内部业务名称这些信息不能原样进入外部 LLM 提示词。可以先在脚本里做替换或者用本地部署模型。第三数值口径要统一。不同评估脚本可能算出不同版本的 accuracy建议由统一的评估入口输出最终结果避免元数据出现同类指标两个数值的情况。3. 环境准备依赖、模型选型和目录结构3.1 Python 环境与依赖本项目的核心依赖非常少。最简情况下只需要openai一个库因为现在很多本地推理服务都提供 OpenAI 兼容接口。如果后续要扩展验证脚本可以再加pytest。创建一个虚拟环境并安装依赖python -m venv .venv source .venv/bin/activate pip install openai1.0.0如果希望后续使用.env文件管理密钥可以额外安装python-dotenvpip install python-dotenv不推荐在脚本中直接写死 API Key。使用环境变量是更稳妥的方式后面主脚本会演示如何读取。3.2 LLM 推理方式选择自动生成模型卡片对 LLM 的要求并不高它需要理解 JSON 字段、遵循输出格式、按 Markdown 组织文字。这个任务不需要最强模型但温度需要设置得低一些。实际项目中有两类选择。第一类是本地或私有化部署的推理服务比如通过 vLLM 部署的 Qwen 系列模型。这类模型参数从几十亿到上百亿都有优势是数据不出内网适合处理敏感训练信息。缺点是本地硬件部署有一定成本。第二类是商业 API 模型。优点是生成质量稳定接入快但要把元数据发到外部服务需要注意数据脱敏和合规审查。下面的示例代码统一走 OpenAI 兼容接口无论哪种服务只要提供base_url和api_key即可接入。3.3 项目目录结构推荐采用下面这种简单但清晰的结构model-card-generator/ ├── README.md ├── requirements.txt ├── .env.example ├── metadata/ │ └── sentiment_model.json ├── generator/ │ ├── __init__.py │ ├── prompt.py │ ├── validator.py │ └── generate.py └── output/ └── MODEL_CARD.mdmetadata目录存放输入元数据generator目录存放核心代码output目录存放生成的模型卡片。把代码和输出分离是为了后续接入 CI 时容易替换。4. 提示词设计用约束条件锁住输出结构4.1 系统提示词定义角色和硬性规则提示词是整个自动生成系统里最容易被低估的部分。很多初版脚本只写一句帮我生成模型卡片得到的输出结构自然五花八门。正确的做法是在系统提示词里明确角色、输出协议和禁止事项。SYSTEM_PROMPT 你是一个模型治理工程师的助手。你的任务是根据用户提供的结构化模型元数据生成一份可直接发布的模型卡片。 硬性要求 1. 只能使用用户提供的事实禁止编造任何指标、版本、日期和数据集信息。 2. 使用中文写作格式为 Markdown。 3. 必须包含以下七个章节顺序不能改变 - 模型详情 - 预期用途 - 训练数据 - 评估方法 - 量化评估结果 - 伦理与公平性考量 - 注意事项和推荐建议 4. 元数据中缺失的信息写“未提供”不要猜测。 5. 不要输出用户提问的复述不要输出客套语直接输出模型卡片内容。 注意最后一条。LLM 经常会在正文前输出好的根据你提供的元数据我生成了以下模型卡片这些内容在自动发布场景里非常碍事必须在系统提示词中明确禁止。4.2 用户提示词把结构化数据转成文本输入用户提示词相对简单核心是把 JSON 元数据完整放入上下文。这里需要注意 JSON 转义问题。在 Python 中使用json.dumps序列化字典并设置ensure_asciiFalse避免中文字符被转成\uXXXX。import json def build_user_prompt(metadata: dict) - str: metadata_json json.dumps(metadata, ensure_asciiFalse, indent2) return ( 请根据下面的结构化模型元数据生成模型卡片。\n 元数据内容如下\n\n f{metadata_json} )如果元数据量很大可以考虑把不参与文本生成的字段在加载时就剔除只保留必要字段。这样既能缩短上下文又能减少 LLM 被无关字段干扰的概率。4.3 采样参数如何设置调用 LLM 时有三个参数需要重点调整。temperature控制随机性。生成模型卡片不适合创造性表达建议设置在 0.1 到 0.3 之间避免同一份元数据生成两次结果差异过大。max_tokens控制最大生成长度。模型卡片通常有 1000 到 2000 字再算上 Markdown 符号建议设置在 2000 到 3000。如果设置过小输出会被截断章节不完整。response_format如果服务支持可以设置为 JSON 模式但在直接生成 Markdown 的方案里不需要。下面的调用示例使用 OpenAI 兼容接口from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyempty ) response client.chat.completions.create( modelqwen2.5-7b-instruct, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: build_user_prompt(metadata)} ], temperature0.2, max_tokens2500 )代码里的端点和模型名是示例。实际项目建议把base_url、api_key、model都放到环境变量中避免每次更换模型都要改代码。5. 核心代码从 JSON 到 Markdown 的完整链路5.1 主脚本读取元数据并调用生成接口下面实现一个完整的generate.py。它负责四件事读取元数据、构造提示词、调用 LLM、保存输出。import os import json import pathlib from openai import OpenAI from generator.prompt import SYSTEM_PROMPT, build_user_prompt from generator.validator import validate_model_card def load_metadata(path: str) - dict: with open(path, r, encodingutf-8) as f: return json.load(f) def generate_model_card( metadata: dict, output_path: str ) - str: endpoint os.getenv(LLM_ENDPOINT, http://127.0.0.1:8000/v1) api_key os.getenv(LLM_API_KEY, empty) model os.getenv(LLM_MODEL, qwen2.5-7b-instruct) client OpenAI(base_urlendpoint, api_keyapi_key) response client.chat.completions.create( modelmodel, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: build_user_prompt(metadata)} ], temperature0.2, max_tokens2500 ) content response.choices[0].message.content output_path pathlib.Path(output_path) output_path.parent.mkdir(parentsTrue, exist_okTrue) output_path.write_text(content, encodingutf-8) return content if __name__ __main__: metadata_path os.getenv(METADATA_PATH, metadata/sentiment_model.json) output_path os.getenv(OUTPUT_PATH, output/MODEL_CARD.md) metadata load_metadata(metadata_path) content generate_model_card(metadata, output_path) problems validate_model_card(content, metadata) if problems: for problem in problems: print(f[校验失败] {problem}) raise SystemExit(1) print(f模型卡片已生成{output_path})脚本在生成完 Markdown 后立即调用校验函数。如果校验失败直接以非零退出码结束。这个设计方便后续接入 CI校验不通过就不会生成最终产物。5.2 校验脚本检查章节完整性和关键指标最简单的校验脚本做两件事检查七个小节是否都存在检查元数据中的评估指标是否出现在生成的文本中。REQUIRED_SECTIONS [ 模型详情, 预期用途, 训练数据, 评估方法, 量化评估结果, 伦理与公平性考量, 注意事项和推荐建议 ] def validate_model_card(content: str, metadata: dict) - list[str]: problems [] for section in REQUIRED_SECTIONS: if section not in content: problems.append(f缺少章节[{section}]) eval_metrics metadata.get(evaluation, {}) for key, value in eval_metrics.items(): if isinstance(value, (int, float)) and str(value) not in content: problems.append(f评估指标 {key}{value} 没有出现在模型卡片中) return problems这里用字符串包含来校验数字是比较原始的方案。它的作用是抓漏项不能完全替代人工核对。更严格的方案会在后面第 8 节介绍让 LLM 先输出结构化 JSON再由模板渲染 Markdown。那样数字一致性可以从数据结构上保证。5.3 命令行运行方式写好脚本后通过命令行运行export LLM_ENDPOINThttp://127.0.0.1:8000/v1 export LLM_MODELqwen2.5-7b-instruct python -m generator.generate \ --metadata metadata/sentiment_model.json \ --output output/MODEL_CARD.md这里没有用argparse而是用环境变量传入路径。是为了让 CI 环境下更容易注入不同参数。如果要在本地多次调试也可以改成命令行参数两种方式都可以接受选择一致的风格即可。6. 运行验证用一份最小元数据生成模型卡片6.1 准备一份最小测试元数据为了验证链路先准备一份简单的元数据文件metadata/sentiment_model.json。内容不需要很复杂但必须覆盖模型信息、训练数据、评估指标三个核心部分。{ model_name: sentiment-classifier, model_version: 1.2.0, model_type: fine-tuned transformer, base_model: bert-base-chinese, task: text-classification, language: zh, training_data: { size: 120000, source: e-commerce review comments }, evaluation: { accuracy: 0.921, f1: 0.88 } }这份简化元数据缺少伦理考量等判断性信息正好可以在生成结果里看到 LLM 如何处理未提供的情况。6.2 预期输出结构运行脚本后output/MODEL_CARD.md应该是一份包含七个小节的完整 Markdown。格式大致如下# Model Card: sentiment-classifier ## 模型详情 该模型是一个基于 bert-base-chinese 微调的中文情感分类模型... ## 预期用途 主要适用于电商评论的正负面情感判断... ## 训练数据 训练数据来源为... ## 评估方法 评估指标采用 accuracy 和 f1... ## 量化评估结果 在测试集上的整体准确率为 0.921F1 值为 0.88... ## 伦理与公平性考量 当前元数据未提供分群评估结果因此无法对特定群体的表现差异进行完整分析... ## 注意事项和推荐建议 该模型仅针对电商评论场景训练在其他领域使用前需要额外验证...如果生成的文本中出现了0.921和0.88这两个数字但章节不完整校验脚本就会报错。这是一个设计合理的反馈闭环。6.3 生成后的质量检查清单脚本自动校验通过不代表文档可以直接发布。人工需要额外检查以下项目检查项通过标准检查方式章节完整性七个章节全部存在且顺序正确校验脚本数字一致性所有评估指标与元数据一致校验脚本 人工抽查语言可读性无客套语、无重复段落、无未替换占位符人工阅读假设合理性预期用途和局限性描述符合业务实际算法负责人确认数据敏感度没有泄露内部数据名或敏感样本发布前审阅这里的核心判断是自动生成负责快人工审阅负责准。两者缺一不可。7. 常见问题与排查路径7.1 输出格式混乱或章节缺失现象生成的 Markdown 里没有预期的二级标题或者出现了好的根据你提供的元数据等客套语。可能原因有三个系统提示词里没有明确禁止客套语温度设置过高导致输出风格不稳定max_tokens设置过小导致后半部分被截断。排查顺序建议从输入开始检查元数据是否加载完整字段是否为空。检查系统提示词是否明确列出了七个章节。检查max_tokens是否足够。检查温度是否大于 0.5如果是降到 0.2。解决方案给系统提示词增加不要输出与模型卡片无关的内容并将温度调整到 0.2 左右。如果问题仍然存在可以考虑使用 Few-shot 示例在消息序列中插入一组用户输入 理想输出作为示范。7.2 LLM 编造评估指标现象生成的模型卡片里出现了一个元数据中不存在的指标比如 accuracy 变成了 0.98而原始 JSON 里明明是 0.921。这是最严重的问题通常被称作幻觉。LLM 在开放生成时会根据训练语料中的概率补全内容尤其当元数据字段较少时它更容易自行想象。应对方式有三层。第一层在系统提示词中增加数字只能来自元数据禁止修改。第二层用校验脚本把关键数字回查一遍比如检查0.921是否出现在生成结果中。第三层更彻底的做法是改变生成方式让 LLM 只负责生成描述性文本所有数值由程序从元数据填充到模板中。这就是第 8 节要讲的模板缝合方案。7.3 输出被截断现象生成的 Markdown 到量化评估结果章节就结束了后面两个章节完全缺失。可能原因max_tokens设置过小或者单个 token 对应的中文字数较多时输出长度超出限制。排查方式查看 API 返回的finish_reason。如果等于length说明是长度被截断如果等于stop说明是模型自然结束。解决方案把max_tokens从 1500 提升到 3000。如果输出内容包含大量表格也可以考虑按章节拆分生成每个章节独立调用一次 LLM最后合并。7.4 Markdown 表格渲染异常现象生成的卡片中包含表格但表格列数不一致或者在本地预览时出现错位。可能原因LLM 对中英文混排表格的列宽处理不稳定偶尔会多出或漏掉一个分隔符。解决方案如果业务上不强制要求表格可以要求 LLM 用列表代替表格。如果必须有表格可以在系统提示词中给出一个固定的表格模板让 LLM 只填行内容。下面是排查链路汇总建议作为团队内部文档发布问题现象可能原因检查方式处理建议输出有客套语提示词未禁止查看输出开头系统提示词增加约束章节缺失max_tokens 不足查看 finish_reason调大 max_tokens数字被篡改模型幻觉校验脚本比对模板填充 人工审阅表格错位列数不一致本地预览用列表代替表格或固定模板8. 从脚本走向生产模板缝合与人工审阅8.1 更稳健的做法让 LLM 输出 JSON再渲染 Markdown直接让 LLM 生成 Markdown 的优点是简单缺点在于格式和内容耦合在一起一旦输出不规范后期处理很麻烦。生产环境推荐一种更稳健的方式两步生成。第一步让 LLM 根据元数据输出结构化 JSON字段由我们预先定义例如{ model_details: 模型描述文本, intended_use: 预期用途说明, training_data: 训练数据说明, ... }第二步程序读取这个 JSON用 Jinja2 或普通字符串模板渲染成最终 Markdown。这样有几个好处数字字段可以直接从元数据中注入不经过 LLM 手写格式由模板统一控制不会因为 LLM 状态差异而出现结构漂移校验脚本只需要检查 JSON Schema 是否合法比检查 Markdown 字符串可靠得多。8.2 生产环境还需要什么一个可用的自动生成脚本距离生产环境落地还有一段距离。至少还需要考虑下面几点。第一日志和审计。每次生成都应该记录模型版本、元数据哈希、LLM 模型名称、生成耗时方便事后回溯问题。第二人工审阅流程。模型卡片最终要通过评审才能发布。推荐用 Git 管理输出文档生成后由算法负责人提交 PR审阅通过后合并到发布分支。第三安全与权限。如果元数据包含敏感信息需要配置严格的访问权限。调用外部 API 时所有输入必须经过脱敏或过滤。第四异常处理。LLM 接口可能超时、限流、返回空内容。脚本要做重试和熔断不要把一次失败的生成结果直接写入正式文档。8.3 扩展方向这套链路可以往多个方向扩展。接入 CI在训练流程结束后自动运行生成脚本把新的模型卡片提交到代码仓库。适合模型频繁迭代的团队。多模型对比同一份元数据可以并行使用多个 LLM 生成多个版本由评审人员选择最优版本或者拼接不同模型的优点。RAG 增强如果模型卡片需要引用数据集文档、伦理审查意见可以先把这些资料向量化生成时检索相关片段再放入提示词减少 LLM 的幻觉概率。多语言版本中文模型卡片生成后可以让 LLM 翻译成英文版本但翻译结果同样需要人工审阅因为术语和业务限制不能丢。9. 可复用的发布前检查清单最后整理一份可以直接复制到团队文档中的检查清单。每次生成模型卡片时按这个顺序过一遍。元数据准备模型版本、数据集版本、训练配置、评估指标都是最新值并且有生成时间。提示词检查系统提示词明确禁止编造数字章节列表完整温度低于 0.3。输出校验七个章节全部存在所有关键指标都出现在卡片中无客套语和重复段落。敏感信息检查没有出现内部业务名称、未脱敏样本、非公开数据集名称。人工审阅重点审阅预期用途伦理与公平性考量注意事项这三部分不能只依赖 LLM。版本管理生成的模型卡片打上版本号记录生成命令、LLM 模型和审阅人。发布确认使用该模型卡片的下游团队确认内容与实际模型一致。模型卡片的自动生成不是把人工写文档这个环节消灭掉而是把机械劳动交给脚本把需要判断的内容留给工程师。落到自己的项目时建议先从一份最小元数据 JSON 开始跑通一条链路再把校验逐步加严。这个过程本身和训练模型一样值得投入。