AI应用开发
一套面向真实产品落地的 AI 应用开发深度课程，覆盖模型接口、上下文工程、结构化输出、流式体验、工具调用、Agent、RAG、安全、评测、观测、成本和生产架构。
来源策略
优先采用官方 API 文档、SDK 文档、安全/治理框架和标准资料；二手材料不作为关键事实依据。所有单元记录访问日期、来源证据、复核周期和风险说明。
课程结构刻意不绑定单一模型或框架，采用可迁移的 AI 应用工程方法论。
能力地图：从聊天 Demo 到 AI 产品系统
很多团队把 AI 应用开发误解成“接一个模型接口再调提示词”。这个理解能做演示，却撑不住用户权限、数据接地、工具执行、评测、成本和上线后的问题定位。本课先建立完整能力地图：AI 应用不是一个调用点，而是由模型契约、上下文工程、工具边界、知识接地、体验状态、评测观测和治理流程组成的系统。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能画出一个 AI 应用从输入到输出的完整链路
- 能区分 Demo、内部工具、生产产品三种工程要求
- 能把后续课程内容放入统一的能力地图中
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 1 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
很多团队把 AI 应用开发误解成“接一个模型接口再调提示词”。这个理解能做演示，却撑不住用户权限、数据接地、工具执行、评测、成本和上线后的问题定位。本课先建立完整能力地图：AI 应用不是一个调用点，而是由模型契约、上下文工程、工具边界、知识接地、体验状态、评测观测和治理流程组成的系统。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能画出一个 AI 应用从输入到输出的完整链路
- 能区分 Demo、内部工具、生产产品三种工程要求
- 能把后续课程内容放入统一的能力地图中
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 能力终点不是会写 prompt，而是能交付稳定、可审计、可迭代的 AI 功能
- 模型层只负责生成和推理，产品系统必须负责权限、事实来源、状态、回滚和人机边界
- 课程采用反向设计：先定义可交付结果，再倒推知识、技能、评估和项目实践
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
用户输入会先经过身份、权限、意图和风险判断，再进入上下文组装；模型输出还要经过结构校验、工具执行、人工确认或后处理。,当应用需要外部数据时，知识库、搜索、数据库和工具调用会改变模型回答的证据来源，也会引入缓存、失效和注入风险。,生产系统必须记录请求、模型、参数、上下文片段、工具结果、错误和成本，否则无法复盘质量退化。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 把一个聊天框拆成 7 个模块：入口、上下文、模型、工具、知识、观测、治理
- 为每个模块写出最小可行产物，例如 schema、权限矩阵、日志字段、失败重试策略和验收样例
- 用“能否复现错误、能否解释来源、能否控制权限”检验是否超出 Demo 阶段
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 如果需求只需要一次性文案生成，先做单步调用和结构化输出，不急着做 Agent。
- 如果需求依赖私有知识，优先设计 RAG 数据管道和引用机制，而不是单纯加长 prompt。
- 如果需求会改数据、下单、发邮件或调用外部系统，先设计工具权限和确认流程，再讨论模型效果。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 只看模型效果不看系统链路，导致上线后无法定位是检索错、工具错还是模型幻觉
- 课程从工具名开始学，缺少能力地图，最后会堆出互相冲突的框架代码
- 把用户反馈当作评测，缺少固定样本集和验收标准，调优没有方向
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，主流官方文档已经把 AI 应用能力从单纯 completion 扩展到 Responses、tool use、structured output、agent SDK、tracing 和治理框架。课程结构因此以系统能力为主线，而不是以某个模型或单一 SDK 为主线。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
选一个你想做的 AI 功能，写出一页能力地图：输入、输出、数据来源、工具、风险、日志、失败回退和上线门槛。验收标准是别人看完后能判断它是否只是 Demo，还是具备进入真实产品的条件。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Responses API reference](https://platform.openai.com/docs/api-reference/responses)（OpenAI，访问 2026-05-27）：Responses API 是 OpenAI 当前用于生成模型响应、组织输入输出项、流式事件和工具调用的核心接口参考。
- [Vercel AI SDK Core overview](https://ai-sdk.dev/docs/ai-sdk-core/overview)（Vercel，访问 2026-05-27）：AI SDK Core 文档说明统一的 provider 抽象、文本生成、流式生成、结构化输出和工具调用能力。
- [A practical guide to building agents](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)（OpenAI，访问 2026-05-27）：OpenAI 官方实践指南强调从工作流、工具、评估、护栏和可观测性角度构建 Agent，而不是只写提示词。
- [NIST AI RMF Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf)（NIST，访问 2026-05-27）：NIST AI RMF 生成式 AI Profile 提供治理、映射、度量、管理风险的组织级框架。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
模型接口与供应商契约：OpenAI、Claude、Gemini 与 AI SDK
模型供应商的接口不是等价的。OpenAI Responses、Anthropic Messages、Gemini Generate Content 与 Vercel AI SDK 的抽象层在消息结构、工具调用、流式事件、结构化输出和错误语义上都有差异。本课解决“如何设计一个不会被单一供应商绑死的模型调用层”。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能比较不同供应商接口的核心对象和差异
- 能设计自己的模型调用适配层
- 能知道什么时候直接用官方 SDK，什么时候引入 AI SDK 一类统一抽象
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 2 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
模型供应商的接口不是等价的。OpenAI Responses、Anthropic Messages、Gemini Generate Content 与 Vercel AI SDK 的抽象层在消息结构、工具调用、流式事件、结构化输出和错误语义上都有差异。本课解决“如何设计一个不会被单一供应商绑死的模型调用层”。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能比较不同供应商接口的核心对象和差异
- 能设计自己的模型调用适配层
- 能知道什么时候直接用官方 SDK，什么时候引入 AI SDK 一类统一抽象
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 模型请求至少包含模型、输入消息、系统约束、生成参数、工具定义和输出约束
- 供应商抽象不是隐藏所有差异，而是稳定应用层真正依赖的字段
- 流式、工具调用和结构化输出是最容易暴露供应商差异的三个区域
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
OpenAI Responses 以 response 和 output item 为核心，更适合把文本、工具、内置能力和状态组织成统一响应链。,Anthropic Messages 以 messages 和 content blocks 为核心，工具调用通过 tool_use / tool_result 形成客户端执行闭环。,Gemini function calling 使用函数声明和模型建议调用，开发者仍要执行函数并把结果回填。AI SDK 则提供 provider 抽象，把 generateText、streamText、generateObject、tool calling 统一到应用代码层。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 定义一个 ModelClient 接口，只暴露 generate、stream、generateObject、callWithTools 四类能力
- 在适配层保留 raw request/response，便于排障和供应商迁移
- 把供应商特有能力标成 capability flags，例如 supportsReasoning、supportsToolChoice、supportsJsonSchema、supportsCachedContext
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 产品早期如果只接一个供应商，可以直连官方 SDK，但应用代码不要到处散落模型参数。
- 需要多模型路由、A/B、成本控制或供应商降级时，应尽早引入统一适配层。
- 如果你依赖某个供应商独有的内置工具或响应事件，不要假装抽象完全通用，应在能力矩阵里显式标注。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 把 messages 数组当成全行业标准，迁移到 Responses 或 Gemini 时才发现工具结果和流式事件无法对应
- 只存最终文本，不存模型、参数、prompt 版本和 raw usage，后续无法做成本和质量分析
- 在业务代码里直接引用供应商 SDK 对象，导致一次模型切换变成全项目改造
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，官方文档普遍强化工具调用、结构化输出和流式事件，而不是只提供简单文本生成。课程建议从第一天就把这些能力视为模型契约的一部分。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
写一个模型适配层设计表，列出 OpenAI、Anthropic、Gemini 和 AI SDK 在输入、流式、工具、结构化输出、错误、usage 方面的字段差异，并标出你的应用实际依赖哪些字段。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Responses API reference](https://platform.openai.com/docs/api-reference/responses)（OpenAI，访问 2026-05-27）：Responses API 是 OpenAI 当前用于生成模型响应、组织输入输出项、流式事件和工具调用的核心接口参考。
- [Anthropic Messages API reference](https://docs.anthropic.com/en/api/messages)（Anthropic，访问 2026-05-27）：Messages API 参考说明 Claude 请求体、消息格式、系统提示、工具参数、stream 和响应内容块。
- [Gemini API function calling](https://ai.google.dev/gemini-api/docs/function-calling)（Google AI for Developers，访问 2026-05-27）：Gemini function calling 文档说明函数声明、模型选择调用、开发者执行函数和回传结果的流程。
- [Vercel AI SDK Core overview](https://ai-sdk.dev/docs/ai-sdk-core/overview)（Vercel，访问 2026-05-27）：AI SDK Core 文档说明统一的 provider 抽象、文本生成、流式生成、结构化输出和工具调用能力。
- [Vercel AI SDK generating and streaming text](https://ai-sdk.dev/docs/ai-sdk-core/generating-text)（Vercel，访问 2026-05-27）：文本生成文档覆盖 generateText、streamText、流式返回、finish reason、usage 等应用层常用契约。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
Prompt、上下文与结构化输出：把不稳定回答变成可校验结果
AI 应用失败经常不是模型不会回答，而是系统无法判断回答是否满足契约。Prompt 负责表达任务，上下文负责提供材料，结构化输出负责让结果可解析、可校验、可重试。本课把“写提示词”升级为“设计输入输出契约”。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能把自然语言任务改写成输入、约束、输出 schema 和验收规则
- 能选择自由文本、JSON schema、枚举和工具调用之间的边界
- 能处理结构化输出失败、字段缺失和模型过度发挥
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 3 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
AI 应用失败经常不是模型不会回答，而是系统无法判断回答是否满足契约。Prompt 负责表达任务，上下文负责提供材料，结构化输出负责让结果可解析、可校验、可重试。本课把“写提示词”升级为“设计输入输出契约”。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能把自然语言任务改写成输入、约束、输出 schema 和验收规则
- 能选择自由文本、JSON schema、枚举和工具调用之间的边界
- 能处理结构化输出失败、字段缺失和模型过度发挥
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- Prompt 是任务说明，不是系统边界；真正的边界来自 schema、校验、权限和后处理
- 上下文越多不等于越好，必须控制来源、顺序、冲突和时效性
- 结构化输出适合进入数据库、工作流和 UI，不适合承载全部解释性内容
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
模型根据系统提示、开发者提示、用户输入和上下文片段共同生成结果。结构化输出通过 schema 或 SDK 封装约束字段类型、枚举、必填项和嵌套对象。,当结果无法满足 schema 时，应用可以重试、降级为人工审核、返回可修复错误，或拆分任务降低一次生成的复杂度。,对于既需要解释又需要机器处理的任务，常见做法是同时生成 display_markdown 和 structured_result，并用 schema 约束关键字段。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 为一个“生成课程大纲”任务写出 schema：title、audience、units、prerequisites、source_policy、risks
- 把提示词分为目标、材料、约束、输出格式、拒绝条件、示例和自检清单
- 对模型输出跑本地 schema 校验，失败时记录原始输出、错误字段和重试次数
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 需要稳定写库时使用结构化输出；需要创意探索时先用自由文本，再在确认阶段结构化。
- 字段很复杂时不要一次生成整棵对象，先生成大纲，再逐单元生成正文。
- 如果 schema 和 prompt 冲突，应以 schema 和业务校验为准，而不是相信模型会“自觉遵守”。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 提示词里说“请输出 JSON”，但没有 schema 校验，最后线上偶发多余文本导致 JSON.parse 崩溃
- 把所有规则塞进一个超长系统提示，结果上下文冲突且难以版本管理
- 把结构化输出当作事实保证，忽略来源验证和业务约束，导致格式正确但内容错误
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，OpenAI、Google Gemini 和 Vercel AI SDK 都把结构化输出作为官方文档中的核心能力。课程因此要求把 schema、校验和失败处理写入每个真实功能的设计，而不是作为后期优化。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
选择一个需要写入数据库的 AI 功能，设计 prompt、输入上下文和 JSON schema。随后准备 10 条测试输入，记录哪些字段最容易失败，并给出重试或人工审核策略。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs)（OpenAI，访问 2026-05-27）：Structured Outputs 文档说明如何把模型输出约束到 JSON Schema 等可校验结构，适合用于后端契约和自动化工作流。
- [Gemini API structured output](https://ai.google.dev/gemini-api/docs/structured-output)（Google AI for Developers，访问 2026-05-27）：Gemini structured output 文档说明 response schema、JSON 输出和枚举/对象等结构化约束。
- [Anthropic Messages API reference](https://docs.anthropic.com/en/api/messages)（Anthropic，访问 2026-05-27）：Messages API 参考说明 Claude 请求体、消息格式、系统提示、工具参数、stream 和响应内容块。
- [Vercel AI SDK generating structured data](https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data)（Vercel，访问 2026-05-27）：结构化数据文档说明 generateObject、streamObject、schema 驱动输出和校验失败处理方式。
- [Vercel AI SDK Core overview](https://ai-sdk.dev/docs/ai-sdk-core/overview)（Vercel，访问 2026-05-27）：AI SDK Core 文档说明统一的 provider 抽象、文本生成、流式生成、结构化输出和工具调用能力。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
流式体验与任务状态：让长响应和长任务可用
AI 应用里的“慢”有两种：模型在生成长文本，或者系统在做检索、工具调用、评测、写库等长任务。只做一个 loading 会让用户无法判断系统是否卡住，也会让开发者难以定位哪个阶段耗时。本课解决流式输出、任务状态和可观测事件如何设计。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能设计文本流、事件流和任务状态的区别
- 能让用户看到有意义的阶段进度
- 能把流式事件转成日志和性能指标
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 4 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
AI 应用里的“慢”有两种：模型在生成长文本，或者系统在做检索、工具调用、评测、写库等长任务。只做一个 loading 会让用户无法判断系统是否卡住，也会让开发者难以定位哪个阶段耗时。本课解决流式输出、任务状态和可观测事件如何设计。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能设计文本流、事件流和任务状态的区别
- 能让用户看到有意义的阶段进度
- 能把流式事件转成日志和性能指标
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 流式不是只为了显得快，而是为了把不可见的生成过程变成可中断、可观察、可恢复的交互
- 事件状态要区分 searching、thinking、tool_calling、writing、validating、finished、failed
- 后端应该拥有任务状态真相，前端只负责展示和用户操作
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
模型流式接口通常返回增量文本、内容块、工具调用片段、完成事件和错误事件。应用需要把这些事件合并成稳定状态，而不是直接把每个事件暴露给 UI。,长任务可以用队列和任务表保存状态，前端通过 SSE、WebSocket 或轮询读取进度。失败时应保留 partial result、error code、retry token 和用户可理解的下一步。,观测层应记录首 token 时间、总耗时、工具耗时、检索耗时、输出 token、用户取消和错误类型。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 为课程生成任务设计一个状态机：queued、researching、drafting、validating、writing_db、verified、failed
- 把模型 stream 事件映射成 UI 事件：内容增量、引用到达、工具开始、工具结束、校验失败
- 给每个状态定义超时和可恢复策略，例如 30 秒无事件提示重试，写库失败保留草稿
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 短文案生成可以只用文本流；涉及工具调用和多阶段处理时应使用事件流或任务状态表。
- 如果任务可能超过浏览器连接时间，后端必须有可恢复任务 ID，而不是把所有工作绑在一个请求里。
- 用户需要知道“正在查资料”和“正在写作”的区别，但不需要看到底层每个 SDK 事件名。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 前端直接拼接 delta，遇到工具调用或结构化对象时展示错乱
- 后端任务失败后没有保存阶段和错误，用户只能重新生成，开发者也无法复盘
- 只监控 HTTP 200，不监控首 token、完成率、取消率和工具失败率，体验问题长期不可见
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，OpenAI、Anthropic 和 AI SDK 文档都把流式能力作为常规路径。OpenTelemetry 也已经有 GenAI 语义约定，说明生产 AI 应用需要把模型调用纳入通用观测体系。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
为一个“生成长篇 Markdown 文档”的功能画出事件序列图。要求包含首 token、检索完成、工具调用、正文完成、schema 校验、写库完成和失败回滚。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Responses API reference](https://platform.openai.com/docs/api-reference/responses)（OpenAI，访问 2026-05-27）：Responses API 是 OpenAI 当前用于生成模型响应、组织输入输出项、流式事件和工具调用的核心接口参考。
- [Anthropic streaming Messages](https://docs.anthropic.com/en/docs/build-with-claude/streaming)（Anthropic，访问 2026-05-27）：流式文档描述消息增量事件、内容块事件和处理长响应时需要维护的事件状态。
- [Vercel AI SDK generating and streaming text](https://ai-sdk.dev/docs/ai-sdk-core/generating-text)（Vercel，访问 2026-05-27）：文本生成文档覆盖 generateText、streamText、流式返回、finish reason、usage 等应用层常用契约。
- [OpenTelemetry generative AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)（OpenTelemetry，访问 2026-05-27）：OpenTelemetry GenAI 语义约定定义模型请求、响应、token、operation、tool 等可观测字段。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
工具调用与函数契约：让模型安全调用外部能力
工具调用让模型从“回答问题”变成“操作系统”：查数据库、发请求、写文件、创建订单、发送消息。能力变强的同时，风险也急剧增加。本课解决如何设计工具契约、执行边界、确认机制和审计记录。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能定义一个安全的 tool schema 和执行闭环
- 能判断哪些工具必须人工确认
- 能为工具调用设计权限、幂等和审计
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 5 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
工具调用让模型从“回答问题”变成“操作系统”：查数据库、发请求、写文件、创建订单、发送消息。能力变强的同时，风险也急剧增加。本课解决如何设计工具契约、执行边界、确认机制和审计记录。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能定义一个安全的 tool schema 和执行闭环
- 能判断哪些工具必须人工确认
- 能为工具调用设计权限、幂等和审计
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 模型只应该建议调用工具，实际执行权必须留在应用代码
- 工具参数 schema 是安全边界的一部分，但不是全部边界
- 高风险工具必须具备权限校验、二次确认、幂等键和回滚策略
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
工具调用流程通常包含：开发者声明工具名称、说明和参数 schema；模型返回工具调用意图；应用校验参数、权限和风险；客户端或服务端执行工具；把结果回传给模型继续生成。,工具应按最小权限设计，输入只允许业务需要的字段，禁止把任意 SQL、任意 URL、任意 shell 命令直接暴露给模型。,工具结果要区分 machine_result 和 user_visible_summary，避免把敏感字段重新喂给模型或展示给用户。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 为“创建知识单元”定义 tool schema：knowledge_id、version_id、title、slug、content、source_refs、verification_status
- 给工具加前置校验：用户是否有 CMS 权限，version 是否存在，content 是否通过质量门禁
- 设计审计日志：tool_name、caller、arguments_hash、permission_result、execution_result、latency、rollback_id
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 读操作工具可以低风险自动执行；写操作、付费操作、发消息和跨租户访问必须加入确认或审批。
- 如果工具失败会产生副作用，必须设计幂等键和补偿动作。
- 工具越多不代表 Agent 越强；工具集应围绕任务闭环设计，避免把模型变成无约束运维入口。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 工具描述写得过宽，模型把搜索工具当作通用浏览器，访问了不应访问的域名
- 应用只校验 schema 不校验权限，导致模型能替用户执行越权操作
- 工具调用失败后把完整错误栈返回模型，泄露内部表名、token 或路径
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，OpenAI、Anthropic、Gemini 和 AI SDK 都提供工具调用或函数调用官方路径；OWASP 对 Agentic AI 的风险也强调“过度代理”和工具滥用。本课把工具调用视为安全工程，而不是提示词技巧。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
设计 3 个工具：一个只读、一个低风险写入、一个高风险写入。为每个工具写 schema、权限规则、是否需要人工确认、幂等策略和审计字段。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Tools guide for Responses API](https://platform.openai.com/docs/guides/tools?api-mode=responses)（OpenAI，访问 2026-05-27）：官方工具指南说明内置工具、函数调用、工具参数和 Responses API 下工具编排的基本边界。
- [Anthropic implement tool use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use)（Anthropic，访问 2026-05-27）：Anthropic 工具调用文档描述工具定义、tool_use 内容块、客户端执行工具和 tool_result 回传闭环。
- [Gemini API function calling](https://ai.google.dev/gemini-api/docs/function-calling)（Google AI for Developers，访问 2026-05-27）：Gemini function calling 文档说明函数声明、模型选择调用、开发者执行函数和回传结果的流程。
- [Vercel AI SDK tools and tool calling](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling)（Vercel，访问 2026-05-27）：工具调用文档说明 tool 定义、参数 schema、execute 回调、多步调用和应用代码如何控制执行。
- [OWASP agentic AI threats and mitigations](https://genai.owasp.org/resource/agentic-ai-threats-and-mitigations/)（OWASP GenAI Security Project，访问 2026-05-27）：Agentic AI 威胁材料强调代理越权、工具滥用、目标漂移、供应链和人机授权边界。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
Agent 工程：单 Agent、handoff、guardrail、tracing 与可控工作流
Agent 不是“让模型自己循环直到完成”。真正可上线的 Agent 需要明确目标、工具、状态、停止条件、交接规则、护栏和轨迹记录。本课解决如何把 Agent 从概念演示变成可控工作流。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能区分单 Agent、工作流编排和多 Agent handoff
- 能设计 guardrail、stop condition 和人类介入点
- 能用 tracing 思维复盘 Agent 每一步决策
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 6 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
Agent 不是“让模型自己循环直到完成”。真正可上线的 Agent 需要明确目标、工具、状态、停止条件、交接规则、护栏和轨迹记录。本课解决如何把 Agent 从概念演示变成可控工作流。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能区分单 Agent、工作流编排和多 Agent handoff
- 能设计 guardrail、stop condition 和人类介入点
- 能用 tracing 思维复盘 Agent 每一步决策
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- Agent 的核心不是自主，而是把模型推理、工具执行和状态迁移组合成可审计流程
- handoff 适合专家边界清晰的场景，不适合把简单任务拆成一堆角色表演
- guardrail 应覆盖输入、工具、输出、成本、时长和越权行为
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
OpenAI Agents SDK 和 LangChain v1 都强调以 agent、tools、middleware/guardrails、tracing 为中心组织应用。Agent loop 每一步都要决定是否继续推理、调用工具、交接给别的 Agent 或结束。,可控 Agent 通常采用状态机或工作流包裹模型决策：模型可以提出下一步，但应用决定是否允许。,Tracing 记录每次模型调用、工具调用、handoff、guardrail 拦截和最终输出，帮助区分“模型不会”“工具失败”“状态设计不合理”。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 先实现单 Agent：输入任务、检索资料、生成草稿、校验结构、输出报告
- 再加入 guardrail：禁止未授权工具、限制最大步骤、检测敏感信息、控制总 token 和运行时长
- 最后才考虑 handoff，例如研究 Agent 交给写作 Agent，写作 Agent 交给审核 Agent
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 任务流程稳定时优先用显式工作流；只有步骤需要动态决策时才引入 Agent loop。
- 多 Agent 适合职责边界和交接产物清晰的复杂任务，不适合用来替代简单函数调用。
- guardrail 的目标不是让模型“更听话”，而是让系统在模型不稳定时仍能守住边界。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 没有停止条件，Agent 在工具失败后反复重试，烧掉 token 和 API 调用
- 角色拆分过多但没有共享状态和交接 schema，最终只是多轮聊天拼接
- 没有 tracing，用户报告“结果错了”时无法知道是哪一步造成错误
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，Agent 相关官方资料已经明显从“提示词角色扮演”转向 SDK、handoff、guardrail、tracing 和实践指南。本课因此把 Agent 定义为工程系统，而不是简单的自主聊天。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
为“自动生成知识库课程”设计一个 Agent 工作流：研究、生成、质检、写库。写出每一步输入输出、工具、guardrail、失败状态和 tracing 字段。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-js/)（OpenAI，访问 2026-05-27）：Agents SDK 文档覆盖 Agent、handoff、guardrail、tracing、model provider 等面向生产 Agent 的工程构件。
- [A practical guide to building agents](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)（OpenAI，访问 2026-05-27）：OpenAI 官方实践指南强调从工作流、工具、评估、护栏和可观测性角度构建 Agent，而不是只写提示词。
- [LangChain JavaScript agents](https://docs.langchain.com/oss/javascript/langchain/agents)（LangChain，访问 2026-05-27）：LangChain JS agents 文档以 createAgent、model、tools 为基础，强调 agent loop、工具和持久上下文。
- [LangChain v1 JavaScript release notes](https://docs.langchain.com/oss/javascript/releases/langchain-v1)（LangChain，访问 2026-05-27）：LangChain v1 发布文档说明 v1 代理 API、middleware、structured output 和迁移方向。
- [OpenTelemetry generative AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)（OpenTelemetry，访问 2026-05-27）：OpenTelemetry GenAI 语义约定定义模型请求、响应、token、operation、tool 等可观测字段。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
RAG 与知识接地：数据清洗、切分、检索、引用和刷新
模型不知道你的私有知识，也不会自动知道资料是否过期。RAG 的目标不是“把文档塞进向量库”，而是建立可维护的知识接地系统：资料从哪里来、如何切分、如何检索、如何引用、何时刷新、如何验证。本课解决 RAG 的工程闭环。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能设计 RAG 数据管道和检索链路
- 能区分 chunk、embedding、index、retriever、rerank、citation 的作用
- 能为知识库设置刷新、失效和来源核验机制
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 7 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
模型不知道你的私有知识，也不会自动知道资料是否过期。RAG 的目标不是“把文档塞进向量库”，而是建立可维护的知识接地系统：资料从哪里来、如何切分、如何检索、如何引用、何时刷新、如何验证。本课解决 RAG 的工程闭环。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能设计 RAG 数据管道和检索链路
- 能区分 chunk、embedding、index、retriever、rerank、citation 的作用
- 能为知识库设置刷新、失效和来源核验机制
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- RAG 的质量上限往往由数据治理决定，不只由 embedding 模型决定
- 检索结果必须带来源、时间和片段边界，否则很难解释和复核
- 不是所有问题都适合 RAG：强计算、强事务和强实时任务通常需要工具或数据库查询
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
典型 RAG 流程包括数据加载、解析、清洗、切分、元数据标注、embedding、索引、检索、重排、上下文注入、生成和引用输出。,chunk 设计会影响召回和幻觉：太短丢上下文，太长带入噪声；元数据如来源、日期、权限、版本、语言和主题能显著改善过滤。,引用不是装饰，而是把回答绑定到可复核证据。对于时效性资料，还要维护 last_checked_at、expires_at 和触发复核事件。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 为一个课程知识库设计字段：source_url、publisher、accessed_at、published_at、topic、version、license、risk_level
- 选择 20 篇资料做切分实验，比较 300、800、1500 token chunk 的检索命中和回答质量
- 实现回答后自检：每个关键结论是否有引用，引用是否真的支持该结论，是否存在过期资料
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 文档少且结构清晰时，可以先用关键词检索加人工 curated source；文档多且语义查询强时再做向量索引。
- 高风险内容应优先显示来源和限制，不要让模型把推断写成事实。
- 如果用户问题需要实时数据，RAG 应和搜索/工具结合，不能只依赖静态索引。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 把网页整页直接入库，导航、页脚和无关内容污染检索结果
- 没有权限元数据，导致跨租户或内部资料被检索给不该看的用户
- 引用只列来源 URL，不标明片段和访问日期，内容更新后无法追溯当时依据
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，LlamaIndex 等官方资料继续把 RAG 拆成 ingestion、indexing、retrieval、query engine 等工程模块；OpenAI 也提供文件/搜索类工具能力。课程采用“数据管道优先”的 RAG 方法，而不是只讲向量数据库接入。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
选 5 篇官方文档做一个小型 RAG 设计，不必先写代码。输出 ingestion 规则、chunk 策略、metadata schema、检索过滤条件、引用格式和刷新周期。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [LlamaIndex understanding RAG](https://docs.llamaindex.ai/en/stable/understanding/rag/)（LlamaIndex，访问 2026-05-27）：RAG 文档把流程拆成数据加载、索引、检索、上下文增强和生成，适合作为知识接地课程依据。
- [LlamaIndex TypeScript RAG framework](https://developers.llamaindex.ai/typescript/framework/modules/rag/query_engines/)（LlamaIndex，访问 2026-05-27）：TypeScript 文档覆盖 query engine、index、retriever 和用 TS 构建 RAG 应用的主要接口。
- [OpenAI Tools guide for Responses API](https://platform.openai.com/docs/guides/tools?api-mode=responses)（OpenAI，访问 2026-05-27）：官方工具指南说明内置工具、函数调用、工具参数和 Responses API 下工具编排的基本边界。
- [Vercel AI SDK Core overview](https://ai-sdk.dev/docs/ai-sdk-core/overview)（Vercel，访问 2026-05-27）：AI SDK Core 文档说明统一的 provider 抽象、文本生成、流式生成、结构化输出和工具调用能力。
- [NIST AI RMF Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf)（NIST，访问 2026-05-27）：NIST AI RMF 生成式 AI Profile 提供治理、映射、度量、管理风险的组织级框架。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
多模型抽象与路由：能力、成本、延迟、失败降级和供应商切换
真实 AI 产品通常不会永远只用一个模型。不同任务对推理能力、速度、价格、上下文长度、工具调用、结构化输出和区域可用性有不同要求。本课解决如何从单模型调用演进到多模型路由，而不是在业务代码里到处写 if else。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能建立模型能力矩阵
- 能设计基于任务、质量、成本和失败的路由策略
- 能处理供应商切换时的契约差异和回归测试
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 8 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
真实 AI 产品通常不会永远只用一个模型。不同任务对推理能力、速度、价格、上下文长度、工具调用、结构化输出和区域可用性有不同要求。本课解决如何从单模型调用演进到多模型路由，而不是在业务代码里到处写 if else。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能建立模型能力矩阵
- 能设计基于任务、质量、成本和失败的路由策略
- 能处理供应商切换时的契约差异和回归测试
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 模型路由是产品策略，不是简单负载均衡
- 能力矩阵至少包含上下文、结构化输出、工具、流式、视觉、延迟、成本、区域和稳定性
- 降级必须定义可接受质量，不是任何模型失败都能随便换一个模型继续
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
统一抽象层负责把业务任务映射到候选模型，再根据策略选择模型。策略可以是静态配置、A/B 实验、SLA 规则、成本预算、用户等级或失败重试。,路由结果必须写入日志：task_type、selected_model、fallback_reason、latency、usage、quality_score。否则你无法知道成本变化是来自模型升级还是请求结构变化。,供应商切换时最容易出问题的是系统提示语义、工具调用格式、流式事件和结构化输出严格度，因此需要回归样本集。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 为 6 类任务建立模型策略：短摘要、长文生成、代码生成、结构化抽取、RAG 问答、Agent 工具调用
- 给每类任务设置默认模型、备用模型、最大成本、最大延迟和失败重试次数
- 准备 50 条回归样本，每次切换模型或 SDK 版本都跑质量和格式验证
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 如果产品还没有稳定任务分类，先不要做复杂动态路由，先记录数据。
- 高价值任务可以用强模型和人工审核；低价值批处理可以用便宜模型加抽样评测。
- 当供应商能力差异很大时，宁可暴露 capability flags，也不要让抽象层抹平所有差异导致隐性失败。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 把 fallback 当成万能重试，结果失败请求在多个模型间循环，成本翻倍且用户仍拿不到结果
- 只比较单次生成质量，不比较 p95 延迟、失败率和结构化输出合格率
- 模型名散落在业务代码和环境变量里，后续无法统一灰度和回滚
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，多供应商官方接口都在强化工具、结构化输出和流式能力；AI SDK 和 LangChain v1 也强调 provider/model 抽象。课程建议把模型路由建立在任务契约和能力矩阵上，而不是建立在模型排行榜上。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
为你的应用写一份模型能力矩阵和路由策略。至少包含 4 个任务类型、3 个模型候选、2 条降级规则和 5 个必须记录的观测字段。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [Vercel AI SDK Core overview](https://ai-sdk.dev/docs/ai-sdk-core/overview)（Vercel，访问 2026-05-27）：AI SDK Core 文档说明统一的 provider 抽象、文本生成、流式生成、结构化输出和工具调用能力。
- [OpenAI Responses API reference](https://platform.openai.com/docs/api-reference/responses)（OpenAI，访问 2026-05-27）：Responses API 是 OpenAI 当前用于生成模型响应、组织输入输出项、流式事件和工具调用的核心接口参考。
- [Anthropic Messages API reference](https://docs.anthropic.com/en/api/messages)（Anthropic，访问 2026-05-27）：Messages API 参考说明 Claude 请求体、消息格式、系统提示、工具参数、stream 和响应内容块。
- [Gemini API function calling](https://ai.google.dev/gemini-api/docs/function-calling)（Google AI for Developers，访问 2026-05-27）：Gemini function calling 文档说明函数声明、模型选择调用、开发者执行函数和回传结果的流程。
- [LangChain v1 JavaScript release notes](https://docs.langchain.com/oss/javascript/releases/langchain-v1)（LangChain，访问 2026-05-27）：LangChain v1 发布文档说明 v1 代理 API、middleware、structured output 和迁移方向。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
安全与合规：Prompt Injection、越权代理、敏感数据和审计
AI 应用的安全问题不是传统 Web 安全的简单延伸。Prompt Injection 可以操纵模型忽略系统指令；过度代理会让模型调用不该调用的工具；敏感信息可能在上下文、日志、引用和工具结果里泄露。本课解决 AI 应用安全基线。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能识别 LLM 应用和 Agent 的核心安全风险
- 能设计权限、数据最小化、人工确认和审计机制
- 能把安全检查纳入开发、评测和上线流程
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 9 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
AI 应用的安全问题不是传统 Web 安全的简单延伸。Prompt Injection 可以操纵模型忽略系统指令；过度代理会让模型调用不该调用的工具；敏感信息可能在上下文、日志、引用和工具结果里泄露。本课解决 AI 应用安全基线。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能识别 LLM 应用和 Agent 的核心安全风险
- 能设计权限、数据最小化、人工确认和审计机制
- 能把安全检查纳入开发、评测和上线流程
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 不可信内容包括用户输入、网页、文档、检索片段、工具返回和模型上一次输出
- 系统提示不是安全边界，安全边界必须在应用代码、权限系统和工具执行层
- 合规治理不是写免责声明，而是能证明数据如何使用、风险如何控制、问题如何追溯
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
Prompt Injection 的本质是模型把外部内容误当成高优先级指令。防护需要内容分区、指令分层、引用隔离、工具白名单和执行前校验。,Excessive Agency 出现在模型拥有过宽工具、过高权限或缺少人类确认时。高风险行为应要求显式授权，并记录谁授权、授权了什么、是否可撤销。,敏感数据治理要覆盖输入脱敏、上下文最小化、日志屏蔽、保留期限、访问审计和供应商数据处理协议。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 给每个工具标注 risk_level：read_only、low_write、high_write、external_effect
- 设计 Prompt Injection 测试集：伪造系统指令、要求泄露密钥、要求绕过来源、要求调用危险工具
- 为日志字段做敏感性分类，明确哪些字段只能 hash，哪些字段禁止存储
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 面向内部员工的工具也要做权限隔离，因为内部文档和工具结果同样可能被注入内容影响。
- 如果模型输出会触发外部副作用，必须先做人类确认或策略引擎审批。
- 安全评估应随新工具、新数据源、新模型版本和权限变更触发，而不是只在上线前做一次。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 把“请不要泄露秘密”写进提示词，却把完整数据库查询结果放进上下文
- 允许模型生成任意 URL 请求，最终形成 SSRF 或内部系统探测风险
- 日志为了排障存了完整 prompt 和工具结果，长期暴露用户隐私和商业数据
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，OWASP LLM Top 10、OWASP Agentic AI 威胁资料和 NIST GenAI Profile 都把安全治理、过度代理、数据泄露和风险管理列为核心议题。课程将安全作为架构层默认要求，而不是上线前补丁。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
为一个带工具调用的 AI 功能做威胁建模。输出资产、攻击者、入口、不可信内容、危险工具、权限边界、检测规则、人工确认点和审计日志字段。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OWASP Top 10 for Large Language Model Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/)（OWASP，访问 2026-05-27）：OWASP LLM Top 10 提供 Prompt Injection、Sensitive Information Disclosure、Excessive Agency 等应用安全风险分类。
- [OWASP agentic AI threats and mitigations](https://genai.owasp.org/resource/agentic-ai-threats-and-mitigations/)（OWASP GenAI Security Project，访问 2026-05-27）：Agentic AI 威胁材料强调代理越权、工具滥用、目标漂移、供应链和人机授权边界。
- [NIST AI RMF Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf)（NIST，访问 2026-05-27）：NIST AI RMF 生成式 AI Profile 提供治理、映射、度量、管理风险的组织级框架。
- [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-js/)（OpenAI，访问 2026-05-27）：Agents SDK 文档覆盖 Agent、handoff、guardrail、tracing、model provider 等面向生产 Agent 的工程构件。
- [Anthropic implement tool use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use)（Anthropic，访问 2026-05-27）：Anthropic 工具调用文档描述工具定义、tool_use 内容块、客户端执行工具和 tool_result 回传闭环。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
评测、观测与成本治理：从感觉调 prompt 到可迭代系统
AI 应用如果只靠主观体验调 prompt，很快会陷入“今天觉得好，明天又坏”的循环。评测提供质量判断，观测提供运行事实，成本治理保证系统可持续。本课解决 AI 应用如何建立可迭代反馈闭环。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能建立离线评测、线上指标和人工反馈的关系
- 能定义 GenAI 日志和 tracing 字段
- 能把 token 成本、延迟、失败率和质量指标放进同一张仪表盘
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 10 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
AI 应用如果只靠主观体验调 prompt，很快会陷入“今天觉得好，明天又坏”的循环。评测提供质量判断，观测提供运行事实，成本治理保证系统可持续。本课解决 AI 应用如何建立可迭代反馈闭环。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能建立离线评测、线上指标和人工反馈的关系
- 能定义 GenAI 日志和 tracing 字段
- 能把 token 成本、延迟、失败率和质量指标放进同一张仪表盘
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 评测样本应覆盖真实任务、边界情况、恶意输入和回归场景
- 观测不是只看日志，而是把一次请求拆成模型、检索、工具、校验和用户反馈多个 span
- 成本治理要按任务、用户、模型、版本和结果价值分析，不能只看总账单
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
评测闭环通常包括固定样本集、期望结果或评分 rubric、自动评分、人类抽检和回归对比。模型、prompt、RAG 索引或工具变更都应触发评测。,OpenTelemetry GenAI 语义约定为模型操作、token、请求和响应提供统一字段。结合 SDK tracing，可以定位一次失败发生在模型输出、工具执行还是后处理。,成本治理需要预算、速率限制、缓存、降级、批处理和异常告警。高成本请求应能追溯到用户、任务和模型版本。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 为一个 RAG 问答功能准备 30 条评测样本：事实型、比较型、超出知识库、注入攻击、过期资料
- 定义指标：answer_relevance、source_support、schema_valid_rate、tool_success_rate、p95_latency、cost_per_success
- 把每次生成记录为 trace：request_id、user_id、task_type、model、prompt_version、retrieval_ids、tool_calls、usage、final_status
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 早期可以用小样本人工 rubric；进入生产后必须有自动回归和线上指标。
- 模型升级前要比较质量、成本和延迟，而不是只看官方能力说明。
- 如果某类任务价值低但成本高，优先限制长度、缓存结果或换低成本模型，而不是无限调 prompt。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 只保存最终答案，没有 prompt_version 和 source_ids，导致质量下降无法定位
- 只用点赞/点踩做评测，样本稀疏且偏差大，无法指导工程改进
- 没有成本归因，月末账单上涨后不知道是用户增长、模型变更还是重试风暴
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，Agent SDK、LangChain v1 和 OpenTelemetry GenAI 语义约定都强调 tracing/observability；NIST 框架也要求风险度量和持续管理。本课要求把评测和观测作为课程项目的交付物。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
为你要上线的 AI 功能设计一张质量与成本看板。至少包含 6 个线上指标、3 个离线评测指标、2 个成本指标和 3 条告警规则。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenTelemetry generative AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)（OpenTelemetry，访问 2026-05-27）：OpenTelemetry GenAI 语义约定定义模型请求、响应、token、operation、tool 等可观测字段。
- [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-js/)（OpenAI，访问 2026-05-27）：Agents SDK 文档覆盖 Agent、handoff、guardrail、tracing、model provider 等面向生产 Agent 的工程构件。
- [NIST AI RMF Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf)（NIST，访问 2026-05-27）：NIST AI RMF 生成式 AI Profile 提供治理、映射、度量、管理风险的组织级框架。
- [Vercel AI SDK generating and streaming text](https://ai-sdk.dev/docs/ai-sdk-core/generating-text)（Vercel，访问 2026-05-27）：文本生成文档覆盖 generateText、streamText、流式返回、finish reason、usage 等应用层常用契约。
- [LangChain v1 JavaScript release notes](https://docs.langchain.com/oss/javascript/releases/langchain-v1)（LangChain，访问 2026-05-27）：LangChain v1 发布文档说明 v1 代理 API、middleware、structured output 和迁移方向。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
生产架构：队列、幂等、权限、日志、发布和回滚
AI 功能上线后会遇到并发、超时、重试、重复写入、权限绕过、模型升级、提示词回滚、成本异常和用户投诉。生产架构要让这些问题可控。本课解决 AI 应用从功能实现到稳定服务的架构要点。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能设计 AI 请求的同步/异步边界
- 能处理幂等、重试、权限和版本发布
- 能建立上线、灰度和回滚机制
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 11 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
AI 功能上线后会遇到并发、超时、重试、重复写入、权限绕过、模型升级、提示词回滚、成本异常和用户投诉。生产架构要让这些问题可控。本课解决 AI 应用从功能实现到稳定服务的架构要点。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能设计 AI 请求的同步/异步边界
- 能处理幂等、重试、权限和版本发布
- 能建立上线、灰度和回滚机制
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- AI 请求通常包含不可重复的外部成本，因此重试必须受控
- prompt、schema、模型和工具都是版本化资产
- 生产架构的目标不是绝不失败，而是失败时可定位、可恢复、可回滚
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
同步请求适合短任务和交互式体验；异步队列适合长文生成、批量处理、资料检索和多工具链路。任务表应保存状态、输入摘要、版本、进度、错误和产物。,幂等键可以防止用户刷新或网络重试造成重复写库、重复扣费和重复发送消息。写操作工具必须把业务唯一键和执行结果绑定。,发布 AI 功能时，不只发布代码，还要发布 prompt_version、model_policy、schema_version、tool_version 和 evaluation_report。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 设计一个 AI 生成任务表：task_id、user_id、status、request_hash、prompt_version、model_policy、retry_count、result_id、error_code
- 为写库工具加幂等：同一个 knowledge_id + version + slug 重试时更新同一条记录，而不是重复创建
- 制定发布流程：评测通过、灰度 10%、监控 24 小时、异常回滚到上一个 prompt/model 策略
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 用户等待时间可接受且任务简单时走同步；超过 20-30 秒或有多步骤副作用时应走异步任务。
- 模型和 prompt 改动应该像代码一样有版本和回滚，不应直接在生产环境手改。
- 如果功能依赖外部文档和搜索结果，应把来源快照或访问日期写入产物，避免未来无法解释当时结果。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 浏览器断开后后端任务继续写库，但前端不知道结果在哪里
- 用户重复点击生成按钮，创建多个相同版本，后台列表混乱
- 模型升级后没有灰度和回归，结果格式变化导致下游解析失败
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，官方模型接口和 SDK 已经支持复杂事件、工具和结构化输出，生产架构必须随之处理版本、状态和观测。课程把发布回滚作为 AI 功能的基础工程，而不是运维附属项。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
为一个“生成并写入知识库课程”的后台任务设计生产方案。输出 API、任务表、状态机、幂等键、权限检查、日志字段、发布流程和回滚策略。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Responses API reference](https://platform.openai.com/docs/api-reference/responses)（OpenAI，访问 2026-05-27）：Responses API 是 OpenAI 当前用于生成模型响应、组织输入输出项、流式事件和工具调用的核心接口参考。
- [Anthropic Messages API reference](https://docs.anthropic.com/en/api/messages)（Anthropic，访问 2026-05-27）：Messages API 参考说明 Claude 请求体、消息格式、系统提示、工具参数、stream 和响应内容块。
- [Vercel AI SDK Core overview](https://ai-sdk.dev/docs/ai-sdk-core/overview)（Vercel，访问 2026-05-27）：AI SDK Core 文档说明统一的 provider 抽象、文本生成、流式生成、结构化输出和工具调用能力。
- [NIST AI RMF Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf)（NIST，访问 2026-05-27）：NIST AI RMF 生成式 AI Profile 提供治理、映射、度量、管理风险的组织级框架。
- [OpenTelemetry generative AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)（OpenTelemetry，访问 2026-05-27）：OpenTelemetry GenAI 语义约定定义模型请求、响应、token、operation、tool 等可观测字段。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。
综合项目：构建带 RAG、工具调用、评测和上线清单的 AI 研究助手
前面的课程分别讲模型、Prompt、流式、工具、Agent、RAG、安全、评测和生产架构。综合项目把它们组合成一个真实可交付的 AI 研究助手：用户给出主题，系统检索资料、整理来源、生成结构化报告、写入知识库，并通过质量门禁。
- 理解 Web API、JSON 和后台数据写入的基本机制
- 知道大语言模型输入输出、上下文、token 和模型参数的基本概念
- 能阅读官方英文技术文档并区分事实、示例和工程建议
- 能把课程能力组合成端到端项目
- 能产出架构图、数据契约、评测集和上线清单
- 能判断一个 AI 项目是否达到生产试运行标准
- 形成一个可以落地到真实项目的设计或验收产物
- 能标注来源依据、时效窗口和需要项目环境复测的风险
版本：v1.1.0
访问与核验日期：2026-05-27
本课是“AI应用开发”深度课程的第 12 课。正文中的事实性判断以本课 source_refs 中的一手资料为主要依据；无法由来源直接证明的内容按工程经验和方法论建议处理。
这一课解决什么问题
前面的课程分别讲模型、Prompt、流式、工具、Agent、RAG、安全、评测和生产架构。综合项目把它们组合成一个真实可交付的 AI 研究助手：用户给出主题，系统检索资料、整理来源、生成结构化报告、写入知识库，并通过质量门禁。
学习这节课时不要只记工具名。AI 应用开发的核心能力是把不稳定、概率式的模型输出放进可控产品系统：输入要被限定，资料要有来源，工具要有权限，输出要能校验，失败要能定位，版本要能回滚。只要其中一环缺失，Demo 就很难变成真实产品。
学习目标和完成标准
完成本课后，你至少应该达到以下标准：
- 能把课程能力组合成端到端项目
- 能产出架构图、数据契约、评测集和上线清单
- 能判断一个 AI 项目是否达到生产试运行标准
- 能把本课方法迁移到自己的产品需求，而不是只照抄示例代码。
- 能说清楚哪些结论来自官方资料，哪些属于工程判断，哪些仍需要在项目环境里验证。
验收时不要只看“读懂了没有”，而要看是否能交付一个清晰产物：设计表、状态机、schema、评测样本、权限矩阵、日志字段或上线 checklist。
前置知识
- 熟悉 HTTP API、JSON、前后端请求链路和基本数据库写入。
- 知道大语言模型的输入、输出、上下文窗口、token、采样参数和流式返回的基本概念。
- 理解后端系统里的权限、日志、错误处理、重试、幂等和版本控制。
- 如果涉及代码实现，建议使用 TypeScript 或 Node.js 作为练习环境，因为当前主流 AI SDK 和后台系统都能较好衔接。
概念模型
- 综合项目的核心是闭环：输入主题、研究来源、生成内容、验证质量、写入系统、监控运行
- 每个模块都要有清晰契约和失败处理，不能靠模型自然完成所有步骤
- 上线标准必须覆盖内容质量、安全风险、成本和可维护性
可以把本课放进一个四层模型里理解：第一层是产品任务，决定用户真正要完成什么；第二层是模型契约，决定模型能接收什么、产出什么；第三层是工程控制，决定权限、状态、校验和日志；第四层是持续治理，决定评测、成本、风险和更新。任何课程内容如果只停留在第二层，都不足以支撑生产系统。
机制原理
研究助手可以采用显式工作流：topic planning、source search、source filtering、outline generation、unit drafting、schema validation、quality gate、DB write、readback verification。Agent 可以参与动态决策，但关键写入必须由应用代码控制。,RAG/搜索负责资料来源，结构化输出负责课程元数据，工具调用负责写库，评测负责内容质量，可观测性负责上线后定位问题。,质量门禁应检查单元数量、章节深度、来源数量、访问日期、风险说明、版本号和读回结果。
从系统角度看，AI 应用的关键不是模型“聪不聪明”，而是应用能否把一次生成拆成可观察、可验证、可回放的步骤。每一步都应回答四个问题：输入来自哪里，谁允许它进入模型，输出如何被校验，失败后如何恢复。这个问题链会贯穿后续所有课程。
实操路径
建议按以下方式练习：
- 实现前先写项目契约：输入主题、输出 library/version/units schema、允许来源类型、禁止编造规则
- 把系统拆成 5 个可测试模块：研究、生成、校验、写库、读回
- 建立最小评测集：3 个主题、每个主题 5 个验收点、每个验收点有人工 rubric 和自动检查
实操时要保留中间产物。只得到最终回答不够，必须保存 prompt 版本、输入摘要、来源列表、模型参数、工具结果、校验结果和读回结果。这样你才能在内容变浅、格式错误、成本上涨或用户投诉时定位原因。
决策框架
- 如果目标是内部内容后台，优先保证来源可追溯和版本控制；如果目标是公开课程，增加编辑审核和发布流程。
- 如果资料快速变化，必须把 freshness 和 trigger_events 写入数据，而不是只写正文。
- 如果生成失败，应保留中间产物和错误阶段，允许从校验或写库阶段恢复。
一个实用判断是：凡是会影响用户数据、钱、权限、外部系统或公开发布的 AI 行为，都不能只靠 prompt 约束。它必须进入工程控制层，用 schema、权限、确认、日志、评测和回滚来兜底。凡是只影响草稿和探索的行为，可以先用更轻量的模型调用快速验证价值。
失败模式与诊断
常见失败包括：
- 端到端全靠一次大模型调用，失败后无法知道是检索少、内容浅还是写库错
- 没有版本号，重生成时覆盖旧内容，后台无法比较课程演进
- 上线清单只看功能可用，不看安全、成本、观测和回滚
诊断时按链路倒查：先确认用户输入和权限，再看上下文是否正确，再看模型请求和参数，再看工具执行和外部数据，最后看后处理、写库和展示。不要一看到结果不好就直接改 prompt；很多问题实际来自资料、状态、权限或 schema。
现实约束与最新变化
截至 2026-05-27，官方生态已经具备 Responses/Tools、AI SDK、Agent SDK、RAG 框架、OWASP 风险框架和 OpenTelemetry GenAI 观测约定。综合项目要求把这些能力组成一个可维护的后台生产流程。
现实工程中还要考虑团队能力、预算、供应商可用性、数据敏感度和上线节奏。课程里给出的框架默认面向“能逐步进入生产”的系统，如果只是一次性内部试验，可以降低一些治理成本；但只要功能会长期运行，就必须补上版本、评测和观测。
练习、作业与验收
完成一个端到端设计包：架构图、数据 schema、工具列表、权限矩阵、评测样本、质量门禁、写库脚本、读回校验和上线 checklist。验收标准是另一个工程师能按你的设计独立实现第一版。
验收建议采用 4 档 rubric：
- 1 分：只有概念描述，没有可执行产物。
- 2 分：有流程或示例，但缺少失败处理和来源依据。
- 3 分：有完整产物，覆盖正常路径、失败路径和基本验证。
- 4 分：能复现、能审计、能回滚，并能解释成本、安全和时效性边界。
来源与复核
本课使用的主要来源如下：
- [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-js/)（OpenAI，访问 2026-05-27）：Agents SDK 文档覆盖 Agent、handoff、guardrail、tracing、model provider 等面向生产 Agent 的工程构件。
- [Vercel AI SDK Core overview](https://ai-sdk.dev/docs/ai-sdk-core/overview)（Vercel，访问 2026-05-27）：AI SDK Core 文档说明统一的 provider 抽象、文本生成、流式生成、结构化输出和工具调用能力。
- [LlamaIndex understanding RAG](https://docs.llamaindex.ai/en/stable/understanding/rag/)（LlamaIndex，访问 2026-05-27）：RAG 文档把流程拆成数据加载、索引、检索、上下文增强和生成，适合作为知识接地课程依据。
- [OWASP Top 10 for Large Language Model Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/)（OWASP，访问 2026-05-27）：OWASP LLM Top 10 提供 Prompt Injection、Sensitive Information Disclosure、Excessive Agency 等应用安全风险分类。
- [OpenTelemetry generative AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)（OpenTelemetry，访问 2026-05-27）：OpenTelemetry GenAI 语义约定定义模型请求、响应、token、operation、tool 等可观测字段。
- [OpenAI Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs)（OpenAI，访问 2026-05-27）：Structured Outputs 文档说明如何把模型输出约束到 JSON Schema 等可校验结构，适合用于后端契约和自动化工作流。
复核规则：本课建议每 90 天重新检查一次；如果模型接口、工具调用协议、SDK 主版本、安全框架或组织合规要求发生变化，应提前复核。涉及生产系统的代码示例和参数必须在项目环境中重新跑通，不能只以文档描述作为最终验证。