模型卡（Model Card）是机器学习模型发布时最容易被跳过、又最不该跳过的一份文档。很多团队训练完模型，日志有了，评估指标有了，代码仓库也收拾好了，唯独模型卡一直没人写，最后上线前只能临时补一段。用 LLM 自动生成模型卡，就是把模型名称、任务类型、训练数据、评估指标、限制条件和预期用途这些元信息结构化之后，交给大语言模型统一排版、补全和规范化。这篇文章我按自己实测过的流程拆一遍：先说明它解决什么，再给你一套能直接改的输入模板和提示词，然后讲批量生成和排查思路。适合要提交模型仓库、做团队内部资产沉淀，或者经常要把模型交接给下游工程师的人看。
1. 自动生成模型卡到底解决什么问题
1.1 模型卡在真实项目里为什么总是被跳过
一个模型从训练到上线，涉及的产出通常有：模型权重文件、推理代码、训练日志、评估脚本、README。模型卡往往被塞在 README 的最后一段，写着“某模型，准确率多少，没了”。问题在于，真正接手模型的工程师需要知道的不只是准确率。他要清楚这个模型在什么数据上训练过，分布是什么，适合在哪些场景用，遇到什么输入会失效，能不能处理长文本，输出格式是否稳定，许可证是什么。
模型卡的价值就是把“模型是什么、能用在哪、不能用于什么”说清楚。但大多数人不是不愿意写，而是不知道写什么。一个模型训练完之后，信息散落在各种地方：训练配置在 YAML 里，指标在 log 里，数据说明在文档里，许可证在仓库目录里。要把这些信息汇总成一份规范的自然语言文档，非常花时间。这时候让 LLM 按固定模板做汇总和补全，效率会高出很多。
1.2 用 LLM 生成模型卡，比传统模板好在哪
传统做法是给一份 Markdown 模板，让工程师自己填。模板的好处是结构统一，坏处是填表体验极差。尤其是字段多、可写可不写的时候，大部分人会跳过自己不确定的部分。LLM 自动生成模型卡的自由度更大，但前提是要给它足够明确的约束。
实测下来，LLM 生成模型卡最明显的优势有三个。第一，能根据同一份结构化输入生成不同长度的版本，比如短版放进 README，完整版提交模型仓库。第二，能自动把指标表达规范化，避免“acc=0.91”“91%准确率”“accuracy 91.2%”同时出现。第三，能根据模型用途自动补齐容易遗漏的局限性描述，比如某个分类模型在特定人群样本上表现不稳定，LLM 可以把它写进“限制与建议”。
但这里要划一条边界：LLM 可以做排版、归纳、措辞规范化，不能编造数据和结论。它只能基于你给的元信息生成，如果某个指标缺失，就应该写“未提供”，而不是猜测一个数字。
1.3 适合哪些场景，不适合哪些场景
适合的场景非常明确：
- 训练脚本和模型输出已经标准化，模型元信息能从配置文件和日志里自动汇总。
- 团队里有多个人维护同一个模型仓库，需要保持模型卡格式统一。
- 模型要提交到类似 Hugging Face 这类平台，有固定的模型卡字段要求。
- 需要给多个模型批量生成说明文档。
不适合的场景也需要注意：
- 如果模型还没有任何评估指标，或者数据来源不清晰，先不要生成，先把信息补全。
- 如果模型卡需要面向监管合规、医疗诊断、金融风控等严肃场景，LLM 只能生成初稿，必须人工复核。
- 如果只想要一段“好看的介绍”而不在乎真实性，那自动生成的模型卡只会把问题放大。
我一般会把这个过程定位成“模型文档的自动草稿器”，而不是“最终审核员”。它能帮你把文档从无变成有，从乱变成规整，但最后一道闸门还是人。
2. 先把模型信息整理成结构化输入
2.1 模型卡必备字段怎么拆
要让 LLM 生成一份可用模型卡，第一件事不是写提示词，而是先确定输入字段。最怕的是把一段自由写的训练日志直接丢给 LLM，让它“看着办”。这样生成的模型卡可能很好看，但信息密度很低，甚至会出现幻觉。
我自己整理的一套核心字段如下：
| 字段 | 说明 | 是否必填 |
|---|---|---|
| model_id | 模型唯一标识，建议用仓库名或文件名 | 必填 |
| model_name | 展示用的模型名称 | 必填 |
| task | 任务类型，比如文本分类、命名实体识别、图像分割 | 必填 |
| framework | 训练框架或推理框架 | 可选 |
| dataset_name | 训练数据集名称 | 必填 |
| dataset_description | 数据规模和构成说明 | 强烈建议 |
| training_config | 训练参数，如学习率、epoch、batch size | 可选 |
| input_format | 输入格式，如文本、图片尺寸、上下文长度 | 必填 |
| output_format | 输出格式，如类别标签、JSON、概率分数 | 必填 |
| metrics | 评估指标，要写清指标名和数值 | 必填 |
| limitations | 已知限制和失效场景 | 建议 |
| license | 模型许可证 | 必填 |
| intended_use | 预期用途 | 建议 |
| update_date | 更新日期 | 可选 |
这些字段不一定一次都齐。实际项目里，最常见的是指标缺单位、数据集描述一句话带过、许可证放在仓库根目录没人读。所以第一步是把已有信息先落一个 JSON。
2.2 一份可复用的 JSON 输入模板
我建议先建立一个model_meta/目录，里面每个模型一个 JSON 文件，命名方式就是{model_id}.json。这样后续不管是跑单条脚本还是一批任务，输入都非常稳定。下面是一个示例：
{ "model_id": "text_classifier_v1", "model_name": "短文本分类模型 V1", "task": "文本分类", "framework": "PyTorch", "dataset_name": "客服工单分类数据集", "dataset_description": "约 10 万条客服工单，覆盖 8 个分类，文本长度大多在 200 字以内。", "training_config": { "learning_rate": 2e-5, "epoch": 3, "batch_size": 32 }, "input_format": "中文短文本，长度不超过 256 字", "output_format": "JSON 对象，包含 label 和 confidence 字段", "metrics": { "accuracy": 0.923, "macro_f1": 0.901 }, "limitations": "对含大量表情符号和方言的工单识别效果较差。", "license": "MIT", "intended_use": "用于客服工单的自动分类与流转，需要人工确认高置信度结果。", "update_date": "2025-03-20" }注意，这里的指标值只是示例，实际要以你自己的评测结果为准。我把这个 JSON 作为最小输入模板。如果暂时没有training_config，可以不填，但metrics和input_format尽量不要缺。缺少这两个字段，生成的模型卡基本没有实用价值。
2.3 为什么先从结构化输入开始，而不是直接让 LLM 猜
这个问题我踩过坑。第一次尝试的时候，我觉得 LLM 能力很强，直接把训练脚本的注释、日志片段和 README 混在一起丢进去，让它生成模型卡。结果是文字非常通顺，但关键指标被写错，数据集规模也被莫名其妙放大了。原因很简单：自由文本里的信息没有统一 schema，LLM 在提取和推断之间的边界处理不好。
结构化 JSON 输入的作用是减少歧义。LLM 不需要去理解一段日志里哪个数值是 loss、哪个数值是 accuracy，你直接在 JSON 里标清楚。它只需要做排版、解释和补全表述。这样生成的内容在事实层面更可靠。
尤其当你面对多个模型的时候，统一 schema 的价值更大。你可以写一个校验脚本，检查每个模型 JSON 是否包含必填字段，没有就打印警告。这样在调用 LLM 之前就能过滤掉一批输入错误，而不是等生成完才发现输出里出现“未提供”。
3. 跑通单次生成的完整流程
3.1 环境准备
在做自动生成模型卡之前，先确认自己的调用环境能不能正常工作。这里不需要多复杂，核心是能调用一个 LLM 服务。无论你用的是本地部署的开源模型，还是通过 HTTP 接口访问的远端服务，只要能提供“输入文本、返回文本”的能力就行。
一个比较通用的做法是使用 OpenAI 兼容的接口格式。你可以先用curl或者 Python requests 做一次最小测试，确认接口地址、模型名称和密钥配置正确。下面是一个简化版的 Python 调用示例：
import requests import json API_URL = "http://localhost:8000/v1/chat/completions" API_KEY = "your-api-key" MODEL_NAME = "your-model-name" def generate_model_card(model_info_json: dict, prompt_template: str) -> str: payload = { "model": MODEL_NAME, "messages": [ {"role": "system", "content": "你是一个专业的机器学习文档工程师。"}, {"role": "user", "content": prompt_template.format(model_info_json=json.dumps(model_info_json, ensure_ascii=False, indent=2))} ], "temperature": 0.2, "max_tokens": 800 } headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } resp = requests.post(API_URL, headers=headers, json=payload, timeout=30) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"]这段代码不能直接复制就跑，API_URL、API_KEY、MODEL_NAME都要换成你自己的。如果你用的是本地推理框架，通常也不需要 API Key，但超时时间、并发上限是另一个要确认的点。
3.2 最小提示词模板
提示词不需要写得像论文一样长，但必须把要求和边界说清楚。我常用的是一个比较收敛的模板：
根据下面的模型元信息，生成一份模型卡。 要求： 1. 使用 Markdown 格式，包含以下章节：模型简介、预期用途、训练数据、评估结果、局限性、使用建议。 2. 只描述元信息里出现的内容，不要编造数字或结论。 3. 未提供的字段，统一写“未提供”。 4. 评估结果里要写清指标名和具体数值。 5. 使用客观、面向工程接手的语气。 模型元信息： {model_info_json}这个模板有两个关键点。第一，它限定了章节结构，避免 LLM 自由发挥出五个不一样的标题。第二，它明确要求“未提供”标注，这样缺失的信息不会被悄悄隐藏。我在多次测试里发现，加上“不要编造”这一句后，输出里的幻觉数据明显减少，但不是完全没有，仍需人工核对。
3.3 调用与验证
先不要写复杂循环，先跑一个模型。用你手头信息最全的那个 JSON 文件去测。调用成功之后，打印返回结果，把输出保存成model_card_<model_id>.md。然后打开这个文件，重点检查：
- 是否包含模型 ID 和任务类型。
- 指标数值是否和输入 JSON 一致。
- 未提供的字段是否被标注。
- 有没有出现输入里不存在的数字、论文引用、数据集来源。
- 章节结构是否统一。
如果第一次生成的结构不理想，不要急着改温度参数，先调提示词。比如你发现“预期用途”写得太宽泛，可以在要求里加一句“预期用途需要结合 task 和 input_format 具体描述，不要写成通用套话”。
3.4 判断生成结果是否可用的标准
我习惯把生成结果分成三档：
| 质量等级 | 判断标准 | 处理方式 |
|---|---|---|
| 可用 | 字段齐全、指标正确、章节完整 | 归档 |
| 需要微调 | 个别标题不统一，措辞太泛 | 调整提示词后重新生成，或人工修改 |
| 不可用 | 指标被改、数据被编造、章节缺失严重 | 检查输入和提示词，必须重新生成 |
不要被“生成速度很快”带偏。宁可多花十秒钟检查指标，也不要让一份带幻觉的模型卡进入仓库。
4. 批量生成时的工程化处理
4.1 批量任务不是多循环几次
当一个模型目录里有二十个模型，另一个团队有八十个模型时，最容易犯的错误就是写一个for循环，把所有 JSON 文件依次丢给 LLM，然后开始等。表面上看没有问题，但实际生产环境里会出现三类情况：
- 某个 JSON 文件格式错误，解析到一半程序崩了，后面全部没生成。
- 某个请求超时，任务卡在中间，你根本不知道卡在哪里。
- 输出目录里混入乱命名的文件，后续难以自动归档。
更稳妥的做法是给批量任务加一个状态记录。我会在输出目录里放一个generation_status.csv，每一行记录一个模型的状态：pending、success、failed、review。脚本每次启动时先读取这个日志，只处理pending和failed的模型，这样即使中断了，也能从断点继续跑。
4.2 任务队列、失败重试和输出命名
批量生成模型卡需要三个额外组件，缺一不可：失败重试、请求频率控制和输出命名规则。
失败重试的逻辑很简单，但要注意重试次数。一次请求失败可能是网络抖动，三次连续失败大概率是接口、权限或输入格式问题。我一般设成最多重试 2 次，重试之间间隔 5 秒。如果 2 次之后仍失败，就把状态标记为failed，记录错误信息，不阻塞后续任务。
请求频率控制也要提前做。很多 LLM 服务有 QPS 限制，所以在循环里最好加一个time.sleep(0.5)或者使用简单的信号量控制并发数。刚跑批量时，建议先取前 3 个模型做小样本测试，确认接口稳定后再放开全量。
输出命名建议统一为model_card_<model_id>.md，不要用时间戳。时间戳会让后续 diff 变得很痛苦。模型卡是要进版本库的，命名不稳定会导致重复生成和覆盖。
4.3 增量更新与版本管理
模型卡不是一次性产出。模型更新后，指标会变，数据集会变，许可证也可能变。如果重新把整个模型卡生成一遍，会导致输出格式不稳定，甚至同一结构在两次生成里出现差异。
增量更新更合理。推荐做法是：当模型 JSON 发生变化时，只对变化的模型重新生成模型卡。同时把模型卡纳入 Git 版本管理，和模型权重、评估脚本一起提交。这样就能看到每次生成前后的 diff，便于 review。
我在实测中还会在模型卡开头加一行：
> 本文档由 LLM 自动生成初稿，最后人工审核日期：2025-04-01这一行能明确文档属性和人工复核状态。虽然看起来简单，但在多人协作时非常有用，能避免后面的人误以为整段文档都是权威结论。
4.4 资源占用和输出一致性检查
如果你用的是本地模型，批量生成时要注意显存和内存占用。常见问题是连续请求导致显存碎片或推理服务响应变慢。建议每处理 20 个模型后观察一次服务日志，看有没有超时或者内存持续上涨。
如果你用的是远端接口，要多关注返回内容的稳定性。同样参数下，连续两次生成同一个模型的模型卡，章节结构可能完全一致，但表述细节会有差异。这是 LLM 的固有特性，不是 bug。为了减少差异，我把temperature固定在 0.2 附近，而不是用默认值。默认值在不同服务里的定义不同，有些默认是 1.0，生成结果会偏发散。
5. 生成结果不理想时的排查链路
5.1 先看现象，不要急着改 prompt
自动生成模型卡出问题，第一反应往往是“提示词写得不好”。但实际排查时，我建议先看现象，再判断真正的问题在哪一层。常见现象有五种，每种对应的优先排查方向都不同。
| 现象 | 优先检查 | 常见原因 |
|---|---|---|
| 模型卡里字段是空的 | 输入 JSON | 字段没有传进去，或键名不一致 |
| 指标数值被改了 | 输入 JSON 和提示词 | 模型理解错误，提示词缺少“不要修改数字”约束 |
| 章节不完整 | 提示词和 max_tokens | 输出被截断，或提示词没有明确章节结构 |
| 生成内容泛化 | 提示词 | 没有写“结合 input_format 和 task 具体描述” |
| 请求失败或超时 | 接口、密钥、服务负载 | 网络不稳定、超时时间太短、并发过高 |
先对照这个表格定位，再动手改。不要一开始就堆提示词，那样问题反而被掩盖。
5.2 从输入、提示词、参数逐层排查
我的排查顺序是：先输入，再提示词，再参数，最后是服务本身。
输入 JSON 是最容易出问题的地方。最常见的是键名不一致，代码里用metrics，JSON 里写成了metric，结果 LLM 拿不到完整数据。这种问题在只跑一个模型时很难发现，因为模型卡里可能仍然生成了“评估结果”标题，只是内容是空的。
提示词的问题是第二层。如果输入已经完整，但生成结果还是泛泛而谈，那就要在提示词里加具体动作。例如写“根据 input_format 说明模型支持的输入长度和格式”，而不是只写“详细描述”。
参数问题主要看temperature和max_tokens。temperature太高容易让模型自由发挥，max_tokens太小会导致输出被截断。我一般设置temperature=0.2，max_tokens=800。如果你的模型卡包含很多章节，max_tokens可以放大到 1200，但不能无限大，要接服务端的限制。
最后看服务本身。连续批量请求时，接口偶尔返回 429 或 503，这是负载问题。加大重试间隔，或者降低并发，通常能解决。不要因为一次返回错误，就一直重复请求同一个输入，那样只是放大负载。
5.3 模型能力边界和人工复核
必须承认一个现实：不是所有 LLM 都擅长严格遵循格式约束。有些模型写长文本很强，但让它按固定章节输出 Markdown 时，会出现标题层级混乱、代码块嵌套错误、列表符号不统一的问题。
遇到这种情况，选型的优先级应该是：指令遵循能力 > 文本流畅度 > 输出长度。你不需要一个能写出华丽排比的模型，更需要它能按照模板输出稳定结构。如果你用的是本地小参数模型，生成效果不稳定，建议在模型卡生成任务里加入后处理脚本，比如用正则强制修正章节标题，或把输出解析成 JSON 再渲染成 Markdown。
人工复核不能省。我的习惯是生成后不直接合并到主分支，而是先提交到一个model-card-review分支，由熟悉模型的人检查指标和限制描述。LLM 在文档规范化上很省力，但如果连验证这一步都省了，那自动生成就会变成自动犯错。
6. 落地建议：从个人脚本到团队规范化
6.1 什么时候值得引入自动生成模型卡
如果你只是偶尔写一份 README，完全不需要引入这套流程。复制一个模板手写更快。但当你满足以下任一条件，就值得把自动生成做成一个小工具：
- 需要给十个以上模型维护模型卡。
- 模型上线前需要向其他团队做模型说明。
- 模型仓库要暴露给外部使用，文档结构要求统一。
- 训练任务频繁更新，模型卡需要跟着版本走。
不要追求一开始就做得很完整。可以先从命令行脚本开始，输入 JSON 目录，输出 Markdown 目录。跑通之后再加上失败记录、增量更新和人工 review 流程。
6.2 把生成环节嵌进现有训练管线
更进一步的落地方式是让模型卡生成成为训练流程的一部分。训练脚本结束后，把关键指标和配置写进model_meta/{run_id}.json，然后调用生成脚本产出模型卡初稿。这样做的好处是减少“事后补文档”的时间差。
我见过一个比较实用的流程：训练完成 → 评估脚本输出metrics.json→ 汇总脚本把配置文件、数据说明和指标合并成模型元信息 JSON → 调用 LLM 生成模型卡 → 手动复核 → 提交。整个链路每一步都只做一件小事，任何一个环节出问题都能单独定位。
这里需要提醒的是：不要为了自动化而把评估结果直接交给 LLM 原样输出。如果评估脚本里同时存在多个指标，一定要在汇总脚本里明确“最终生效指标列表”。否则 LLM 可能会把中间过程当成最终结果。
6.3 最后我建议保留的人工检查项
自动生成模型卡可以节省大量时间，但落地时我仍然会固定保留以下几项人工检查：
- 指标数值是否正确。
- 局限性描述是否和已知问题一致。
- 许可证、模型 ID 等关键字段是否拼写正确。
- 是否有幻觉内容，比如不存在的论文、数据集或性能数字。
- 章节标题是否符合团队或平台要求。
这个清单并不复杂，但能挡住大部分风险。尤其当团队里有人提问“这个模型为什么在特定输入上效果很差”时，模型卡里的limitations字段应该是提前写好的，而不是临时解释。
踩过几次之后我发现，很多自动生成流程的问题不是模型能力不够，而是输入信息和工程边界没有理清楚。模型卡生成这件事，本质上不是“让 LLM 写作文”，而是“把结构化的模型信息翻译成规范文档”。只要输入干净、提示词约束清楚、批量任务有状态记录，最后留一道人工审核，这套方案在团队里就能稳定跑起来。
