发布模型时最容易被忽视但又不该跳过的一步是写 Model Card。之前处理模型交付一张模型卡经常要反复补充指标、训练数据、使用限制还要统一格式。后来尝试用大语言模型LLM自动生成 Model Card整个流程节省了大量时间。这篇教程会完整拆解我的实践过程Model Card 是什么、为什么要用 LLM 生成、整体流程怎么设计、代码怎么写、以及生产环境落地时需要注意哪些问题。如果你正在做模型资产管理、平台开发或者希望把模型文档工程化这篇文章可以给你一套可上手的思路。即使你现在只是用现成大模型 API也能从零构建一个最小可用的 Model Card 生成器。1. Model Card 是什么为什么要自动化生成1.1 Model Card 的定义与组成Model Card 可以理解成模型的一份“说明书”或“简历”。它用结构化方式记录模型的核心信息让使用方能够快速判断“这个模型能不能用、什么时候不能用”。虽然不同团队定义的字段不同但通常包含以下模块模型概述模型名称、版本、任务类型、基础架构。预期用途适合哪些场景不适合哪些场景。训练数据数据来源、数据规模、预处理方式。评估结果在测试集上的准确率、召回率、F1 等指标。局限性与风险已知短板、偏见风险、对特定群体的影响。使用建议阈值选择、二次校验方式、部署注意事项。Model Card 和 README 不同。README 更多面向开发者讲的是怎么安装、怎么调用Model Card 更多面向使用者、审计者和业务决策者讲的是模型行为边界。1.2 手工编写 Model Card 的痛点在我接触过的团队里手工写 Model Card 往往存在四个问题。第一信息分散。模型信息散落在训练代码、日志、实验平台、论文和沟通记录里要收集齐全很费时间。第二格式不统一。有人写 Word有人写 Markdown有人直接在模型平台里填表单字段名称经常对不上。第三更新滞后。模型迭代很快调一次参、换一次数据旧模型卡的指标就失效了。第四人工成本高。写一张完整模型卡至少需要半小时到一小时如果模型很多这个工作量会迅速膨胀。1.3 LLM 在 Model Card 生成中的定位用 LLM 生成 Model Card目的不是完全替代人工而是把“从散落信息到初稿文档”这一步自动化。LLM 擅长两件事一是理解自然语言文本抽取关键信息二是按照模板输出结构化的 Markdown。合适的做法是让 LLM 生成初稿再由人工审核修订。这里要特别强调一个边界LLM 可能产生“幻觉”也就是编造看起来合理但不存在的信息。因此在生成流程里必须对结果做字段校验和事实核对不能直接把输出当作最终交付物。2. 技术方案设计LLM 自动生成 Model Card 的整体流程2.1 整体流程拆分在写代码之前先明确一个最小可行流程。整个自动生成过程可以拆成六步收集模型相关素材模型配置文件、README、训练日志、评估报告。整理结构化输入把素材中的关键字段抽取成 JSON 或文本块。设计 Prompt 模板告诉 LLM 需要输出的 Model Card 结构和格式。调用 LLM API把 Prompt 发送给大模型得到 Markdown 输出。校验输出结果检查必填字段、格式、敏感信息。人工审核发布算法负责人确认指标和局限性描述准确后发布。这六步只依赖一个 LLM API 和少量 Python 脚本适合作为起点。后续可以扩展成基于 RAG 的检索增强生成或者接入 Agent 编排框架。2.2 输入信息收集与预处理要把模型卡生成做得稳定不能直接丢给 LLM 一堆杂乱文本最好先提供一个规范化的输入。我的做法是准备一份 JSON 文件包含模型的关键元信息。{ model_name: text-classifier-v1, model_version: 1.0.0, task_type: 文本分类, base_model: bert-base-chinese, training_data: { source: 电商评论脱敏数据, size: 120000, description: 包含商品评论和人工标注的情感标签 }, evaluation: { accuracy: 0.92, f1: 0.89, test_set_size: 8000 }, limitations: [ 对口语化文本存在误判, 数据集中负面评论占比较高可能导致负面偏差 ], intended_use: 用于电商平台售后工单的初步情感判断 }这段 JSON 就是 LLM 生成 Model Card 的信息源。如果你们团队的配置是 YAML也可以先转成 JSON。关键是把字段统一方便后续读取和填充 Prompt。2.3 Prompt 模板设计Prompt 是自动生成 Model Card 的核心。我倾向于使用“结构指引 原始信息 输出要求”三段式。你是一位机器学习平台文档工程师。请根据下面的模型信息生成一份 Model Card使用 Markdown 格式。 要求 - 包含模型概述、预期用途、训练数据、评估结果、局限性与使用建议六个板块。 - 所有指标和描述必须严格来自输入信息禁止编造。 - 如果输入信息缺失请在对应位置标注“待补充”。 - 语言保持简洁直接。 模型信息 {model_info}这里使用{model_info}作为占位符。实际执行时可以把上一步的 JSON 序列化后填充进去。为了让输出更稳定我会要求模型“缺失位置标注待补充”这比让模型自己推理更安全。2.4 结果校验方法LLM 输出后不能直接保存。我会写一个简单的校验函数至少检查三件事是否包含六个必需板块。是否出现“待补充”以外的异常占位符。是否包含敏感词例如接口密钥、内网地址、未脱敏的用户ID。校验不通过就重新请求一次或者进入人工处理队列。3. 环境准备与版本说明3.1 运行环境说明本文示例使用 Python 3.9 及以上版本主要依赖openai库和python-dotenv。这些库的版本不需要刻意固定建议在项目里使用虚拟环境隔离依赖。另外本文使用“OpenAI 兼容接口”作为示例。你可以把API_BASE指向任何兼容接口的大模型服务常见的有本地部署的 vLLM、各类云厂商的模型服务等。具体配置项会因服务商不同而有差异需要按实际情况调整。3.2 安装依赖先在项目根目录创建requirements.txtopenai1.0.0 python-dotenv1.0.0执行安装命令pip install -r requirements.txt如果你不想使用openai库也可以直接用requests库做 HTTP 调用。示例代码会尽量保留最小依赖方便你迁移。3.3 项目结构建议建议按下面的结构组织项目model-card-generator/ ├── data/ │ └── model_info.json ├── prompts/ │ └── model_card_template.txt ├── scripts/ │ └── generate_model_card.py ├── output/ └── .envdata/存放模型元信息。prompts/存放 Prompt 模板方便后续做模板版本管理。scripts/存放生成脚本。output/存放生成的 Model Card。.env存放 API Key 等机密信息不能提交到 Git。4. 核心代码实现4.1 读取模型信息首先封装一个读取 JSON 的函数。这样生成脚本只关心数据不关心文件路径。# 文件路径scripts/generate_model_card.py import json import os from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent def load_model_info(json_path: str) - dict: 读取模型元信息 JSON 文件。 with open(json_path, r, encodingutf-8) as f: return json.load(f)这个函数返回一个字典后续填充 Prompt 时会用到。4.2 读取 Prompt 模板并填充内容这里有一个小坑。如果 Prompt 模板使用 Python 的str.format()Markdown 里的大括号{}会与格式化语法冲突。为了避免这种问题我使用最简单的replace()方法填充占位符。先创建一个模板文件prompts/model_card_template.txt你是一位机器学习平台文档工程师。请根据下面的模型信息生成一份 Model Card使用 Markdown 格式。 要求 - 包含模型概述、预期用途、训练数据、评估结果、局限性与使用建议六个板块。 - 所有指标和描述必须严格来自输入信息禁止编造。 - 如果输入信息缺失请在对应位置标注“待补充”。 - 语言保持简洁直接。 模型信息 __MODEL_INFO__模板中使用__MODEL_INFO__作为占位符这样不会与 Markdown 语法冲突。然后写填充函数def build_prompt(model_info: dict) - str: 读取模板并将模型信息填充到占位符中。 template_path BASE_DIR / prompts / model_card_template.txt with open(template_path, r, encodingutf-8) as f: template f.read() model_info_text json.dumps(model_info, ensure_asciiFalse, indent2) prompt template.replace(__MODEL_INFO__, model_info_text) return prompt注意ensure_asciiFalse可以保留中文字符方便模型理解。4.3 调用 LLM API 生成 Model Card在.env文件中配置 API 信息LLM_API_KEYyour_api_key LLM_API_BASEhttps://your-llm-service.example.com/v1 LLM_MODELyour-model-name然后实现调用函数。这里使用openai库的 OpenAI 兼容接口方式。from openai import OpenAI from dotenv import load_dotenv load_dotenv(BASE_DIR / .env) client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_API_BASE), ) def generate_model_card(prompt: str) - str: 调用 LLM 生成 Model Card Markdown 内容。 response client.chat.completions.create( modelos.getenv(LLM_MODEL), messages[ {role: system, content: 你是一个严谨的模型文档生成助手。}, {role: user, content: prompt}, ], temperature0.2, max_tokens2048, ) return response.choices[0].message.content这里有几个参数值得说明temperature0.2降低随机性让输出更稳定更贴近模板要求。max_tokens2048限制输出长度避免模型生成过长或截断。system消息给模型一个角色设定有助于约束输出语气。如果你使用的是其他大模型平台只需要调整api_key和base_url大多数情况下代码结构不变。4.4 校验输出并保存 Markdown生成完内容后写一个最小校验函数def validate_output(content: str) - bool: 检查生成的 Markdown 是否包含必需板块。 required_sections [ 模型概述, 预期用途, 训练数据, 评估结果, 局限性, 使用建议, ] return all(section in content for section in required_sections) def save_output(content: str, model_name: str) - Path: 将内容保存到 output 目录。 output_dir BASE_DIR / output output_dir.mkdir(exist_okTrue) output_path output_dir / f{model_name}_MODEL_CARD.md with open(output_path, w, encodingutf-8) as f: f.write(content) return output_path保存文件时使用模型名称作为文件名方便多个模型文件管理。4.5 组装主流程并运行最后把主流程串起来def main(): info_path BASE_DIR / data / model_info.json model_info load_model_info(str(info_path)) prompt build_prompt(model_info) result generate_model_card(prompt) if not validate_output(result): print(校验失败缺少必需板块) return output_path save_output(result, model_info[model_name]) print(fModel Card 已生成{output_path}) if __name__ __main__: main()运行命令cd model-card-generator python scripts/generate_model_card.py如果一切正常你会在output/目录下看到一个text-classifier-v1_MODEL_CARD.md文件。文件内容大致包含六个板块所有指标都来自model_info.json。如果模型信息中缺少某个字段LLM 应该会输出“待补充”。5. 进阶基于 RAG 的自动化 Model Card 生成5.1 为什么需要 RAG上面的示例依赖一份手工整理好的 JSON。如果项目资料很多例如有几十页实验报告、多个 README、不同版本的训练配置人工先整理 JSON 仍然很耗时。这时可以引入 RAGRetrieval-Augmented Generation检索增强生成。RAG 的核心思路是先把模型相关资料切分成小块转换成向量存入向量数据库用户提问或需要生成 Model Card 时先在知识库中检索最相关的片段再把这些片段和 Prompt 一起交给 LLM。这样既能提升生成内容的事实性也能支持长文档输入。RAG 在模型卡生成场景中的价值在于它能把“理解整个项目文档”这个任务拆解为“检索相关片段 按模板生成”两个子任务降低 LLM 处理超长文本的压力。5.2 一个简单的检索思路实现在引入完整向量库之前你可以先用关键词检索模拟一下效果。下面的例子演示如何从多个文本片段中根据关键词挑选与“评估”“训练数据”相关的内容。# 伪代码示例仅用于演示检索思路 documents [ {title: 训练数据说明, content: 使用了120000条脱敏电商评论}, {title: 评估报告, content: 准确率0.92F1 0.89}, {title: 部署说明, content: 建议使用GPU部署}, ] query 评估结果 scored_docs [] for doc in documents: score 0 if query in doc[title]: score 2 if query in doc[content]: score 1 scored_docs.append((score, doc)) top_docs sorted(scored_docs, keylambda x: x[0], reverseTrue)[:2] for score, doc in top_docs: print(doc[title], doc[content])这个示例虽然简单但能说明检索的核心找到与目标字段最相关的文本。生产环境建议使用向量检索例如text-embedding模型配合向量数据库可以处理语义相似但关键词不一致的情况。5.3 Agent 编排扩展当 Model Card 生成流程变得更复杂时可以考虑引入 Agent 编排框架。常见做法是用一个 Agent 负责读取模型目录。用一个 Agent 负责检索实验记录。用一个 Agent 负责生成 Markdown。最后用校验 Agent 检查输出。很多 LLM 应用编排框架都支持这种多步骤流程例如 LangChain、Spring AI以及基于 MCP 的工具链。它们的作用是让每一步可以被追踪、重试和替换。开始阶段不建议过度设计先用最简单的脚本跑通再逐步加入编排能力。6. 常见问题与排查思路6.1 常见问题汇总问题现象常见原因解决思路生成结果缺少部分板块Prompt 约束不明确或模型输出被截断增强 Prompt 要求提高max_tokens指标与输入不一致LLM 幻觉或上下文理解错误在 Prompt 中强调“严格引用输入信息”增加校验Markdown 格式不稳定模型对格式理解波动使用temperature降低随机性后处理补充标题调用 API 超时网络或服务端负载问题增加重试机制设置合理超时时间敏感信息泄露输入数据未脱敏在上游做敏感信息过滤输出侧再做一次检查6.2 生成内容包含虚假信息这是最需要警惕的问题。如果 Model Card 里出现模型本身没有的准确率发布后可能造成误导。建议从三方面控制Prompt 明确要求“只使用输入信息不推测不编造”。校验脚本对比输出中的数值与原始 JSON 中的数值发现不一致就标记为高风险。建立人工复核流程模型卡发布前必须经过算法负责人确认。如果模型信息确实缺失宁可标注“待补充”也不要让模型自行猜测。6.3 输出格式和模板不对齐LLM 在少量样本下很容易输出多种 Markdown 风格。解决方式有两种。一种是在 Prompt 中给出一个极简示例让模型模仿格式另一种是后处理解析把输出切分成段落再根据标题重新映射到标准模板。第二种更稳定但代码量会增加。初期建议先让 Prompt 多约束后期再根据实际需求添加解析逻辑。6.4 API 调用失败和超时在自动化流程中API 调用失败是常态不能只做一次请求。建议加入重试机制并设置超时时间。import time def generate_model_card_with_retry(prompt: str, retry_times: int 3): last_exception None for attempt in range(retry_times): try: return generate_model_card(prompt) except Exception as e: last_exception e time.sleep(2 * (attempt 1)) raise last_exception重试时使用递增的等待时间避免频繁请求给服务端造成压力。7. 最佳实践与工程建议7.1 Prompt 模板纳入版本管理Prompt 是生成质量的关键。Prompt 一旦改动生成结果可能变化很大。建议把prompts/目录纳入 Git 管理并在模板头部标注变更原因。这样后续某个模型卡生成效果变化时可以回溯到具体版本。7.2 输入信息与输出结果可追溯每张生成的 Model Card 都应该记录来源。一个简单做法是在输出文件头部加入源信息注释例如输入 JSON 路径、LLM 模型名、生成时间。 来源data/model_info.json 生成模型your-model-name 生成时间2025-06-01 10:00:00这样即使后续内容被修改也能知道原始生成背景。7.3 强制字段校验与变更审批关于模型信息的修改要谨慎。建议在保存 Model Card 前先执行校验脚本再走一次变更审批。特别是涉及准确率、训练数据来源、隐私风险等关键字段时一定要有人为确认。7.4 敏感信息过滤模型训练数据中可能包含用户信息或内部系统信息。在生成 Model Card 前要对输入文本做脱敏比如使用正则替换邮箱、手机号、内网 IP 等。输出侧同样要检查一次防止模型把敏感片段原样输出。7.5 本地部署时的精度选择如果你使用本地部署的 LLM 做模型卡生成会面临显存和生成质量的平衡。常见做法是使用半精度fp16 或 bf16加载模型减少显存占用。对于文本生成任务一般影响不大。如果追求更稳定的输出质量可以结合具体模型选择合适的精度格式。这个环节根据你的推理引擎和显卡驱动灵活调整不需要死记参数。7.6 持续更新机制模型迭代后Model Card 不能自动过时。建议在模型发布流水线中增加“生成 Model Card”这一步每当模型配置变更或评估指标更新就触发重新生成。这比手动维护更可靠也能避免模型已经发布、文档还停留在旧版本的情况。8. 总结与实践建议这次实践的核心并不是“用 LLM 写文档”这个动作本身而是建立一条“信息收集 — Prompt 约束 — 结果校验 — 人工审核”的文档生产链路。即使后续替换模型、增加字段、接入 RAG骨架仍然可以复用。如果你正准备在团队里推行建议先选一个最常见的模型手工整理一份model_info.json跑通最小脚本再逐步扩展检索和 Agent 能力。有了第一张自动生成的 Model Card后续优化方向就会更清晰。模型文档这件事少做一次两次看不出差别长期坚持下来对模型理解、复用和审计都会有很大帮助。也欢迎你把实践过程中遇到的问题留在评论区一起交流。