最近沃顿商学院教授 Ethan Mollick 关于 AI 实验室应该自写文档的观点在 AI 工程实践圈子里引起了不少讨论。这个观点表面上是针对大模型公司的发布流程但放到任何一家自研模型或深度定制模型的技术团队里它都指向同一个真正的问题最了解模型的人往往没有把这份理解转变成系统化的文档。等到下游开发者、评测人员或安全审计方开始使用模型时缺文档导致的偏差就会表现为错误集成、误用能力和风险误判。这篇博客不讨论行业博弈而是把这个呼吁翻译成一套可执行的工程方法模型卡、系统卡、评测报告、API 文档应该写什么写完怎么校验更新模型时怎么让文档跟得上又如何避免自写文档变成自说自话。文章会尽量贴近一线 AI 开发、模型部署和 AI 应用开发的真实场景适合算法工程师、AI 产品经理、技术文档工程师和负责模型发布流程的团队参考。1. 先理解 Ethan Mollick 的呼吁AI 文档为什么不能只靠外部机构写1.1 这个观点在讨论什么问题AI 实验室发布一个模型后通常都会附带技术报告、API 文档和模型卡但这些材料的质量差异很大。有些文档像宣传页只写优势能力不写失败案例和边界有些模型卡只是简单列出几个评测集上的得分完全不解释这些分数是在什么条件下得到的。Ethan Mollick 长期研究 AI 对组织与工作的影响他在公开场合多次强调 AI 透明度和可用性的关系。他呼吁 AI 实验室自己把文档写起来本质上是希望把模型能力的最终解释权从外部评测机构拉回模型开发方手里。这里需要澄清一点这个呼吁并不是否认第三方审计的价值。恰恰相反外部研究者、记者和审计机构可以做独立检验他们的存在本身就构成一种压力。但问题在于外部人接触到的模型往往是一个黑盒 API他们能看到的只是输入输出关系不是模型开发过程中的完整记录。一个负责任的 AI 实验室不能只依赖外部人替自己写说明因为最核心的上下文只在实验室内部外部人根本没有渠道获取。由此带来的工程启示是如果你的团队在自研模型、微调模型或封装第三方模型那么你同样不能把文档这项工作外包给评测机构或开源社区的解读。你需要在模型发布流程里建立一套由开发方主导、但可以被外部验证的文档体系。1.2 外部人看不到的模型上下文外部黑盒测试者只能提交输入、观察输出。他们看不到训练数据构成、数据清洗规则、微调策略、系统提示词、温度参数、部署时的后处理逻辑。举个例子某一个 API 模型在回答问题时可能经过安全过滤层外部人看到的输出其实是过滤后的表现却很容易把过滤能力归因到模型本身。又比如同一个模型使用不同采样参数回答质量会有明显波动外部人如果不知道文档默认采用的解码参数就可能在复测时得到完全不同的结果。内部记录里会有大量这样的信息某个 checkpoint 在哪些任务上会崩溃对抗样本的成功率是多少不同 temperature 参数下输出差异有多大微调前后模型行为偏移了多少。这些数据只有实验室内部有。如果这些上下文不写进文档下游开发者就只能靠猜测来理解模型评测方也只能通过反复试探来重建这些信息效率极低且容易出错。所以在实际项目里文档缺失的影响通常不会在产品刚上线时显现而是在几个月后集中爆发使用者发现模型出现了文档没有提到的行为排查时找不到记录只能从代码和日志里逆向推断。这本身就是一种技术债务而且比代码债务更难偿还。1.3 自写文档不等于自说自话如果自写文档变成发布方自己写一篇我们的模型更强、更安全、更可控那和没有文档没有区别。真正的自写文档应该满足三个条件。第一个条件是可复现。文档里的指标来自可以复跑的评估脚本别人拿到脚本和评估集可以在自己的环境里复现出接近的结果。第二个条件是诚实披露。已知局限和失败案例必须单独成章不能把它们埋进脚注也不能只用可能产生幻觉这类空话带过。第三个条件是责任绑定。文档需要标明作者、维护者和评审者当指标被质疑或风险被误读时团队能定位到具体的人和数据来源。自写意味着作者对文档负责可验证意味着这份文档经得起反复审查。这两点合在一起才是 Ethan Mollick 呼吁背后的真实含义也是 AI 工程实践中最容易被忽略的部分。2. AI 实验室自写文档的落地对象模型卡、系统卡与数据集卡片2.1 模型卡应该记录哪些内容模型卡的核心作用是让一个对模型完全不了解的新开发者在几分钟内判断这个模型能不能用于我的任务。它不是学术论文也不是产品宣传页而是一份结构化的事实说明。一个实用模型卡通常包含以下字段模型名称、版本号、发布日期、作者团队、训练数据概述、上下文窗口、支持的输入输出格式、评测结果、已知局限、建议用途和禁止用途。用 YAML 保存模型卡是一个比较常见的做法因为字段结构稳定易于解析也方便写进 Git 仓库里做版本管理。model_name: demo-chat-model version: 1.4.0 release_date: 2025-05-12 author_team: ai-platform train_data_summary: 公开网页语料过滤后约 1200 亿 token时间截止 2025-03 context_window: 8192 evaluation: benchmark: demo-benchmark-v2 accuracy: 0.87 eval_set_size: 1500 timestamp: 2025-04-30T10:00:00Z known_limitations: - 中文生僻名词概率偶尔偏低 - 对 2025 年 3 月之后事件的回答不可信 - 长代码结构生成偶尔丢失右括号 allowed_uses: - 内部知识库问答 - 代码片段解释 disallowed_uses: - 医疗诊断 - 自动化法律意见这个 YAML 示例用于说明思路实际项目要结合自己的模型、包名和路径调整。关键点不是字段格式而是字段背后的态度known_limitations不能临时写几条它应该从评估脚本里的失败案例中总结出来disallowed_uses必须写清楚否则下游开发者会随意拓展用途最后把风险归到模型头上。2.2 系统卡与模型卡的分工模型卡回答的问题是模型本身能做什么系统卡回答的问题是整个产品系统在线上是怎么工作的。两者不能混为一谈。在 AI Agent、RAG、多模型路由这类场景里系统卡往往比模型卡更重要。因为用户输入经过的链路很复杂先检索知识库再拼装 prompt然后调用模型接着做格式校验最后还要过一层安全过滤。模型的输出只是整条链路的一部分一个环节出问题都会影响最终结果。系统卡需要描述模块链路、中间处理规则、缓存策略、失败回退、日志与监控项。下面用一个表格说明几类文档的分工。文档类型核心问题主要读者关键内容模型卡模型能做什么、边界在哪下游开发者、算法评估者能力、评测结果、局限、用途限制系统卡线上系统如何工作运维、安全、产品模块链路、缓存、回退、监控、安全层数据集卡片训练和评测数据怎么来的数据治理、算法审计来源、清洗规则、偏差分析、授权情况API 文档调用方怎么正确接入应用开发、集成方参数、错误码、限流、计费、重试策略评测报告指标是怎么算出来的审核、审计、复测方评估集、指标口径、脚本、复现步骤2.3 把文档当作代码交付物文档不能散落在共享网盘或个人笔记里。AI 实验室自写文档的工程化第一步是把所有文档放进 Git 仓库文档版本与模型版本绑定。docs/ ├── model-card.yaml ├── system-card.yaml ├── evaluation/ │ ├── evalset.json │ └── metrics.md ├── api/ │ ├── README.md │ └── error-codes.md └── incident-history/ └── 2025-01-12-refusal-loop.md当模型发布 1.4.0 版本时给代码库打一个model-1.4.0的 tag文档同样在这个 tag 下。这样任何人拿到一个模型版本都能找到与之精确对应的文档不会出现模型已经升级、文档还停留在上一个版本的情况。文档审查也应该走代码评审流程而不是一个人在本地写完直接发布。3. 用工程化流程让文档从补写变成随开发同步产出3.1 需求阶段先登记模型用途很多团队的文档是在模型训练完成之后才开始写的这时候大量细节已经丢失。真正的文档工程化应该反着来在模型开发启动的时候就用一个文档模板登记目标场景。这个模板信息量不需要很大但必须在项目启动时写清楚目标场景是什么目标用户是谁明确不做哪些事什么方向的失败成本最高。这些内容后续会直接成为模型卡的allowed_uses和disallowed_uses来源。如果一个团队连这个模型要解决什么问题都写不出来那不应该先开工训练因为这通常意味着项目需求本身还没有收敛。在实践里可以先在docs/next-model-proposal.md里记录这些内容等模型训练完成后方案文档再转化为正式的模型卡。这样文档就不是临时补写的而是一个从需求到交付持续演进的产物。3.2 训练与评测阶段自动采集指标文档里的数字不能靠事后回忆。评估脚本每次运行时应该把结果自动保存为 JSON 或 Markdown 文件并记录模型版本、时间戳、依赖版本和环境信息。import json import time from pathlib import Path results [] for case in eval_set: prediction model.generate(case[input]) results.append({ case_id: case[id], expected: case[expected], prediction: prediction, correct: case[expected] in prediction, }) metrics evaluate(results) metrics[timestamp] time.ctime() metrics[model_version] model.version metrics[eval_set_version] eval_set.version metrics[prompt_template_version] prompt_template.version metrics[decode_params] { temperature: 0.7, top_p: 0.9, max_tokens: 1024, } Path(artifacts/metrics.json).write_text( json.dumps(metrics, ensure_asciiFalse, indent2) )这段代码的关键是记录四类元信息模型版本、评估集版本、prompt 版本和解码参数。没有这些信息指标就是孤立的数字出了争议无法回溯。评估脚本本身也要提交到仓库提交信息里标明对应的模型版本。3.3 发布前用文档检查单把关模型发布前不能只检查模型能不能跑通还需要检查文档是否齐全。建议在发布流程里加入一个文档检查单任何一个项目不通过发布流水线就失败。检查项要求不通过的后果模型卡是否完整包含能力、局限、用途限制下游无法判断适用场景评测结果是否由脚本生成有结果 JSON 和脚本路径指标无法复现信任度下降已知局限是否列出至少列出 3 条具体局限使用者会误认为模型没有边界风险等级表是否完成覆盖严重到低风险场景安全审计无法推进API 错误码是否更新错误码与线上实现一致集成方排障困难系统卡是否有链路图描述模块调用和回退关系线上故障无法快速定位文档版本号是否与模型版本一致模型 tag 与文档版本匹配旧文档误导新模型使用注意不要只验证模型能启动还要验证文档的输入、输出、异常分支和日志是否与线上行为一致。3.4 版本更新后同步文档模型迭代频率很高文档版本如果跟不上就会造成旧文档配新模型的混乱。建议在发布流水线里增加一个版本一致性检查读取模型版本对比文档中的版本号。model_version$(docker inspect demo-app --format {{ index .Config.Labels model.version }}) doc_version$(grep ^version: docs/model-card.yaml | awk {print $2}) if [ $model_version ! $doc_version ]; then echo 模型版本与文档版本不一致请更新 model-card.yaml exit 1 fi这段命令只是示例实际项目要按自己的部署方式调整。核心思路是把文档是否同步变成发布流程里的硬性条件而不是依赖某个人记住提醒。4. 自写文档的质量控制谁来审、审什么、怎么避免自吹自擂4.1 引入独立审计视角自写文档最容易被挑的问题是不够客观。所以流程上至少要有两层审核。第一层是开发团队内部的技术评审重点检查事实和可复现性。评审人要看评估脚本是否存在、结果 JSON 是否由脚本生成、已知局限是否足够具体。第二层是独立审计可以是公司内部不参与模型开发的安全团队也可以是外部研究机构。审计方要能拿到评估脚本和必要的评估集复测文档里的关键数字。这里有一个实践建议第三方复测的结果如果和文档不一致应该作为独立章节写进文档而不是把差异删掉或私下协调。差异本身是很有价值的信号它可能暴露评估集不同、解码参数不同甚至模型行为漂移。4.2 把已知风险写进已知局限性文档里最影响使用者判断的部分不是指标高不高而是它会在哪里出错。比如在事实型问答任务中模型容易出现 AI 幻觉文档就应该列出典型的失败案例而不是统一说大模型可能产生幻觉。又比如模型在低资源语言场景上测试集较小文档要明确说明样本量不足结论置信度有限不能给出一个看起来很精确但不稳的数字。举个例子与其写模型代码生成能力优秀不如写模型在 500 条 Python 单测编写任务上通过率为 82%但在多文件项目的跨文件类型推断场景下失败率较高建议与静态分析工具配合使用。后者的信息量远大于前者。注意文档里最不该出现的是没有条件的准确率。任何指标都必须带着场景、口径、样本量和测试时间一起出现。4.3 让评估脚本可复现可复现是自写文档的底线。评估时固定模型版本、固定依赖版本、固定随机种子使用相同 prompt 模板并把运行环境写入结果文件。import random import numpy as np import torch def set_seed(seed: int) - None: random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed_all(seed) set_seed(42) # 评估时不要打开影响随机性的数据增强 model.eval()如果评估脚本本身不稳定文档里的数字就会成为争议源头。一个数字无法被复现它在工程上的价值就是零。团队应该把可复现性当成评估脚本的基本要求而不是额外加分项。5. 文档中的指标、参数与风险评估表怎么做5.1 评测指标要写清楚场景、口径和数据来源指标表不能只有一行准确率 87%。它至少应该包含任务场景、指标名称、数据集来源、样本量、结果和备注。这样读者才能判断这个指标对他是否有参考价值。任务场景指标数据集来源样本量结果备注中文新闻分类宏平均 F1demo-news-v350000.84训练集与测试集来源均含新闻站法律问答人工可用率demo-legal-qa2000.76样本量较小置信度有限Python 代码生成通过率demo-codegen-py5000.82单文件场景未覆盖多文件项目英文摘要ROUGE-Ldemo-summary-en8000.34参考摘要由人工重写非原文句抽取生成类任务不能只依赖 BLEU 或 ROUGE还需要结合人工评估。分类任务则要关注精确率、召回率和 F1不能只看准确率尤其是类别不平衡时。指标口径写不清楚文档再长也没有参考价值。5.2 风险等级表如何设计风险评估表可以按严重、高、中、低分级每一级都要给判定标准、典型例子和缓解措施。风险等级判定标准示例缓解措施严重可能造成人身伤害或重大财产损失医疗诊断建议、航空操作指令禁止自动化决策强制人工审核高可能造成明显的法律或隐私风险自动化法律意见、个人信息处理限制用途增加人工复核中可能降低用户体验或引入错误信息新闻摘要、客服问答在响应中标注模型生成提供反馈入口低影响有限且可接受代码注释生成、文案润色按普通发布流程管理风险表不是静态文件。线上发现新问题时要回头更新风险等级和缓解措施。风险表的作用是让下游开发者在做风险决策时能快速判断当前模型适合什么场景、需要什么额外控制而不是把风险全部留给集成方自行推断。5.3 API 文档和错误码容易遗漏的内容API 文档除了 endpoint、鉴权方式和参数说明还应该写清楚 context window 超限时返回什么错误、token 计费和 credits 消耗规则、请求超时多长、限流后应该怎么重试。这些内容在集成阶段最容易引发工单。一个容易遗漏的细节是错误响应的结构。如果文档只写错误码含义不写响应体的 JSON 示例开发者在处理异常时只能靠猜测。{ error: { code: rate_limit_exceeded, message: 请求频率超过限制请稍后重试。, retry_after_ms: 15000 } }把错误码、重试时间、错误响应结构写清楚可以显著降低部署和集成阶段的沟通成本。文档里的 json 示例越接近线上真实行为调用方的排障效率就越高。6. 常见问题与排查路径文档没人看、数据对不上、更新滞后6.1 文档写完了但没人看现象文档发布到内部知识库一两个月没有访问记录模型发布时也没有人核对文档。这种情况很常见核心原因是文档没有嵌入到必要的流程里。常见原因和处理建议如下。问题现象常见原因检查方式处理建议文档写完无人阅读文档不在发布检查单里查看发布流程、定义完成标准把文档齐全设为发布前置条件调用方不看文档就接入错误信息里没有文档链接查看 API 错误响应在错误响应中返回 doc_url 字段文档维护责任不清晰团队没有指定文档 owner检查仓库提交记录为每个模型卡指定维护人和评审人文档与当前版本脱节没有版本一致性检查对比模型标签和文档版本号在 CI 中加入版本一致性检查最有效的方法是把文档消费行为嵌入到开发体验里。调用方遇到错误时错误响应里直接给出文档链接而不是让使用者去知识库里搜索。这样文档才能从静态资料变成开发流程的一部分。6.2 文档里的指标和复测结果对不上现象文档说准确率 87%外部复测只有 78%。这是自写文档最容易消耗信任的场景。出现差异时要按顺序排查四个环节模型版本、prompt 模板、评估集、解码参数。排查步骤检查点解决方式1复测用的模型版本是否与文档一致用模型标签和权重 hash 确认2prompt 模板是否与文档一致对比文档中的 prompt 原文3评估集是否一致对比测试样本 hash 和样本量4解码参数是否一致核对 temperature、top_p、max_tokens注意排查任何指标不一致时先确认输入是否正确再检查环境、版本和配置。大部分差异都出在这四个环节而不是出在模型本身。如果四个环节核对后仍然不一致再检查评估脚本 bug 或文档本身错误。关键是团队要有能力回答这个指标是从哪份脚本、哪个评估集、哪组参数里算出来的而不是用可能是环境差异糊弄过去。6.3 模型升级后文档没有同步现象模型已经上线 4.x文档还停留在 3.x。这种情况的根因通常是发布流水线没有版本一致性检查。模型随便升级文档靠发布人记得才更新。对策是在发布前强制比较模型版本号和文档版本号。同时模型卡里要增加一个变更记录章节记录每个版本在行为、token 消耗、响应质量上的变化。变更记录不需要很长但必须说清楚从上一个版本到现在什么样的请求会得到不同的响应。这个责任最好由模型发布负责人承担而不是由文档工程师独自维护。7. 最佳实践把文档建设变成可持续的工程习惯7.1 文档即代码的最佳实践清单把文档当成代码来管理是 AI 实验室自写文档这个观点落到工程里最重要的转化。以下清单可以带到团队评审会上逐条核对。文档与代码同仓库不使用个人笔记或共享网盘作为唯一载体。文档字段有模板模型卡、系统卡、API 文档分别有自己的模板。评估结果由脚本自动生成不手工填写评测数字。发布前执行文档检查单未通过不能上线。文档版本与模型版本使用 tag 绑定发布流水线自动校验。已知局限写出具体案例和场景不用模版话术。外部复测结果作为附录写进文档不隐藏差异。每个文档有明确的 owner 和 reviewer。文档更新触发变更记录变更记录随发布一起评审。7.2 学习环境与生产环境的文档要求差异不同阶段对文档的深度要求不同。个人实验和学习环境可以轻量化但不能完全没有记录生产环境则必须完整。环境最低文档要求评测要求风险控制要求学习环境简单的 README记录模型用途、数据集和已知问题不强制但建议记录 eval 结果来源不涉及真实用户数据开发环境模型卡初稿 评估脚本关键指标可复现限制访问记录调用日志测试环境模型卡 系统卡 测试报告指标口径完整与线上一致有使用者须知禁止高风险用途生产环境模型卡 系统卡 API 文档 评测报告 变更记录指标可复现外部可复测风险表、监控、回滚方案和文档联动生产环境文档缺失的成本最终会由真实用户和一线值班人员承担。线上行为异常时如果连系统链路和模型版本都定位不了再强的排障能力也无处发力。7.3 一个新手团队可以立刻执行的 21 天落地方案如果团队之前没有文档工程习惯不要试图一次性铺开全部体系。可以按 21 天分阶段落地。第 1 到 7 天整理已有信息把当前模型的历史评测结果整理成 JSON 文件从实验记录里抽出已知局限写一版最简模型卡。这一步不追求完美先让信息从一个位置移到另一个位置。第 8 到 14 天搭模板和仓库按模型卡、系统卡、API 文档、评测报告四个目录建立 docs 仓库把模板提交进去指定每个文档的 owner。让一两个正在迭代的模型先用上新模板收集反馈并调整字段。第 15 到 21 天接入发布流程把文档检查单和版本一致性检查写入发布流水线选一个业务场景试用文档跟踪文档是否真的减少了接入和排障时间。这一步做完团队就具备了文档即代码的基础能力。之后可以根据团队规模继续扩展增加外部审计、公开评估脚本、记录在线事故逐步把文档和监控体系连接起来。对于刚开始转型的团队不需要一次性追求完整但需要先把文档从一个可有可无的产物变成模型发布流程里不可跳过的一步。这些做法并不会额外增加很多工作量因为它把原本就存在于会议、聊天记录和实验脚本里的信息转移到了一个可以被读取和验证的地方。Ethan Mollick 的呼吁如果只停留在实验室应该写文档这句话它不会有任何工程价值只有当团队把写文档当成模型交付的一部分当成发布流程里不可跳过的一步AI 系统的可用性和可维护性才真正开始。对于刚起步的团队可以从一份最简单的模型卡和一条版本一致性检查开始先把自写文档变成完成一个模型发布必须走完的步骤再逐步加深。
