跳到主要内容

AI应用工程

核对日期：2026-05-13。

不稳定项：模型服务商 API、SDK、流式协议、价格、速率限制、网关能力、托管向量/文件服务和前端 AI SDK 版本变化较快；生产接入必须以官方文档、当前账单和压测结果为准。

1. 阶段目标​

本阶段目标是掌握把 LLM、Prompt、RAG 接入真实应用的工程方法。AI 应用不是“前端一个输入框 + 后端调用模型”，而是包含任务建模、模型网关、流式响应、异步任务、上下文存储、缓存、成本、限流、错误处理、用户确认和可观测性的完整系统。

学完本阶段，你应该能做到：

  • 设计一个 AI 功能的端到端调用链路。
  • 区分同步请求、streaming、异步任务、批处理的适用场景。
  • 设计模型 provider adapter 或 AI gateway，避免业务代码散落调用不同模型 API。
  • 处理流式输出的中断、重试、取消、部分结果和前端状态。
  • 建立 token、成本、延迟、错误、prompt version、model version 的调用日志。
  • 设计缓存、限流、预算和降级策略。
  • 设计用户体验：可编辑草稿、引用、确认、撤销、反馈、人工接管。
  • 知道 API key、用户数据、日志和模型输出的安全边界。

本阶段的核心产出是：

  • 一个 AI Web 应用工程设计文档。
  • 一个模型调用封装接口。
  • 一个成本账本和可观测字段清单。
  • 一个 AI 功能错误处理矩阵。

2. 学习前置条件​

建议已完成：

  • 05-Transformer与大模型原理，理解 token、推理参数和模型边界。
  • 06-Prompt与上下文工程，能设计 prompt 模板和结构化输出。
  • 07-RAG与知识系统，理解检索、引用、权限和 eval。
  • 具备 Web 前后端或服务端开发经验。

不要求：

  • 先掌握 Agent 系统。
  • 自建 LLM 推理集群。
  • 一开始就接入所有模型服务商。

3. 核心知识地图​

4. 详细讲义​

4.1 AI 应用和普通 Web 应用的差异​

AI 应用仍然是软件系统，但多了几个典型不确定性：

维度普通 Web 应用AI 应用
输出规则或数据确定概率生成，可能不稳定
延迟通常可控首 token 和总生成时间波动大
成本多与请求和资源相关与输入/输出 token 强相关
错误异常码和业务错误还包括幻觉、格式错、拒答、部分输出
测试单测/集成测试为主需要 eval、样例集和人工反馈
UX用户提交后得到确定结果需要展示生成中、可编辑和确认

工程目标：把概率组件包在确定性系统里，让失败可检测、可恢复、可审计。

4.2 端到端调用链路​

一个基础 AI 功能调用链路：

用户操作
-> 前端校验
-> 应用 API
-> 鉴权和预算检查
-> 构造任务输入
-> 构造 Prompt / Context
-> 调用模型网关
-> 解析和校验输出
-> 保存结果和日志
-> 返回给用户
-> 收集反馈和评测样例

不要让前端直接持有模型 API key。模型调用应该由服务端或可信边缘层完成，便于鉴权、计费、限流、日志和安全治理。

4.3 模型 Provider Adapter​

不同服务商 API 参数、错误码、流式格式、工具调用协议都不同。业务代码不应该直接依赖多个服务商细节。

推荐封装一个统一接口：

type ModelMessage = {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
};

type ModelRequest = {
  model: string;
  messages: ModelMessage[];
  temperature?: number;
  maxOutputTokens?: number;
  metadata?: Record<string, string>;
};

type ModelUsage = {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  costUsd?: number;
};

type ModelResponse = {
  text: string;
  usage: ModelUsage;
  providerRequestId?: string;
  finishReason?: string;
};

注意：这是课程中的概念接口，真实项目要根据 SDK、工具调用、结构化输出和流式事件扩展。

4.4 同步、Streaming、异步任务和批处理​

模式适用优点风险
同步请求短文本分类、抽取简单超时风险
Streaming聊天、长文生成体感延迟低中途失败复杂
异步任务长文档处理、批量生成可重试、可排队状态设计复杂
批处理大量离线任务成本和吞吐更好结果延迟高

选择标准：

  • 用户是否需要实时看到进度。
  • 任务是否可能超过 HTTP 超时时间。
  • 是否需要取消、暂停、重试。
  • 是否可以离线处理。
  • 是否涉及高成本或高风险操作。

4.5 Streaming 工程细节​

Streaming 常用 SSE、WebSocket 或框架封装。它不是“把文本一点点显示”这么简单。

必须处理：

  • 首 token 超时。
  • 中途网络断开。
  • 用户取消。
  • 部分输出保存。
  • 输出结束标记。
  • 安全检查和后处理。
  • 引用、工具结果和文本 delta 的不同事件类型。

前端状态建议：

idle -> submitting -> streaming -> completed
                   -> cancelled
                   -> failed

如果流中断，界面应该明确展示“已生成部分内容”，并允许重试、继续或丢弃。

4.6 异步任务和队列​

长任务不要阻塞请求线程。典型流程：

POST /ai/tasks -> 返回 task_id
worker 消费队列 -> 调用模型/工具 -> 更新状态
GET /ai/tasks/:id -> 查询状态和结果

任务状态建议：

状态含义
queued已入队
running执行中
waiting_user等待用户确认
succeeded成功
failed失败
cancelled已取消
expired超时或过期

异步任务必须考虑幂等。用户重复点击不应该创建多个昂贵任务。

4.7 会话、上下文和结果存储​

AI 应用至少有三类状态：

  • 用户会话：用户输入、模型输出、交互历史。
  • 任务状态：异步任务进度、步骤、错误。
  • 上下文状态：摘要、检索证据、工具结果、用户确认信息。

存储原则：

  • 只保存必要内容。
  • 敏感数据脱敏或加密。
  • 记录 prompt version 和 model version。
  • 保留可复现所需的输入摘要，但避免把密钥、隐私、内部日志写入公开位置。
  • 对可删除数据支持删除或过期策略。

4.8 缓存策略​

AI 缓存分多种：

缓存缓存对象适用风险
Prompt prefix cache重复系统提示或长上下文前缀长上下文应用依赖服务商能力
Exact response cache相同输入的模型结果稳定问答、离线任务陈旧、隐私
Tool result cache搜索、数据库、解析结果工具成本高数据过期
RAG retrieval cache查询检索结果热点问题权限泄漏
Semantic cache语义相似请求复用FAQ错误复用

缓存 key 至少应包含：

  • 用户或租户权限范围。
  • prompt version。
  • model name/version。
  • 输入 hash。
  • RAG 索引版本。
  • 输出 schema version。

不要跨租户共享含敏感内容的缓存。

4.9 限流、预算和成本账本​

AI 成本要按 token 和功能维度记录，而不是只看总账单。

成本账本字段建议：

字段说明
request_id内部请求 ID
user_id / tenant_id用户和租户
feature功能名称
model模型
prompt_versionPrompt 版本
input_tokens输入 token
output_tokens输出 token
cached_tokens缓存 token
tool_calls工具调用次数
latency_ms总延迟
first_token_ms首 token 延迟
estimated_cost预估成本
status成功、失败、取消

预算控制：

  • 用户级日/月额度。
  • 租户级预算。
  • 功能级预算。
  • 单请求 token 上限。
  • 高成本操作二次确认。
  • 异常成本报警。

4.10 错误分类和恢复策略​

AI 应用错误不能只显示“出错了”。

错误类型示例恢复策略
输入错误文本过长、文件格式不支持提示用户修改
鉴权错误无权限访问文档拒绝并记录
预算错误超过 token 或金额上限降级或提示升级
速率限制provider 429排队、退避重试
超时首 token 或总响应超时重试、切模型、异步化
安全拒答模型或策略拒绝给出可行动解释
格式错误JSON 不合法修复重试、降级
部分输出streaming 中断保留部分结果，允许继续
检索失败无相关证据拒答或引导补充

重试必须有上限和退避策略。对非幂等工具调用，不能盲目重试。

4.11 前端 AI 体验设计​

好 AI 体验不是聊天框本身，而是围绕任务给用户控制权。

必须考虑：

  • 输入前：示例、约束、文件状态、隐私提示。
  • 生成中：进度、阶段、可取消。
  • 生成后：可编辑、可复制、可引用、可重新生成。
  • 不确定性：置信度、引用、缺失信息、人工确认。
  • 失败时：明确错误、重试建议、保留输入。
  • 高风险动作：预览、确认、撤销、审批。

典型模式：

场景推荐体验
客服回复生成草稿，人工编辑后发送
数据抽取表格预览，字段级校验
文档问答答案 + 引用 + 原文跳转
代码生成diff 预览 + 测试结果
批量任务任务列表 + 状态 + 失败重跑

4.12 可观测性和评测闭环​

上线 AI 功能后，需要同时看系统指标和质量指标。

系统指标：

  • 请求量。
  • 成功率。
  • P50/P95 延迟。
  • 首 token 延迟。
  • token 用量。
  • 成本。
  • 错误码。
  • provider 可用性。

质量指标：

  • eval 通过率。
  • 用户采纳率。
  • 用户编辑距离。
  • 负反馈率。
  • 引用点击率。
  • 拒答准确率。
  • 人工审核通过率。

闭环流程：

线上日志/反馈 -> 抽样标注 -> 进入 eval 集 -> 回归测试 -> 更新 Prompt/模型/检索 -> 灰度发布

没有评测闭环的 AI 应用会在 Prompt 改动、模型升级和知识库更新时逐渐失控。

5. 关键概念表​

概念含义工程意义常见问题
Provider Adapter模型服务封装层屏蔽 API 差异业务代码直连模型
AI Gateway模型网关路由、限流、日志、fallback权限设计过粗
Streaming流式返回 token/event降低体感延迟中断和部分结果处理差
Async Task后台任务处理长耗时任务缺状态和幂等
Cost Ledger成本账本定位成本和预算只看总账单
Rate Limit限流防滥用和控成本误伤高价值请求
Fallback降级方案提升可用性不评测质量差异
Trace调用链追踪排查模型和检索问题日志缺 token 和版本
Human Confirmation人工确认控制高风险输出交互太重
Eval Loop评测闭环持续质量控制只靠用户反馈

6. 工程案例​

6.1 AI 文档总结工具​

场景：用户上传长文档，系统生成摘要和行动项。

关键设计：

  • 上传后异步解析。
  • 长文档分块摘要再汇总。
  • 生成结果支持编辑。
  • 记录文档版本、prompt version、token 成本。
  • 对解析失败和超长文档给出明确提示。

高风险点：直接同步处理大文件容易超时，解析噪声会污染摘要。

6.2 AI 表单填写助手​

场景：用户输入自然语言，系统生成表单字段。

关键设计：

  • 模型输出结构化 JSON。
  • 字段级校验。
  • 高风险字段需要用户确认。
  • 原始输入和字段来源可追溯。

高风险点：不要让模型直接提交表单，必须先预览和确认。

6.3 AI 客服草稿生成​

场景：客服输入用户问题，AI 根据知识库生成回复草稿。

关键设计：

  • RAG 检索知识库。
  • 输出草稿而非直接发送。
  • 显示引用和相关政策。
  • 记录客服是否采纳和编辑内容。

高风险点：赔付、退款、封号等动作必须走业务系统规则。

6.4 AI 代码 Review 服务​

场景：对 PR diff 做风险审查。

关键设计：

  • 分文件 chunk。
  • 对大 diff 异步处理。
  • 输出文件、行号、风险、影响、建议。
  • 与 CI 测试结果结合。
  • 支持开发者标记误报。

高风险点：模型可能给出泛泛建议，需要 schema 和严重程度标准约束。

6.5 企业知识库聊天​

场景：员工问内部制度和技术文档。

关键设计：

  • 鉴权后检索。
  • 答案带引用。
  • 支持继续追问。
  • 记录未命中问题。
  • 高敏文档不进缓存或日志脱敏。

高风险点：多租户和权限过滤不能交给模型判断。

7. 常见误区与反模式​

反模式表现后果修正
前端直连模型API key 放浏览器密钥泄露、无法控权服务端调用
只有一个输入框没有任务状态和确认用户不信任任务化交互
不记录 token只看请求数成本失控成本账本
无取消重试生成卡住只能刷新体验差、重复扣费状态机和取消
所有任务同步长任务阻塞请求超时和资源占用队列异步化
盲目 fallback失败就换便宜模型质量不可控fallback 也要 eval
跨租户缓存相似问题复用结果数据泄露权限入 cache key
错误提示含糊“发生错误”用户无法处理错误分类和建议
无反馈入口用户只能复制结果无法迭代采纳、编辑、反馈
日志存敏感原文调试方便合规风险脱敏和访问控制

8. 阶段练习​

8.1 调用封装练习​

设计一个模型调用接口，至少包含：

  • 普通文本生成。
  • 结构化输出。
  • streaming。
  • token usage。
  • provider request id。
  • 错误分类。

要求：业务层不直接依赖具体 provider SDK。

8.2 Streaming 练习​

实现或设计一个流式聊天接口，说明：

  • 如何返回 delta。
  • 如何处理用户取消。
  • 如何保存部分输出。
  • 如何处理流中断。
  • 前端状态机如何设计。

8.3 异步任务练习​

为“长文档总结”设计任务表：

  • task_id。
  • status。
  • progress。
  • input_file_id。
  • result_id。
  • error_code。
  • retry_count。
  • created_at / updated_at。

说明如何保证幂等。

8.4 成本账本练习​

为一个 AI 功能设计成本日志，并回答：

  • 哪个用户成本最高？
  • 哪个功能 token 最多？
  • 哪个 prompt version 成本上升？
  • 哪个模型延迟最高？
  • 哪些请求触发了 fallback？

8.5 前端体验练习​

选择一个 AI 功能，画出用户状态流：

  • 输入。
  • 生成中。
  • 部分结果。
  • 完成。
  • 失败。
  • 重试。
  • 人工确认。
  • 反馈。

说明每个状态用户能做什么。

9. 项目任务​

9.1 项目要求​

完成一个 AI Web 应用的设计和最小实现，可以选择：

  • 文档总结工具。
  • 客服回复草稿。
  • 知识库问答。
  • 表单填写助手。
  • 代码 Review 服务。

必须包含：

  • 一个真实任务流。
  • 服务端模型调用封装。
  • streaming 或异步任务。
  • Prompt 版本记录。
  • token、成本、延迟和错误日志。
  • 基础 eval 样例。
  • 前端状态：生成中、取消、失败、重试、完成。
  • 用户确认或编辑机制。

9.2 设计文档模板​

# AI 应用工程设计文档

## 1. 业务场景和目标
## 2. 用户流程
## 3. 系统架构
## 4. 模型调用封装
## 5. Prompt / RAG / 上下文
## 6. Streaming 或异步任务
## 7. 数据存储和日志
## 8. 成本、限流和预算
## 9. 错误处理和降级
## 10. 前端体验状态机
## 11. Eval 和上线验收
## 12. 安全和合规边界

9.3 评分标准​

维度分值标准
架构完整性20前端、API、模型、存储、日志链路清晰
模型封装15provider 差异隔离，错误和 usage 统一
交互体验20有状态、取消、重试、确认和编辑
成本与稳定性20有成本账本、限流、缓存、降级
评测与观测15有 eval、trace、反馈闭环
安全边界10密钥、权限、日志和缓存安全明确

10. 验收题​

  1. AI 应用和普通 Web 应用在工程上有哪些关键差异？
  2. 为什么前端不能直接持有模型 API key？
  3. Provider adapter 应该统一哪些字段和错误？
  4. Streaming 和异步任务分别适合什么场景？
  5. 流式响应中断时应该如何处理用户体验和数据状态？
  6. AI 缓存 key 为什么必须包含权限和版本信息？
  7. 成本账本至少应该记录哪些字段？
  8. 模型调用失败应如何分类和恢复？
  9. AI 输出为什么通常需要用户确认或可编辑机制？
  10. 线上 AI 功能如何形成评测闭环？

11. 延伸阅读​

官方与 SDK 文档​

工程实践资料​

建议阅读方式​

  • 先读目标模型服务商 API，确认消息格式、streaming、错误码和速率限制。
  • 再读 AI SDK 或 Gateway 文档，理解抽象层能解决什么。
  • 最后结合 OWASP LLM Top 10 检查安全边界。

12. 本阶段总结​

AI 应用工程的核心是把不确定的模型输出放进可控的软件系统里。模型负责生成，系统负责权限、状态、成本、校验、观测、用户确认和失败恢复。

你应该形成一个判断：一个 AI 功能能不能上线，不只看 demo 是否惊艳，而要看它在慢、贵、错、断、拒答、越权、输出不完整、用户误操作时是否仍然可控。

下一阶段进入 Agent 系统设计。你会学习如何让模型在受控边界内选择工具、维护状态、推进多步任务，并理解 Agent 的控制流、失败条件和人类在环机制。