AI应用工程化交付：文档驱动控制模型不确定性的实践指南

AI 应用跑通 Demo 容易，真正难的是交付。做过 RAG 问答、Agent 编排这类项目的人应该都有同感：原型阶段一两天就能拉起来，可一旦进入工程化交付，需求边界乱、指标说不清、模型一换就崩、Prompt 调完没法回滚，项目越往后越像踩在流沙上。我在接手这类项目时，会把“文档驱动”作为工程流交付的骨架来用——不是写一堆没人看的 Word，而是让每一份文档都承担明确的工程职能。这篇是“AI 开发文档驱动实践”系列的第二篇，重点讲工程流交付怎么落地，适合正在做 AI 应用交付的开发者、技术负责人，以及被 AI 项目返工折磨的团队参考。

1. 为什么 AI 开发必须“先文档、后代码”

1.1 传统文档驱动的思路，为什么在 AI 场景失灵

过去做传统软件开发，文档驱动的逻辑是“把确定性行为描述清楚”。需求文档写功能点，设计文档画模块图，接口文档定义入参出参，开发照着实现就行。这套思路在常规 Web 系统、中间件项目里很成熟，因为行为是可预测的：输入给定，逻辑固定，输出唯一。

但 AI 项目完全不是这样。模型输出有概率性，同一个 Prompt 多次调用结果可能不同；Prompt 语义极其敏感，加一句“请用中文回答”可能就改变输出结构；评测标准主观性强，同一个答案有人说“可以”，有人说“完全不对”。我见过一个团队做知识库问答，产品经理和算法工程师为了“什么叫回答正确”争论两天，最后发现两个人对召回片段的理解完全不同。传统文档解决不了这个问题，因为传统文档默认“行为是确定的”，而 AI 项目里行为本身就是变量。

所以在 AI 工程流交付里，文档驱动的本质变了：文档要描述的不再是“系统怎么做”，而是“如何在一个不确定系统里建立确定性边界”。需求文档要做的是锁定输入输出的业务边界，技术方案要定义模型链路和兜底策略，评测文档要把主观质量变成可量化的通过标准。谁先把这个边界画清楚，谁的交付进度就更可控。

1.2 AI 项目的隐形返工，大多源于“口头需求”和“印象式验收”

做过 AI 交付的人对下面这个场景不陌生：客户说“我要一个能查公司制度文件的问答助手”，开发觉得简单，几天后 Demo 出来了。然后客户开始提反馈——“这个回答不够完整”“这段应该引用附件原文”“那个问题不应该回答这么细”。每一条听起来都是小改动，但背后涉及切分参数、召回数量、Prompt 结构、拒答规则的连锁调整。两周下来代码改了 N 版，每一版之间没有明确记录，到最后没人说得清当前线上那版为什么这么调。

这就是 AI 项目最贵的隐形返工：因为需求没有文本化约定，验收靠双方“印象”；因为评测没有固化基线，每次优化都不知道是变好还是变差；因为 Prompt 没有版本记录，发现问题时无法快速回滚。我自己的习惯是，任何 AI 交付项目启动第一天，先建四个文档：需求矩阵、技术方案、评测基线、变更记录。不写完这四样，不动核心代码。

这套做法表面上增加了前期成本，实际上省的是后续反复试错的成本。曾经有个项目，需求矩阵里明确了“仅回答制度相关内容，不回答非制度问题”，就这一条“非目标”定义，帮团队后续省掉了大量无关问题的处理争议。文档驱动在 AI 工程里的价值，就是四个字：控制变量。

2. 工程流交付的整体设计思路

2.1 阶梯式交付：先 Demo，再可用，最后才谈交付

AI 项目最大的坑，是想直接从 Demo 跳到交付。Demo 阶段的成功标准是“看起来不错”，演示几个精心挑选的案例，模型表现流畅就能过关。但交付阶段的成功标准是“稳定达标”，需要覆盖常见边界情况、满足性能要求、能解释错误行为、支持后续迭代。这两者之间隔着一整套工程化工作。

我把 AI 项目交付拆成三个阶段：Demo 阶段、可用阶段、可交付阶段。

Demo 阶段的目标是验证可行性，用少数样本确认“这个方向走得通”，产出物是原型代码和少量演示用例。可用阶段的目标是补齐质量和边界，要求建立评测集、设置质量门槛、完善异常处理，产出物是评测报告和问题清单。可交付阶段的目标才是工程化交付，要求部署方案确定、监控日志齐全、文档完整、支持交接和后续维护。

很多团队在 Demo 阶段就感觉“做完了”，这是典型的误判。Demo 只是验证了模型能力的可能性，工程流交付要把这种可能性变成可复现、可度量、可维护的稳定性。每个阶段之间都需要一个明确的评审门槛，达不到不许进入下一阶段。这个门槛靠什么定义？靠文档，尤其是评测基线和验收清单。

2.2 四类文档构成工程流交付的核心骨架

工程流交付阶段，我维护四类核心文档，它们的职责完全不同。

需求矩阵回答“做什么”。它把用户诉求拆成可核对的条目，包括用户故事、输入样本、预期行为、验收标准、非目标。需求矩阵的粒度要到“可测试”，每一条都能对应到一个评测用例。

技术方案回答“怎么做”。它描述系统架构、模型链路、数据流、接口设计、异常兜底。AI 项目里技术方案尤其要写清每个节点的输入输出，以及模型行为不达预期时的降级策略。

评测基线回答“好不好”。它定义质量指标、测试数据集、评测方法和通过阈值。评测基线是整个交付的“红绿灯”，没有它，优化就是凭感觉，验收就是扯皮。

变更记录回答“为什么变成现在这样”。它记录每次 Prompt 调整、模型替换、参数修改的原因、内容和评测结果。AI 项目里变更记录不是给领导看的，是给“两周后的自己”看的。

这四类文档是一套闭环：需求矩阵定义目标，技术方案定义路径，评测基线定义标准，变更记录定义历史。缺了任何一个，工程流交付都会出现漏洞。

3. 核心细节拆解：把文档写成可执行的标准

3.1 需求矩阵怎么写，才能不被开发“打折消化”

需求矩阵是工程流交付的源头，写不好后面全是歪的。我发现很多团队的需求文档写得太“产品化”，全是“提升用户体验”“增强回答准确性”这种无法验证的描述，开发拿到手只能自行发挥，交付结果自然对不上预期。

我的需求矩阵模板包含六个字段：用户故事、输入样例、预期行为、验收标准、非目标、优先级。用户故事描述业务场景，输入样例给出至少一个代表性输入文本，预期行为描述给定输入下系统应该输出什么，验收标准用可量化语言定义“通过”，非目标明确指出系统不做什么，优先级用来排迭代顺序。

举一个实际的例子。某个企业制度问答项目，需求矩阵的一条记录是：用户故事“员工询问年假制度”；输入样例“我今年刚入职，可以休几天年假？”；预期行为“依据公司制度文件，给出年假计算规则和适用条件”；验收标准“召回内容包含制度原文中年假相关条款，回答无事实性错误，引用可追溯”；非目标“不做年假余额查询、不解答非制度类问题”；优先级 P0。

注意“非目标”这一栏，很多人都忽略，但它在 AI 项目里极其重要。模型天生是生成式的，你不告诉它不要做什么，它就会自由发挥。需求矩阵里写清非目标，等于给模型和开发者同时划了一条边界线，后续拒答策略的设计也有了依据。开发看到这条需求就知道：非制度问题不需要优化回答，直接走拒答分支就行。这一条能让团队避免大量无效优化。

3.2 技术方案：数据流、模型链路、兜底策略缺一不可

技术方案文档在 AI 工程流交付里容易走两个极端：要么写成高大上的架构图 PPT，要么写成只有自己看得懂的代码注释集。我理想的 AI 技术方案，至少包含四部分：系统架构、数据流、模型链路、兜底策略。

系统架构不用多说，描述整体模块划分。数据流要写数据从哪里来、经过哪些处理、最终到哪里去。RAG 类项目要写清楚文档加载、切分、向量化、存储、召回、重排、生成的完整链路。模型链路要说明每个环节用到什么模型、为什么选它、输入输出格式是什么。

关键是兜底策略。AI 模型一定会出现非预期行为，技术方案里必须预设怎么办。比如向量召回结果太少怎么办（降低阈值还是改写查询）、生成内容置信度低怎么办（拒答还是附提示）、模型服务超时怎么办（缓存还是降级到检索原文）。没有兜底策略的方案，相当于把交付成败完全押注在模型单次输出上，风险极高。

我在写技术方案时还要求统一术语表。AI 项目里“解析文档”这个说法太模糊——是解析 PDF 里的文本，还是解析表格，还是解析扫描图片里的 OCR 内容？不同人理解完全不同。术语表里把每个关键操作的定义写清楚，评审会才能开得有效率。

3.3 评测基线：交付的“红绿灯”，必须冻结到字段级

评测基线是 AI 工程流交付里最核心的文档。没有它，你无法回答“这个版本到底比上个版本好还是差”这个最基本的问题。我的评测基线文档包含四个模块：指标定义、测试数据集、评测方法、通过阈值。

指标定义要把质量量化。RAG 问答项目我常用指标包括：召回准确率（Retrieval Recall@K）、答案相关性（相关性打分）、事实一致性（有没有编造）、拒答准确率（该拒的拒了没）、回答延迟（P95 延迟）、单次调用成本。每个指标要有明确的计算方式，比如答案相关性采用“LLM-as-judge + 人工抽检”双轨制。

测试数据集是评测基线的灵魂，至少覆盖正常样本、边界样本、干扰样本三类。正常样本验证主流程；边界样本测试极限情况，比如超长问题、空输入、专业术语、口语化表达；干扰样本测试拒答能力，比如问与业务无关的问题。数据集建好后要冻结，每次评测用同一份数据，结果才有可比性。

通过阈值要分级。建议分 P0 和 P1：P0 指标不达标，版本绝不允许上线，比如事实一致性、核心召回准确率；P1 指标不达标，允许带风险发布，但要记录并限期整改，比如延迟指标、成本指标。阈值要有历史数据支撑，先跑一版基线，看真实分布再定，不要拍脑袋定一个永远达不到的分数。

3.4 变更记录：为什么 AI 项目尤其需要“三条信息绑定”

传统项目也有变更记录，但 AI 项目的变更记录有独特要求：必须把“变更内容、变更原因、评测结果”三件事绑定记录。

原因很简单，Prompt 的变更不是传统代码变更，它没有编译错误，没有报错信息。你调整了一个词，可能回答风格变了，可能在某个边界用例上突然失效了。如果不记录“为什么改”，两周后回看 PR，除了“优化 Prompt”之外什么都说不出来。而且模型也不是一成不变的，API 背后的模型版本可能更新、服务端可能调整参数，这些外部变化也会影响行为。变更记录里要登记评测时的模型版本、Prompt 版本、测试集版本、评测结果，四个信息齐全，才能定位问题。

我日常用 Markdown 维护变更记录，每次变更追加一条，内容包括：变更时间、变更类型（Prompt/模型/参数/逻辑）、变更内容、变更原因、涉及需求编号、评测结果对比。不需要花哨工具，关键是“坚持写”。养成习惯之后，排查线上问题的时间会大幅缩短。

4. 实操实现：从文档骨架到自动化交付流水线

4.1 定义一个最小闭环项目：企业制度问答助手

为了把前面讲的思路串成一个可复现的流程，我拿一个典型项目来演示：企业制度问答助手。业务场景是员工通过自然语言查询公司制度内容，系统基于内部制度文档做 RAG 问答。这个项目规模适中，既有模型链路，又有评测需求，很适合用来演示工程流交付的完整过程。

项目的技术栈比较常见：文档解析用 PyMuPDF，向量化用 text-embedding 接口，向量库用 Chroma，生成用大模型 API，服务框架用 FastAPI。这个组合不是唯一答案，但足以演示工程流交付的闭环。

项目启动第一步，先建 docs 目录，初始化四份文档：

docs/ ├── requirements-matrix.md ├── technical-design.md ├── evaluation-baseline.md └── changelog.md

这个动作看起来简单，实际上是在给整个项目立规矩：所有重要决策先落到文档，再动代码。团队成员从第一天就清楚，这不是一个“先写着玩再说”的项目。

4.2 需求矩阵实例：从业务诉求到可测条目

企业制度问答的需求矩阵，我会先拉一轮相关方访谈，把口头诉求转成文本条目。下面是我在真实项目里会用的矩阵示例（节选）：

每个编号对应后续的评测用例和变更记录。REQ-003 这类“非目标”条目尤其关键，它不是功能需求，而是约束条件，直接指导拒答策略的设计。需求矩阵写完，要跟相关方逐条过一遍，特别是“非目标”部分，双方确认后才能进入开发。

4.3 技术方案实例：RAG 链路每个节点的输入输出

技术方案文档不需要写代码，但必须把链路讲清楚。企业制度问答助手的 RAG 链路，我会这样描述：

文档加载节点，输入是 PDF 文件，输出是纯文本段落。要注意 PDF 里的表格和页眉页脚，需要自定义解析规则。

文本切分节点，输入是长文本，输出是文本块（chunk）。切分策略要结合制度文件的结构：按章节标题优先切分，保证语义完整性；单块长度建议控制在 512 个 token 左右；相邻块保留少量重叠（例如 50 token），避免关键信息被切断。

向量化与入库节点，输入是文本块，输出是向量索引。Embedding 模型选型要考虑中长文本的语义表达能力，入库时把段落对应的制度名称、章节号、版本号作为元数据存下来，召回结果才能给出引用来源。

召回与重排节点，输入是用户问题向量和已有索引，输出是 Top-K 相关文本块。K 值范围取 5 到 10，根据评测结果调整；如果目的是定位精确条款，可以做关键词与向量混合召回再重排，提升命中率。

生成节点，输入是用户问题与召回文本块，输出是最终回答。Prompt 里要明确“仅基于给定材料回答、引用需注明出处、材料不足时拒答”三条约束。

每个节点还要写上兜底策略：比如生成超时走缓存、召回为空走改写查询再试一次、置信度不足走拒答话术。方案评审的时候，评审人看的就是这些边界情况有没有人管过。

以下是生成的链路配置片段（Python 伪代码风格，便于团队讨论）：

# pipeline_config.py CHUNK_SIZE = 512 CHUNK_OVERLAP = 50 EMBEDDING_MODEL = "text-embedding-3-small" TOPK = 8 GENERATION_MODEL = "gpt-4o-mini" FALLBACK_MODE = "reject" # 兜底：拒答 CACHE_TTL = 3600 # 缓存一小时

这套配置就是要写进技术方案并作为参数基准的，后续所有调优都从这个基准开始记录。

4.4 评测基线实例：测试集、指标、阈值怎么定

评测基线的关键动作是“把质量变成数字”。企业制度问答助手的评测数据集，我准备了三类：正常样本 80 条，覆盖各制度主题；边界样本 40 条，覆盖超长问题、专业术语、口语化表达、多轮逻辑；干扰样本 30 条，覆盖非制度问题、敏感问题、情绪化表达。测试集至少达到 150 条，才能支撑有效的回归评测。

下面的字段结构用于记录每条评测样本：

case_id：REQ-001-01 需求编号：REQ-001 输入：“我今年刚入职，可以休几天年假？” 期望要点：["年假天数按入职年限折算", "需引用年假制度章节", "不输出个人余额信息"] 类别：正常

评测时我会写一个自动评测脚本，读取测试集、调用服务接口、把结果与期望要点对比，最后输出一份 JSON 报告。相关代码可以这样组织：

# eval_runner.py import json import requests def load_cases(path): with open(path, "r", encoding="utf-8") as f: return [json.loads(line) for line in f if line.strip()] def evaluate(cases, endpoint): results = [] for case in cases: resp = requests.post(endpoint, json={"question": case["input"]}, timeout=30) answer = resp.json().get("answer", "") hit = all(k in answer for k in case["expected_points"]) results.append({ "case_id": case["case_id"], "input": case["input"], "answer": answer, "hit": hit, }) return results def main(): cases = load_cases("eval_cases.jsonl") results = evaluate(cases, "http://localhost:8000/ask") passed = sum(1 for r in results if r["hit"]) report = { "total": len(results), "passed": passed, "pass_rate": round(passed / len(results), 4), "details": results, } with open("eval_report.json", "w", encoding="utf-8") as f: json.dump(report, f, ensure_ascii=False, indent=2) print(f"pass_rate: {report['pass_rate']}") if __name__ == "__main__": main()

通过阈值我给这个项目定的标准是：P0 指标里，事实一致性通过率不低于 95%，核心召回准确率不低于 90%；拒答准确率达到 100%；P1 指标里，P95 延迟低于 3 秒，单次问答成本低于 0.05 元。注意阈值不是一次定死的，先用 50 条样本跑一遍看真实水平，再定一个“跳一跳够得着”的目标。

4.5 接入自动化流水线，让评测回归成为常态

评测脚本写出来只完成一半，关键是把评测融入开发流程。我常做的是在 CI 里加一个评测任务：每次提交代码或修改 Prompt，自动跑评测集，生成报告，质量门禁拦住不达标的版本。

本地执行时，可以做一个极简的评测入口：

# 执行完整评测 python eval_runner.py # 附带本次变更说明 python eval_runner.py --note "优化拒答话术，降低误答率"

CI 侧我用 GitHub Actions 里的一段配置做演示：

# .github/workflows/eval.yml name: eval-check on: pull_request: branches: [main] jobs: evaluate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.11" - name: Install dependencies run: pip install -r requirements.txt - name: Run evaluation run: python eval_runner.py - name: Check quality gate run: python check_gate.py --min-pass-rate 0.9

这个流程让“文档驱动”真正变成“工程流交付”的一环：需求矩阵提供测试集，评测基线定义阈值，CI 执行自动化回归，变更记录登记每次改动的结果。四类文档在流水线里各就各位，交付就不再依赖某个人的“感觉”。

4.6 交付前检查清单

到了正式交付前的检查阶段，我习惯按下列清单逐项核对：

部署文档是否包含环境依赖、配置项说明、启动命令、模型服务依赖和版本要求。演示脚本是否覆盖 P0 需求对应的主路径和典型边界场景。日志体系是否记录了每次问答的输入、输出、召回来源、模型耗时和错误信息。成本统计是否有单次会话成本预估和月度规模估算。安全与权限检查是否确认知识库内容不过度暴露、接口鉴权已配置、敏感信息不进入日志。

这些条目不是套话，任何一条缺失都可能在真实环境暴露问题。交付不是代码跑起来就算完成，而是“别人拿着文档也能把系统跑起来、能看懂系统为什么这么表现、能接手后续迭代”。

5. 常见问题与避坑实录

5.1 “Prompt 随改随坏”的真凶是版本失控

我在多个团队里都见过这个场景：某天线上回答质量突然波动，排查了半天，最后发现是有人前一天晚上在调试环境里直接改了生产 Prompt，没有提交、没有记录，连他自己都忘了具体改了哪个词。这事儿在传统代码工程里几乎不可能发生，因为代码有 Git 管理，但 Prompt 在很多团队里处于“失控”状态。

解决思路不是禁止修改 Prompt，而是给 Prompt 加和代码同等的管理纪律。Prompt 作为独立的 Markdown 文件放进 Git 仓库，每次修改走 PR 评审；CI 评测门禁强制把关。触发线上变更前必须关联需求编号、评测报告和变更记录。这样哪怕调整一个字，也能回溯到“为什么要改、改了之后评测结果如何”。

5.2 评测集长期不更新，指标会从“护航”变成“假象”

评测基线不是一劳永逸的。测试集长期不更新，模型和 Prompt 就会“过拟合”到这份固定数据上：指标看起来很高，但一遇到真实用户的新问法，表现立刻崩掉。这就是测评数据集的“应试教育”问题。

我的经验是测试集每个月至少补充一轮真实用户问题。线上日志里收集到的失败案例、边界高频提问、新业务场景问法，都应该定期回流到测试集里。评测集不是只增不删，如果某类用例已经连续多轮通过，可以降低它的测试权重，把预算让给新增的难例。让测试集保持“疼痛感”，才能持续暴露问题。

5.3 “文档是干完活再补的”——这个想法在 AI 项目里行不通

有人觉得文档驱动的“文档”是项目结束后的产出物，这种理解在传统项目里可能只是“补文档很麻烦”，在 AI 项目里则直接导致交付失败。因为 AI 项目的核心变量（模型、Prompt、评测）太不稳定，没有前期文档锚定，开发过程根本收敛不下来。

举个例子，没有需求矩阵约束，开发会按自己对“制度问答”的理解设计边界，结果客户一直在问“我入职三年应该休几天”，系统却回答“按制度执行，具体天数请咨询 HR”。这种语义偏差如果到交付验收才发现，返工成本不可估量。文档必须前置，是因为它真正改变的是“开发每一步的决策参照系”。

5.4 文档太多没人更新？把文档绑进流程，而不是挂在墙上

阻力最大的问题永远是“团队不爱写文档”。我试过多种方法，最有效的不是强调“文档很重要”，而是把文档写进流程必经之路：需求矩阵不更新，评测用例不更新，PR 不让合；技术方案不评审，核心代码不得合入；变更记录不填，线上部署不被允许。让文档成为流程的卡点，而不是可选的附加项。

另一个技巧是文档模板化。模板能大幅降低写作门槛，团队只需要填空，不需要从白纸开始。约定好模板后，文档风格自然趋同，评审效率也更高。再配合固定的“文档评审会”节奏，比如每迭代一次评审一次，文档就不会变成写完就弃的一次性垃圾。

6. 最后的实践体会

在 AI 工程流交付里，文档驱动不是“多写文档”，而是“用文档控制不确定性”。模型是概率性的、Prompt 是敏感的、评测是主观的，这些变量控制不住，项目就会变成靠运气交付。把需求矩阵、技术方案、评测基线、变更记录四类文档真正跑进流程里，我体会最深的变化是：开会争论少了，回归测试快了，接手的人敢改代码了。如果你正被 AI 项目的交付质量折磨，不妨从建 docs 目录开始，先写清楚“非目标”，再写评测集，最后再调 Prompt——这个顺序能帮你少走很多弯路。