AI工程落地如何用文档驱动：从Prompt到模型卡的实践指南-北京尧图网络

做 AI 工程落地的人可能都有同感模型效果一不好第一反应永远是“改 prompt”第二反应是“换模型”但很少有人先问一句——这个功能的验收标准是什么当初为什么这么设计如果项目里的文档只停留在“接口文档”和“产品 PRD”那 AI 项目跑得越久越容易变成一座没人敢动的黑箱。这也是我写“AI 开发文档驱动实践”系列的原因。上一篇聊了从 idea 到原型怎么用文档梳理需求这一次我们把视角拉长聊聊工程流交付怎么让文档成为 AI 项目从开发、评估到上线运维的主线而不是可有可无的附件。刚做 AI 项目时我也觉得文档驱动是“敏捷开发的反动派”写着写着就变成负担。直到一个做了半年的客服工单分类项目换个人就无法迭代时我才意识到AI 项目里最贵的不是 GPU不是 API 调用费而是丢失的上下文。一个 prompt 为什么加某句话、一个评估集为什么删掉某条样本、一个 agent 为什么只暴露三个工具这些背景如果不落在文档里所有经验都会慢慢蒸发。下面这些内容来自我真实踩坑后的实践希望能对正在把 AI 能力往生产环境推的朋友有点用。它不适合那种 demo 完了就走的活动项目而更适合要维护半年以上的 AI 产品。1. 为什么 AI 项目特别需要文档驱动1.1 AI 的交付物不只是代码而是“可运行的经验”传统软件开发里代码是稳定、可测试、可评审的文档更多是“事后补充”。但 AI 应用不一样一个完整的交付物至少包含四样东西模型或 API 配置、prompt 模板、评估数据集、以及编排这些组件的代码。更关键的是其中 prompt 和评估集的改动往往比代码更频繁而且很难用“单元测试”把所有问题都守住。举个例子你写了一个客服工单分类 prompt要求模型“如果工单语气比较急优先判断为高优”。这句话在代码里只占一行但它背后的业务逻辑是历史上发生过“用户骂了几句但其实是咨询”的样本导致高优误判率飙升。如果没有文档记录这条经验三个月后另一个同事看到这个 prompt大概率会直接删掉“语气比较急”这半句理由是“太主观”。于是模型回归线上投诉暴增。所以 AI 项目的文档驱动核心不是“写文档给审计看”而是把团队的判断和上下文沉淀下来让每一次 prompt 改动、模型升级、工具增删都有依据。这种文档不是解释代码的注释它本身就是交付物的一部分。1.2 什么样的文档才叫“能驱动工程的文档”很多人一听文档驱动下意识想到一个 wiki 系统里面堆满几十篇没人看的文章。我在工程流里对文档只有三个硬性要求可版本化、可执行、可解释。可版本化意味着文档跟着代码走用 git 管理改一个条件、加一条评估样本都能 diff 出来。可执行意味着文档里的接口定义、评估用例、模型参数可以被脚本直接读取用来生成测试代码或者跑回归。可解释则要求每条关键决策都写明“为什么这样做”“当时有哪些选择”“放弃了什么”。这样的文档才是活的否则只是又一份静态文档。我推荐用 Markdown Git 仓库来维护而不是放到企业 wiki。原因很直接wiki 的编辑权限往往太宽松谁都能改但没有版本回退意识而 Git 天然适合多人协作每个改动都有作者、有时间、有理由还能和 issue、MR 关联起来。1.3 文档驱动真正解决的是“知识断层”做 AI 项目的团队很容易出现一个怪圈模型效果好时大家不愿意动文档觉得“反正能跑”模型效果变差时大家又忙着调参更没时间写文档。结果就是项目启动三个月后唯一完整的文档是产品和运维一起写的部署手册而 prompt 怎么设计、数据清洗规则是什么、评估集怎么来的全都散落在聊天记录和个人笔记里。文档驱动能有效缓解这个问题。它迫使团队在每个里程碑结束前把当时的方案、实验结果、阶段性结论写下来哪怕只有半页纸。这样做的好处是新人接手时不用靠“口口相传”模型劣化时能快速回退到某个已知 good 的版本业务方提出新需求时也能直接用旧文档作为需求讨论的锚点。我见过太多项目死就死在“会做的人走了解释没人懂”文档驱动就是给项目上的一道保险。2. 工程流交付的文档体系2.1 第一层业务需求如何转成 AI 任务定义工程流交付的第一步是把业务语言翻译成 AI 可执行、可评估的任务定义。很多团队在这里就翻车了比如只写“提高客服效率”完全没定义输入输出导致后面既没法做 prompt也没法做评估。我常用的模板是四段式业务背景、任务公式、约束条件、评估方式。以工单自动分类为例维度内容业务背景客服系统每天约 3000 张工单需要人工按 8 个类目分配部门平均耗时 2 分钟任务公式输入是工单标题描述文本输出是 1 个或 2 个预定义类目标签约束条件单次推理延迟小于 800ms必须支持中英文混排错误标签不能把投诉单分到咨询类评估方式精确匹配准确率Top-1 和 Top-2、人工抽检通过率、高优工单的召回率这份文档不用写得很长但一定要让一个没参加过前期讨论的工程师看完就能明白“到底要建一个什么 AI 能力怎么验证它做得好不好”。后面所有 prompt、代码、评估集都围绕这份任务定义展开。2.2 第二层技术方案和架构决策记录ADR接下来是技术选型和架构层面的决策记录。这一层最容易被忽视但它恰恰是将来返工成本最高的一环。举个例子项目初期为了快速出 demo直接调用云端大模型 API等上线后要求数据不出内网才被迫换成本地部署的小模型。如果一开始在 ADR 里写清楚“数据安全等级较高必须支持私有化部署”这个约束选型就不会走弯路。ADR 的写法可以很轻量不需要重型的架构设计文档。通常包含五个部分背景、决策、理由、替代方案、影响。我建议固定成一个简单的 Markdown 模板存在 docs/adr/ 目录下编号管理# ADR-003客服工单分类采用自部署小模型方案 ## 背景业务要求数据不出内网云端大模型 API 无法满足合规要求。 ## 决策采用本地部署的通义千问或 Qwen 系列 7B/14B 模型通过 vLLM 提供 OpenAI 兼容接口。 ## 理由 - 数据不出内网满足安全要求 - 7B/14B 在工单分类这类文本任务上已能接近 GPT-4 的基线准确率 - 单卡 A10 可承载线上流量成本可控 ## 替代方案 - 继续使用云端 API被合规否决 - 使用更小的 1.8B 模型准确率差 6 个百分点不可接受 ## 影响 - 需要一个 GPU 节点运维复杂度增加 - prompt 风格需适配本地模型部分指令理解能力弱于云端模型 - 后续模型升级需重新跑评估集这类 ADR 的价值在于它把一段历史判断固定下来未来任何人看到模型选型都能知道“当时为什么没有选另一个方案”。如果你用的 AI 编程工具能读取 docs/adr/ 下的内容它生成的代码也会更贴合项目的技术约束。2.3 第三层接口契约与 Prompt 版本说明第三层是技术契约层包括 API 接口定义、数据结构、prompt 模板和 agent 工具定义。这一层是和代码结合最紧密的文档也是最容易做到“从文档生成代码”的地方。以 Spring AI 为例Java 服务里通常会定义一个工具方法和一个 prompt 模板。接口契约文档可以这样写## 工具create_ticket_classification 功能将工单文本分类并返回类目编码入参 - text: string工单正文 - history: string[]聊天历史可选出参 - category: string枚举[BILL, TECHNICAL, COMPLAINT, CONSULT, OTHER] - confidence: number0-1 之间的置信度错误处理入参为空时返回 error.code EMPTY_TEXT有了这份契约AI 编程工具在生成 Spring Boot 的 Controller、Service 和 DTO 时就不会自己发明类目名称或参数结构。你会发现“文档驱动”在 AI 编程场景里不是一句口号而是实实在在的约束手段——把 prompt 和接口的规则喂给 AI它能少发挥不少。同样prompt 模板也要版本化。我不建议直接在代码库里放一个prompt.txt完事最好加上变更说明# prompt: 工单分类 v2.1 更新日期2025-06-18 变更人xxx 变更原因v2.0 对“退款失败但语气平和”的工单误判为咨询类补充了“已发生交易问题”的判定条件。2.4 第四层评估报告与回归基线最后一层是质量观测层也是工程流交付能不能“闭环”的关键。AI 项目的质量标准不能靠感觉。我要求每个版本至少产出一份评估报告内容是评估集版本、测试样本数量、各项指标数据、与上一版本的对比、异常样例分析。这里要特别说一句评估报告不是只在发版前做一次而是每次 prompt 或模型改动后都要跑。一个小技巧是把评估报告直接提交到仓库里的 docs/eval/ 目录文件名带上版本号比如eval_report_v2.1.md。这样 git log 就自动变成了一条“效果趋势图”哪次改动让准确率掉了一目了然。3. 从需求到交付一个完整的实操流程3.1 第一步用 Context Spec 锚定项目上下文很多 AI 项目的失败不是模型不够强而是上下文没有对齐。我建议每个项目在启动时先写一份 Context Spec上下文规格放到docs/context.md。它比 PRD 轻但比会议纪要重核心目的是让“人、AI 编程工具、模型”使用同一套背景知识。一份 Context Spec 至少包含以下几块项目背景为什么做这个功能期望解决什么问题目标用户谁在用使用场景是什么数据样例5-10 条真实输入输出展示边界情况禁忌项明确不要做什么比如“不要生成不属于 8 个类目的新类目”已确认的评估指标准确率、召回率、延迟、成本上限等写完 Context Spec 之后后续所有 prompt 优化、代码生成、测试用例设计都引用这份文档避免每次开会或者改代码时重新对齐背景。3.2 第二步让 AI 编程工具按文档生成代码如果你已经在用 AI 编程工具比如 IDE 里的 AI 插件或者 Spring AI 等框架可以尝试“文档即提示词”的姿势。把接口契约和 Context Spec 喂给 AI 工具然后让它生成代码。不用每次都把背景重新输入一遍工具会把上下文带入后续对话。以生成一个工单分类 REST 接口为例我在 Java 工程里会这样下指令根据 docs/context.md 中的任务定义以及 docs/contracts/ticket_classification.md 中的接口契约生成 Spring Boot Controller 和 Service 实现。方法签名不要修改请求和响应 DTO 字段按照契约定义。模型推理走本地的 OpenAPI 兼容端点。这样生成的代码至少能保证结构符合约定类目枚举不会写错错误处理也能对应得上。当然AI 生成的代码仍然需要人工 review但至少省掉了大部分重复劳动。3.3 第三步评估集归入版本库prompt 改动必须绑定报告我在团队里定了一条铁律不允许“改完 prompt 口头同步”。任何 prompt 改动必须附带一次评估结果。评估集放在 git 仓库里可以是 JSON Lines 或者 CSV每条样本标注好“期望输出”和“是否作为回归关键项”。常见结构data/eval/ golden_v1.jsonl golden_v1.1.jsonl regression_v2.jsonl docs/eval/ eval_report_v2.1.md跑评估的脚本单独维护注意不要一次性把所有测试样本全塞给模型那样成本太高。CI 里跑一个小的 smoke test比如 20 条关键样本完整评估放到发版前或每天晚上跑一次。改 prompt 的时候把变更内容写进报告的“变更说明”里。比如版本变更点准确率高优召回率备注v2.0初始版本87.2%91.0%基线v2.1增加“已发生交易问题”判定88.5%92.3%误判减少延迟无波动v2.2将“语气过激”权重降低87.8%90.1%高优召回下降回滚这种表一旦长期维护下来几乎就是项目的“AI 效果账本”谁改了什么东西、带来了什么影响一笔一笔都清清楚楚。3.4 第四步部署模型时模型卡与运行时配置缺一不可模型部署不是“把接口起起来”就完事。真正进入工程流交付我要求每个部署单元必须附带一张模型卡Model Card记录模型来源和版本比如 Qwen2.5-7B-Instructprompt 模板版本部署时绑定的那份依赖环境Python 版本、推理框架、CUDA 版本推理超参温度、top_p、max_tokens、并发数观测指标请求量、延迟分位数、token 用量、成本预估这张模型卡最好写成MODEL_CARD.md放在项目仓库里和部署配置Dockerfile、K8s deployment放一起。你看这就把文档驱动延伸到了运维侧任何一个人看到这张卡就能回答“线上这个服务到底是什么模型、用的什么 prompt、资源够不够”这些最常见的问题。另外一定要关注成本观测。我见过不少团队上线后只盯准确率结果月底收到云账单才发现成本超了预算五倍。所以在模型卡里写上“每千次请求成本预估”并且通过日志统计真实 token 消耗是文档驱动在成本治理上的一个延伸。4. 常见问题与排查技巧实录4.1 文档和代码脱节过两周就没人维护了这个问题几乎每个团队都会遇到。我的解法不是靠自觉而是靠自动化。在 CI 里加一个文档检查任务内容包括Markdown 格式规范检查markdownlint文档中引用的文件路径是否存在接口契约里定义的数据结构是否有对应的代码类如果使用 OpenAPI 规范可以用脚本对比生成代码和 spec 是否一致一旦某个文件引用了不存在的路径或者 OpenAPI 定义改了但没有更新接口文档CI 直接失败。这样能把“文档过期”的问题挡在合并代码之前。4.2 新人不理解评估集随便往 golden set 里加样本评估集是 AI 项目最敏感的资产。很多人会随手把线上新出现的一条样本加进测试集然后发现指标“变好”了其实只是模型见过类似的内容。我的做法是评估集不直接往 master 提交所有新增样本必须走 MR并且要有“为什么加这条”的说明。比如“某用户反馈投诉单被分到咨询类补充该场景回归”。这样至少能保证每一条样本都有业务来源而不是拍脑袋。4.3 模型输出不符合 JSON 格式导致下游解析崩溃这可以说是生产环境里最经典的问题了。文档驱动的价值在于在契约文档里明确约定输出格式并且在代码里做校验和重试不能只靠 prompt“保证”。实操中我会让模型首先输出一个宽松的文本然后用代码做后处理或者要求模型通过 function calling 方式返回结构化参数。对于自部署模型建议在推理服务层加一层 response schema 校验不符合就重试一次还不符合就记一条异常日志。这些规则也要写进文档不然下次换上另一个模型问题会反复出现。4.4 多个模型对比时团队内部争论“谁更好”文档驱动不解决模型效果本身的问题但它能规范对比方式。我建议所有模型对比都基于同一个评估集、同一份抽样标准并且做“盲评”把模型 A 和模型 B 的输出结果随机打乱让人工 reviewer 只评价“是否达到了期望效果”不评价“是谁生成的”。这样能极大减少“我觉得新模型更像人”这类主观干扰。4.5 AI 写文档写得很像但它可能是幻觉现在很多团队用 AI agent 辅助生成文档效果很惊艳但也带来了新风险AI 编造数据集、编造“最佳实践”、甚至编造不存在的依赖版本。我在文档驱动里有一条原则AI 生成的文档只能作为初稿必须由人工标注“经过核验”并在文档头部注明日期和审核人。对于技术决策类文档AI 最多做资料整理不能替代 ADR 的最终决策记录。5. 工具链与落地配置参考5.1 文档仓库怎么搭我习惯一个 AI 工程服务对应一个 Git 仓库根目录下docs/结构如下docs/ context.md # 上下文规格 adr/ # 架构决策记录 0001-intro.md contracts/ # 接口契约、prompt 模板、工具定义 ticket_classification.md eval/ # 评估报告 eval_report_v2.1.md MODEL_CARD.md # 模型卡配合.markdownlintrc做格式约束pre-commit 钩子里加上 markdownlint 和链接检查。如果你想可视化浏览这些文档可以用 MkDocs 或 Docusaurus但纯 Git 仓库也已经够用。5.2 从文档生成 prompt 和代码的姿势在 Spring AI 项目里可以把docs/contracts/下的内容直接作为知识库提供给 agent让它在生成代码时参考。也可以手动在 AI 编程工具里指定“先读这个文件再开始编码”。另一个实用技巧是把常用 prompt 模板放到src/main/resources/prompts/目录Spring AI 运行时加载这样 prompt 能跟着 jar 包发布避免线上还在用本地改过的临时 prompt。你要保证“线上跑的 prompt 文档里记录的 prompt”最稳妥的方式就是让模型卡记录资源文件版本部署时校验哈希值。5.3 CI/CD 里的“质量门禁”我在 GitLab CI 里通常会加这几个 jobstages: - doc-check - test - eval-smoke - deploy doc-check: stage: doc-check script: - markdownlint docs/**/*.md - python scripts/check_links.py docs/ - python scripts/validate_contracts.py docker-compose.yml eval-smoke: stage: eval-smoke script: - python scripts/run_eval.py --subset golden_smoke.jsonl artifacts: paths: - docs/eval/latest_report.md请注意不要在每次提交时都跑完整评估集成本太高。把完整评估放到定时任务或者发版前手动触发CI 只保证“核心样本不劣化”。5.4 可选本地模型部署时的最小配置如果你的项目需要私有化部署模型可以用 vLLM 起一个 OpenAI 兼容服务模型卡里记录参数。推荐配置示例vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --served-model-name ticket-classifier部署之后所有调用方都走统一的/v1/chat/completions接口prompt 模板由业务服务读取这样文档、代码、模型三者就能对得上。如果你用的是 OpenAI 等云端 API模型卡上就写 “cloud provider model name temperature max_tokens”逻辑一样。6. 最后分享两个小技巧文档驱动不要理解成“文档越多越好”。真正有用的文档是能回答“为什么”和“怎么验证”的那几份。我建议你从最小集开始一份 Context Spec、一份模型卡、一个 golden set。三个东西加起来可能不超过十页但足以让一个新人快速接手项目。另外一个很个人的经验每当有人跑来问我 prompt 为什么这么写我不直接回答而是给他一个命令git log --follow -p -- src/main/resources/prompts/ticket_classification_v2.txt。让他在 git 历史里找到当初的变更说明比当面解释十遍都有效。当团队习惯了从文档和 git 历史里找答案文档驱动才算真正落地了。

AI工程落地如何用文档驱动：从Prompt到模型卡的实践指南

相关推荐

MyBatis缓存机制详解：一级与二级缓存原理与实践

C语言与Python协同实现高效算法与网络操作

Vibe Kanban 如何为仓库配置 Setup 脚本，让代理启动前自动安装依赖并准备环境

更多资讯

树莓派Pico呼吸灯：MicroPython硬件PWM与伽马校正实战

Qwen3与Claude3.5的Thinking Mode推理对比实战

WSL+VS Code Server+Ollama：构建Web化AI开发环境

.NET构建与发布革新：NativeAOT、单文件、剪裁与源生成器实战指南

Android面试能力解码：基础穿透力与场景决策力实战

Zabbix保姆级部署教程：从环境准备到主机接入与报错排查

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？