主题
交付物：部署文档、培训材料、AI 使用规范
本章要回答的问题：交给客户的除了能跑的系统，还应该有什么才算交付完成？
这一部分的验收标准只有一句：换一个人来，照文档能重装一遍。 系统能跑只是起点；客户还要能安装、能操作、能排障、能审计、能培训新人、能在出问题时找到人。交付物就是把这些能力固定下来。
交付不是交硬盘
一次合格的交付至少有三层：
| 层 | 客户拿到什么 | 没有会怎样 |
|---|---|---|
| 系统 | 代码/镜像、模型、语料、索引、配置 | 跑不起来 |
| 文档 | 架构、部署、运维、验收、许可证 | 换人装不上/不敢改 |
| 人 | 培训、使用规范、支持边界 | 不会用/乱用/出事没人管 |
只交系统，客户得到的是一个“黑盒”；只交文档，客户得到一堆“说明书”。三层都齐，才叫交付。
交付物清单
| 类别 | 交付物 | 最低要求 |
|---|---|---|
| 系统 | 交付包、模型/语料清单、索引、配置 | 可校验、可回滚 |
| 架构 | 架构图、数据流、信任边界、版本 | 能解释“数据从哪到哪” |
| 部署 | 前置条件、安装、配置、验证、回滚 | 换人能重装 |
| 运维 | 启停、健康检查、日志/指标/追踪、备份、升级、故障 | 值班能照做 |
| 验收 | 标准、用例、证据、未决问题、签字 | 每条标准有证据 |
| 培训 | 管理员/操作员/用户材料、练习、考核 | 学员动手做过 |
| 规范 | AI 使用规范、数据分类、引用核验、事件上报 | 使用者签字 |
| 合规 | 模型/语料/软件许可证、NOTICE | 能说明“能不能用/能不能传” |
| 支持 | 联系人、响应时限、升级路径 | 出事知道找谁 |
缺哪一项，就在验收报告里写“未交付/未验证”，不要用“后续补充”糊过去。
一个交付包的结构
text
delivery-<客户>-<版本>/
00-README.md 门面：版本/范围/联系人/目录
01-architecture.md 架构、数据流、信任边界、版本、SLO、限制
02-deploy.md 前置条件、安装、配置、验证、回滚
03-operations.md 启停、健康检查、备份、升级、故障
04-acceptance.md 标准、用例、证据、未决问题、签字
05-training.md 对象、议程、练习、考核
06-ai-usage-policy.md AI 使用规范、数据分类、事件上报
07-licenses.md 模型/语料/软件许可证
MANIFEST.sha256 逐文件校验和目录名不重要，能不能按图索骥才重要。每个文件开头写“读者是谁、什么时候用、读完能做什么”。
部署文档：换人重装
部署文档不是功能列表，是任务清单。按 Diátaxis 的分类，它属于 how-to，不是 tutorial，也不是 reference（引用 [1]）。每一节至少包含：
- 前置条件：系统、Python、GPU/驱动、内存/磁盘、端口、权限、网络。
- 命令：模板阶段变量用
<...>标出，不要写死客户路径；交付包里必须替换成实际值，或从config.env读取，不能留<...>。 - 预期输出：健康检查返回什么、日志长什么样；没有预期输出，读者不知道“成功”是什么。
- 失败时先看哪里：日志、端口、显存、权限；不要只写“排查”。
- 回滚：切回上一版、恢复索引/配置、重跑验证。
三条硬规则：
- 不写密钥/密码；凭据交接走单独流程。
- 版本要钉住：模型、语料、Python、引擎、镜像 tag。
- 回滚必须演练过；只写“可以回滚”不算（演练/变更管理参考 SRE Workbook，引用 [4]）。
培训材料：三类人
培训不是念 PPT，是让学员在自己的环境里完成一次任务。至少分三类：
| 对象 | 要会 | 不要讲 |
|---|---|---|
| 管理员 | 安装、启停、备份、权限、看指标 | CUDA 调优、模型训练 |
| 操作员 | 日常问答、引用核验、反馈分诊、故障上报 | 改代码、改模型 |
| 最终用户 | 提问、看引用、核验、反馈 | 运维、权限配置 |
半天议程的骨架：演示 → 管理员手把手 → 操作员场景演练 → 安全规范案例 → 用户真实问题练习 → 故障桌面演练 → 考核。每个人都要动手；只看演示，第二天就忘。
培训材料要留：课件版本、练习环境、录屏、签到/考核、反馈。培训后 1 周回访一次，把高频问题补进 FAQ/使用规范。
AI 使用规范：能问、不能传、怎么核验
规范不是“请谨慎使用”这种空话。它要回答四个问题：
- 什么数据能进系统？ 公开/内部/受限/禁止四级；禁止级（身份证号、银行卡、密码、密钥）不许粘贴。
- 什么答案能信？ 每个结论要有引用；数字、日期、金额、处罚条款逐字核对；高风险场景第二人复核。
- 什么不能做？ 绕过权限、共享账号、导出受限文档、把模型输出直接发客户/监管、伪造出处。
- 出问题找谁？ 数据泄漏、错误回答、服务故障、权限异常，各自的联系人、时限、升级路径。
AI 使用规范要和 NIST AI RMF 的“治理/映射/测量/管理”对上（引用 [2]），也要覆盖 OWASP LLM Top 10 里的提示注入、敏感信息泄漏、过度代理（引用 [3]）。本书不提供法律意见；涉及合同/合规时让客户法务确认。
一条可抄的引用核验流程：
text
回答 → 找 [n] → 点开引用 → 核对条款号/原文/适用范围 → 数字逐字核对 → 高风险二次复核 → 有疑问提反馈（带 request_id）验收与交接
验收报告要每条标准一个证据：
| 标准 | 证据 |
|---|---|
| 服务可用 | /health 返回 200 的截图/JSON |
| 已知问题正确 | 问题、回答、引用、标准答案 |
| 拒答 | 语料外问题的回答 |
| 权限隔离 | 越权问题的回答 + audit.jsonl |
| 离线可跑 | verify.log + 断网方式 |
| 性能 | 8.3 的压测报告（TTFT/TPOT/并发） |
| 备份恢复 | 恢复演练记录 |
| 文档完整 | check_delivery.py 的输出 |
没有证据的项写“未验证”，不要写“通过”。 8.3/8.6 的 GPU 数据还没回来时，验收报告要明确写“待测”，不能拿估算当实测。
交接时留一份未决问题清单：谁负责、影响、截止日期。口头承诺不算交付。
维护与升级
交付不是终点。至少约定：
- 版本：系统/模型/语料/配置四个版本；每次变更写 changelog。
- 升级：预发验证 → 备份 → 停机窗口 → 切换 → 观察 → 回滚预案。
- 模型/语料更新：重跑 6.x 评估；质量/权限/引用都要复测。
- 过期下线：旧模型/旧索引/旧文档按保留期清理；审计按合规保留。
- 支持边界：工作时间、响应时限、哪些问题免费、哪些是变更单。
最小实现
labs/08-delivery/delivery/：
templates/：8 份核心文档模板（README、架构、部署、运维、验收、培训、AI 使用规范、许可证）。check_delivery.py：交付包自检——文件、标题行、验收/告警/许可证表格、【占位符】/TODO/待填/XXX、明显密钥，以及MANIFEST.sha256的逐文件覆盖与哈希。README.md：模板用法与“交付前最后三件事”。
bash
# 模板结构自检（允许占位符）
python3 labs/08-delivery/delivery/check_delivery.py --allow-placeholders --allow-missing-manifest
# 真实交付包自检（占位符会失败）
python3 labs/08-delivery/delivery/check_delivery.py --dir dist/delivery-<客户>-<版本>自检只做最低门槛，不判断内容好坏；内容正确性靠评审、验收和“换人重装”测试。本机验证结果在 benchmarks/delivery/delivery-check.json：模板/填充包 PASS，缺 MANIFEST、改哈希、删标题、空验收表、config.env 里放密钥等负例都按预期 FAIL。
常见坑
文档是写给构建者自己的。 跳过了前置条件、预期输出、失败处理；换人装不上。
密钥进文档。 部署手册里贴了 API key/密码；交付包一旦外流，密钥就泄漏。
只写“能回滚”，没演练。 真出事时找不到上一版、索引对不上、配置没备份。
培训=念 PPT。 学员没有动手，第二天只会点“发送”。
使用规范太虚。 “请谨慎使用”没有可执行条款；数据分类、引用核验、事件上报都要写死。
验收没有证据。 “演示通过了”不是证据；标准、输入、输出、日志、签字缺一不可。
许可证最后一天才看。 模型不能商用/语料不能再分发，交付包已经发出去了。
把未测写成通过。 8.3/8.6 的 GPU 数据没回来就写“性能达标”，验收报告就失去可信度。
工程含义
交付物是产品的一部分，不是项目尾款。 文档、培训、规范、验收和代码一样，要有版本、评审、演练。
“换人重装”是最便宜的验收。 找一个没参与开发的人，只给交付包；他卡住的地方，就是客户明天会卡的地方。
把不确定性写出来。 未决问题、已知限制、待测项，比“一切正常”更专业；客户需要知道边界。
交付完还要能维护。 版本、升级、回滚、评估复测、许可证复审，都是长期工作；交付包要能支撑下一版。
参考资料
- Procida, D. Diátaxis: A systematic framework for technical documentation authoring. https://diataxis.fr/
- NIST. AI Risk Management Framework. https://www.nist.gov/itl/ai-risk-management-framework
- OWASP. Top 10 for Large Language Model Applications. https://owasp.org/www-project-top-10-for-large-language-model-applications/
- Google SRE. The SRE Workbook（runbook、演练、变更管理）. https://sre.google/workbook/table-of-contents/