扩展篇：AI 特色功能开发（选学）¶
先完成基础项目，再选择一个小而完整的 AI 功能¶
AI 功能是项目加分项，不是核心业务的替代品
完成第五篇后，你的项目已经具备核心业务闭环、测试记录、部署版本和基础交付材料。如果时间、能力和项目场景允许，可以继续为项目增加一个真正有业务价值的 AI 特色功能。
本扩展篇不要求堆叠技术，也不要求每个项目都增加聊天窗口。你只需选择一个真实问题，完成“模型接入 → 业务融合 → 安全与降级 → 测试交付”的最小闭环。模型服务不可用时，项目原有业务仍应正常运行。
本篇学习目标
理解大模型 API、流式输出、RAG、智能生成、分类、推荐、Tool Calling、MCP 和智能体的基本用途；根据项目需要选择一种能力，将其接入真实业务；通过密钥保护、最少数据、人工确认、成本限制、失败降级和固定测试，使 AI 功能能够稳定演示和安全关闭。
开始学习：AI-01 大模型 API 调用 返回第五篇：测试、部署与成果交付
一、先区分两种“使用 AI”¶
本课程一直鼓励使用 AI 辅助学习和开发，但“使用 AI 开发项目”与“在产品中实现 AI 功能”不是一回事。
| 方式 | 使用者 | 作用 | 示例 |
|---|---|---|---|
| AI 辅助开发 | 学生和开发者 | 帮助分析、设计、编码、测试和检查 | 让编码助手分析错误、生成测试初稿 |
| 产品 AI 功能 | 项目最终用户 | 在真实业务中获得生成、问答、分类或推荐 | 用户生成商品描述、查询办事指南 |
即使项目没有产品 AI 功能，你仍然可以在整个开发过程中合理使用 AI 协作。产品 AI 功能属于选学扩展，不是所有项目的必做要求。
不能用一个通用聊天框代替业务设计
如果 AI 页面与项目用户、数据和业务流程没有关系，它只能证明模型接口可以调用，不能证明项目增加了实际价值。
二、你是否适合进入扩展篇¶
1. 必须满足的进入条件¶
- 项目能够稳定启动；
- 用户可以登录并完成核心业务流程；
- 后端权限和数据归属已经检查；
- 核心功能测试已经执行；
- 严重缺陷已经修复并回归；
- 项目已经完成本地或目标环境部署；
- README 和配置说明基本完整；
- 剩余时间足够实现并测试一个扩展功能。
如果核心流程仍然不通，应先返回第四篇和第五篇完成基础项目。
2. 不建议进入的情况¶
- 项目只能在开发者电脑上偶尔运行；
- 登录、权限或核心状态仍有严重错误；
- 测试和部署尚未完成；
- 团队希望同时实现多个复杂 AI 功能；
- 没有真实业务场景，只是想加入“AI”名词；
- 计划将真实用户隐私直接上传到外部模型；
- 免费额度或模型服务不稳定，但没有降级方案；
- 无法安排固定测试和演示时间。
3. 最重要的停止规则¶
在扩展开发中出现以下情况时，应暂停 AI 功能：
先保住一个完整、可靠的基础项目，再考虑特色功能。
三、本篇完成后你应具备什么能力¶
完成所选路线后，你应能够：
- 从业务问题判断是否真的需要大模型；
- 在后端安全配置模型地址、API Key 和模型名称；
- 将第三方模型调用封装为可替换的客户端；
- 处理输入、输出、超时、限流和外部服务异常；
- 根据需要实现流式输出或 RAG 检索；
- 将生成、分类或推荐放入真实业务步骤；
- 区分 Tool Calling、MCP 与智能体；
- 保持权限、业务状态和最终决定由项目后端控制；
- 估算调用成本，限制输入、输出、频率和步骤；
- 使用固定案例验证效果、安全和失败降级；
- 通过功能开关关闭 AI，并重新完成基础业务；
- 用真实证据演示 AI 功能的价值和限制。
四、学习路线与章节目录¶
| 小节 | 核心问题 | 主要成果 |
|---|---|---|
| AI-01 接入模型 | 怎样安全完成第一次大模型 API 调用？ | 模型客户端、配置、异常和降级 |
| AI-02 流式问答 | 怎样让内容边生成、页面边显示？ | SSE 流式接口、停止和断线处理 |
| AI-03 RAG 知识库 | 怎样让回答依据自己的可信资料？ | 文档分块、向量检索、引用和拒答 |
| AI-04 融入业务 | 怎样实现生成、分类或推荐？ | 一个真实业务 AI 功能和效果评测 |
| AI-05 Tool Calling、MCP 与智能体 | 怎样让模型在受控范围内使用工具？ | 只读工具、权限、审计和概念理解 |
| AI-06 测试交付 | 怎样证明 AI 功能可以安全交付？ | 测试、安全、成本、降级和演示材料 |
不要求顺序完成所有章节
AI-01 是共同基础，AI-06 是统一收尾。中间章节根据项目场景选择，不需要为了“技术全面”全部实现。
五、根据项目选择学习路线¶
路线 A：入门生成¶
适合：
- 商品描述；
- 报修描述；
- 活动通知；
- 工作摘要；
- 内容草稿。
最低成果：
- 一个可编辑草稿；
- 用户确认后再保存；
- 模型失败时手工填写；
- 正常、虚构和超时测试。
路线 B：流式交互¶
适合：
- 较长问答；
- 报告草稿；
- 长文本摘要；
- 需要降低等待感的生成任务。
最低成果：
- 页面逐段显示；
- 能够停止生成；
- 中断不会显示为成功；
- 代理部署后仍能流式返回。
路线 C：知识问答¶
适合：
- 校园办事指南；
- 课程资料；
- 项目使用手册；
- 设备操作说明；
- 组织内部公开知识。
最低成果：
- 可信知识来源；
- 文档分块和向量检索；
- 回答返回真实引用；
- 没有依据时明确拒答；
- 资料更新和权限说明。
路线 D：业务智能¶
适合：
- 报修分类；
- 内容标签；
- 活动推荐；
- 商品推荐；
- 候选项排序和解释。
最低成果：
- 分类只能使用已有类别；
- 推荐只能选择真实候选 ID；
- 后端业务规则优先；
- 有人工修改或规则降级；
- 使用固定数据与基线比较。
路线 E：挑战拓展¶
适合：
- 查询本人业务状态；
- 连接多个标准化工具或资源；
- 完成范围明确的多步辅助任务。
最低成果：
- 一个只读工具；
- 当前身份来自后端登录状态；
- 未知和越权工具调用被拒绝；
- 有步骤、时间和调用上限；
- 能解释 Tool Calling、MCP 和智能体的区别。
推荐大多数学生选择路线 A、B、C 或 D
路线 E 的重点是理解受控工具和协议，不以工具数量或自主步骤多少评价。复杂智能体不是课程项目质量的必要条件。
六、怎样选择一个有价值的功能¶
先回答五个问题：
1. 好功能的共同特征¶
- 与项目主题和核心流程有关；
- 输入、输出和使用位置明确；
- 第一版范围小；
- 结果可以人工核对；
- 失败不会破坏业务数据；
- 有固定案例能够验证；
- 成本和响应时间可控；
- 能在 3—5 分钟内稳定演示。
2. 不合适的功能¶
- 与项目无关的通用聊天；
- 让模型自动决定权限、金额或审批；
- 没有真实候选数据的“推荐”；
- 没有可信资料来源的“知识问答”；
- 把 SQL、Shell 或完整文件系统交给模型；
- 一次计划完成 RAG、智能体、语音和图像全部功能；
- 只能在线运行，没有任何备用或降级方式。
3. 项目与功能示例¶
| 项目类型 | 推荐方向 | 业务价值 | 基础降级 |
|---|---|---|---|
| 图书管理 | 借阅规则 RAG | 快速查找规则和来源 | 查看规则原文 |
| 宿舍报修 | 描述生成或分类 | 提高描述完整度、减少错分 | 手工填写和选择 |
| 校园集市 | 商品描述生成 | 降低发布填写难度 | 手工编辑 |
| 活动报名 | 候选活动推荐 | 帮助筛选真实可报名活动 | 热门或时间排序 |
| 教室预约 | 查询本人预约 Tool | 通过自然语言查询状态 | 原预约记录页面 |
| 课程平台 | 课程资料 RAG | 基于指定资料回答 | 课程资料目录 |
七、本篇必须遵守的七条原则¶
1. 业务优先¶
先定义用户问题，再选择模型能力。技术名称不能代替需求。
2. 后端调用¶
浏览器只调用项目后端。API Key、模型配置和第三方错误处理都在后端。
3. 最少数据¶
只发送完成任务需要的信息，不发送密码、Token、无关隐私和完整数据库。
4. 规则兜底¶
权限、金额、库存、状态和数据归属由后端确定性代码负责。
5. 人工确认¶
模型输出优先作为草稿、建议或候选结果。高风险操作必须明确确认。
6. 失败可降级¶
超时、限流、额度耗尽和模型离线时，保留手工或规则方式。
7. 证据验收¶
不能只展示一次成功截图。需要固定测试、失败案例、成本记录和关闭 AI 后的基础业务验证。
八、AI 功能的最小工程结构¶
推荐职责¶
| 层 | 负责 |
|---|---|
| 页面 | 输入、加载、结果展示、编辑、确认和降级入口 |
| Controller | 登录、请求接收和项目响应 |
| AI Feature Service | 业务场景、提示词、结果校验和人工确认边界 |
| 模型客户端 | 配置、HTTP、超时、平台字段和错误转换 |
| 原业务 Service | 权限、状态、金额、库存和正式数据修改 |
| 测试 | 模拟模型、固定评测、真实小规模验证和降级演练 |
不要为了 AI 功能创建第二套登录、用户表、响应格式或业务规则。
九、三种难度层级¶
| 层级 | 学习目标 | 推荐成果 |
|---|---|---|
| 入门 | 会安全调用模型并处理失败 | 一个文本草稿功能 |
| 进阶 | 能连接业务数据或知识 | 流式、RAG、分类或推荐 |
| 挑战 | 能设计受控工具和多步流程 | 只读 Tool、MCP 体验或最小智能体 |
评价重点不是技术名称，而是：
一个完成度高的文本生成功能，比一个无法控制、无法测试的复杂智能体更有价值。
十、最低交付标准¶
所有路线都应提交：
1. 设计¶
- AI 功能任务卡；
- 业务问题和使用位置；
- 输入、输出和数据来源；
- 模型、业务规则和人工确认边界；
- 明确不做的范围。
2. 实现¶
- 后端模型客户端；
- 环境变量配置；
- 一个真实业务入口；
- 输入与输出校验；
- 超时和错误处理；
- 基础功能降级。
3. 验证¶
- 固定正常案例；
- 边界和错误案例；
- 恶意输入或越权案例；
- 模型服务不可用案例；
- 关闭 AI 后的完整基础流程；
- 少量真实服务验证；
- 自动化测试使用模拟客户端。
4. 交付¶
-
.env.example； - README 配置和关闭说明；
- 测试与效果记录；
- 安全和隐私说明；
- 成本预算；
- 降级矩阵；
- 已知限制；
- 3—5 分钟演示或录屏。
十一、扩展篇成果包¶
建议整理：
代码仓库还应包含：
扩展成果可以在第六篇中继续使用：
| 扩展成果 | 第六篇用途 |
|---|---|
| 功能任务卡 | 说明为什么选择这个 AI 功能 |
| 架构图 | 答辩 PPT 技术设计 |
| 测试报告 | 证明功能经过验证 |
| 安全与成本说明 | 回答工程风险问题 |
| 降级演示 | 证明基础业务独立 |
| 个人贡献记录 | 简历和作品集 |
| 已知限制 | 项目复盘 |
十二、评价建议¶
AI 功能是选学内容时，应与基础项目评分分开。没有选择复杂 AI 技术，不应影响核心业务项目的基础成绩。
| 评价维度 | 关注点 |
|---|---|
| 业务价值 | 是否解决真实问题 |
| 范围控制 | 是否只完成一个小闭环 |
| 工程实现 | 模块边界、配置、异常和测试 |
| 模型效果 | 是否使用固定案例验证 |
| 安全隐私 | 密钥、数据、权限和输出 |
| 成本稳定 | 调用限制、超时和预算 |
| 降级能力 | AI 关闭后基础业务正常 |
| 演示表达 | 能否讲清价值、限制和证据 |
详细评分量规参见 AI-06 测试交付。
十三、AI 在扩展篇中的正确角色¶
AI 编码助手可以帮助：
- 阅读现有项目结构；
- 解释模型平台官方文档；
- 设计最小接口和 DTO；
- 生成客户端和测试初稿；
- 分析异常响应；
- 检查提示词和结构化输出；
- 整理安全、成本和降级清单；
- 生成演示脚本初稿。
AI 不能替代你完成：
- 选择真实业务问题；
- 确认资料和数据是否合法；
- 核对平台接口、价格和模型名称；
- 创建和保护真实 API Key；
- 执行真实测试；
- 判断模型输出是否正确；
- 完成权限和越权验证；
- 确认关闭 AI 后基础业务正常；
- 记录真实成本、耗时和失败结果。
不要把 AI 生成的测试结果当作真实证据
AI 可以生成测试表和预期结果，但不能证明测试已经执行。正确率、耗时、费用、通过数量和失败案例必须来自真实记录。
十四、开始前准备¶
1. 项目材料¶
- 需求说明书；
- 系统设计说明书；
- 权限矩阵；
- 测试报告；
- 部署说明；
- 当前
v1.0版本； - 与候选 AI 场景相关的真实业务数据结构。
2. 模型与平台¶
- 选择可用的模型服务；
- 阅读官方 API 文档；
- 确认模型、接口和计费方式；
- 创建仅用于当前环境的密钥；
- 明确额度和预算；
- 准备模型不可用时的模拟客户端。
3. 安全¶
-
.gitignore已覆盖真实配置； -
.env.example不包含密钥； - 测试数据已经脱敏；
- 不会向模型发送密码、Token 和无关隐私；
- 知道怎样撤销泄露密钥；
- 明确哪些输出需要人工确认。
4. 选择路线¶
本篇小结¶
扩展篇不是要求项目“AI 化”，而是训练你把一种不确定的外部能力放进真实软件工程：
先完成基础项目 → 选择真实问题 → 接入最小模型能力 → 保持后端规则 → 人工确认 → 安全与成本限制 → 固定测试 → 失败降级 → 稳定演示
请从 AI-01 开始理解模型调用，再根据项目选择一条路线。无论选择哪种功能，都应回到 AI-06 完成统一测试和交付。