《互联网产品的 AI 架构·模型接入与能力边界》目录与学习路径

这本书在讲什么

《互联网产品的 AI 架构》讨论一个具体问题：当模型成为产品的一部分，架构应该在哪里划线。

它不教模型训练，也不比较厂商榜单。它从产品事实出发，讨论能力契约、网关、路由、流式、成本、缓存、降级与治理怎样组合成一条可运行、可回归的链路。贯穿案例仍是「回声」——前两套书分别从服务端与客户端看它，这一套看它如何接入 AI 能力。

四卷的分工是：

卷一先把「一次模型调用」变成「一项产品能力」，后面的性能优化、编排与治理才有稳定的落点。

卷一的结构

卷一 45 篇，由三部分组成：

• 前置 3 篇：序、前言、本目录。
• 正文 39 篇：13 章，每章 3 节。
• 附录 3 篇：术语与判据速查、能力契约与错误码速查、AI 架构评审清单。

每一章对应实验工程 ai-lab 里的一个目录，三个源文件对应三节；测试用 Node 26 的 node --test 直接运行，不引入第三方依赖。第 13 章把前面的模块组合成一条基线，作为卷一的收口。

文中所有模型都是确定性 mock provider，不调用真实 API；除明确标注为本机测试输出的数字外，一律是案例假设值。

第 1 章 AI 能力的产品化边界

先回答“AI 能力和模型调用差在哪”。把能力写成契约：输入、输出、质量、延迟、成本与失败语义，再讨论哪些任务值得用模型、哪些应该交给规则。

• 1.1 产品里的 AI 能力到底是什么
• 1.2 哪些事该用模型，哪些不该
• 1.3 ai-lab：从需求到能力契约

第 2 章 模型选型与能力矩阵

模型不是越贵越好。本章把质量、延迟、成本、上下文与可控性拆成可比较的维度，给出硬约束过滤加加权评分的选型矩阵，并解释多模型并存的必然性。

• 2.1 模型能力的五个维度
• 2.2 选型矩阵：离线评测与在线 A/B
• 2.3 多模型并存的现实

第 3 章 模型网关

网关是产品与模型之间的稳定层。它负责认证、配额、路由、缓存、观测与审计，不负责业务语义。本章用 node:http 写出可运行的零依赖网关与 SSE 流式协议。

• 3.1 模型网关的职责边界
• 3.2 统一契约与流式协议
• 3.3 ai-lab：实现零依赖模型网关

第 4 章 多模型路由

路由决定一次请求落到哪个模型。任务、租户、区域、成本与健康五个维度，哪些该在网关判断、哪些该交给业务，以及路由结果如何解释与灰度。

• 4.1 路由的五个维度
• 4.2 优先级、加权与健康回退
• 4.3 路由的可解释性与灰度

第 5 章 流式输出与交互架构

流式不是把响应切开发送。首字延迟、背压、取消、半截响应与重试语义，任何一项没定义清楚，用户都会看到重复或断裂的文本。

• 5.1 流式的端到端链路
• 5.2 背压、取消与半截响应
• 5.3 流式下的错误与重试语义

第 6 章 上下文与提示的架构位置

提示是产物，不是字符串。模板、变量、版本、所有者与评审，缺一项就无法回滚。上下文预算是提示工程里最容易被忽略的架构约束。

• 6.1 提示是产物，不是字符串
• 6.2 上下文预算与裁剪
• 6.3 提示版本化与发布

第 7 章 结构化输出与工具调用

结构化输出与工具调用把模型从“聊天”变成“执行”。模型只提议，网关与业务决定是否执行；解析失败要有修复预算与降级路径。

• 7.1 结构化输出的契约与校验
• 7.2 工具调用：谁执行、谁授权
• 7.3 解析失败的重试、修复与降级

第 8 章 延迟、成本与质量

延迟、成本与质量构成一个不可能三角。本章把端到端延迟拆到阶段、把 token 成本算到微元，并把取舍写成可复核的 ADR。

• 8.1 端到端延迟预算怎么拆
• 8.2 Token 成本模型与配额
• 8.3 质量、成本与延迟的取舍记录

第 9 章 缓存与复用

缓存能省钱也能制造事故。精确缓存、语义缓存、失效传播与多租户隔离，必须一起设计；命中率不是越高越好。

• 9.1 精确缓存、语义缓存与结果复用
• 9.2 失效、隐私与多租户隔离
• 9.3 命中率的度量与陷阱

第 10 章 降级与兜底

模型一定会不可用。按能力分级决定“可缺、可弱、必须阻塞”，再把小模型、规则、模板与排队组织成有预算的降级链，并用演练验证。

• 10.1 模型不可用时产品该做什么
• 10.2 降级策略：小模型、规则、模板、排队
• 10.3 降级演练与用户可见性

第 11 章 安全与信任边界

把模型接进产品，等于把数据送出域。密钥、租户、提示注入与输出审查，四道边界缺一不可，任何一道都不该由业务方各自实现。

• 11.1 密钥、租户与数据出域
• 11.2 提示注入与输入信任边界
• 11.3 输出审查与内容安全接入

第 12 章 可观测与计量

一次 AI 请求至少要能回答：谁、用了哪个模型、花了多少、结果如何、失败在哪。观测字段、计量对账与质量信号要一起设计。

• 12.1 一次 AI 请求的最小观测字段
• 12.2 计量、账单与配额对账
• 12.3 质量信号的线上采集

第 13 章 卷一收口：ai-lab 能力网关基线

把前十二章的模块组合成一条基线：能力清单、契约矩阵、网关组合与风险清单。这一章不引入新概念，只验证前面的判断能否一起工作。

• 13.1 能力清单与契约矩阵
• 13.2 网关的组合：路由、缓存、降级
• 13.3 基线度量与风险清单

三条阅读路径

不必按顺序读完。按当前问题选一条：

• 第一次接入模型：
• 正在做模型网关：
• 准备上线与治理：

第一条用于第一次接入，第二条用于网关与路由建设，第三条用于上线前的成本、安全与治理检查。

读完卷一应能回答的十二个问题

1. 这个功能为什么必须用模型？如果模型今天不可用，产品行为是什么？
2. 这次请求的质量、延迟、成本预算分别是多少？超了谁来收敛？
3. 网关里哪些逻辑属于平台，哪些属于业务？边界写在哪？
4. 为什么这次请求落在这个模型上？路由结果能否解释？
5. 首字延迟与半截响应用户会看到什么？重试会不会重复文本？
6. 提示改版后如何回滚？旧版本还会被哪些请求命中？
7. 结构化输出失败时，修复预算几次？失败后转人工还是模板？
8. 缓存键包含什么？提示、模型或权限变化后旧结果何时失效？
9. 模型不可用时，哪些能力可缺、哪些可弱、哪些必须阻塞？
10. 一次请求的观测字段能回答哪几个问题？错误会被采样掉吗？
11. 密钥与用户数据在哪一层出域？租户隔离靠什么保证？
12. 这次接入的退出条件是什么？临时降级与临时开关何时删除？

答不上来的问题，就是下一轮设计评审的输入。

实验工程 ai-lab

实验工程位于书稿代码块中，按 // file: 标记抽取即可运行：

# 在抽取后的 ai-lab 目录内
node --test test/*/*.test.ts

三级验证口径：

与站内既有专题的分工

站内已有 AI 推理、LLM 应用、LLMOps 与 MCP 专题，本书不重复工具教程，只讨论产品侧的架构决策：

换句话说：专题回答“这个工具怎么用”，本书回答“这个能力该放在架构的哪里、失败时产品怎么办”。

每章的产出物

每章结束时，团队应该手里多出一样东西，而不只是读完三篇文章：

怎么用这套书

三种常见用法：

• 设计评审前：读第 1、3、8、10 章，先确认能力契约、网关边界、预算与降级，再讨论具体模型。
• 上线前：读第 9、11、12 章，检查缓存隔离、数据出域与观测字段，避免上线后才发现无法定位。
• 事故复盘时：读第 5、7、10 章，区分是流式语义、解析失败还是降级链设计的问题。

每篇末尾都有「常见错误与边界」。如果时间只够读一节，读那一节。

常见问题

这套书需要真实模型 API 吗？ 不需要。全部实验用确定性 mock provider，结论在 L1/L2 可复现；真实模型只影响具体数值，不改变架构判断。

为什么不直接用一个模型？ 因为产品里同时存在质量敏感、成本敏感与延迟敏感的任务。多模型不是技术炫技，而是预算与承诺分层的必然结果。

网关会不会成为新的单点？ 会，所以第 3 章把网关限制在无状态、可水平扩展的职责内，业务语义与长事务不放进来。

卷一只讲接入，不讲 RAG 和 Agent 吗？ 对。卷一先把“一次调用”的契约、预算与失败路径定清楚；没有这层，RAG 与 Agent 的问题会被误判成模型能力问题。

版本与口径

• 运行时：Node 26.5.0，直接运行 .ts，依赖类型剥离。
• 代码限制：禁用 enum、namespace 与构造函数参数属性；本地导入带 .ts 后缀。
• 依赖：只使用 node: 内置模块，零第三方依赖。
• 成本：整数微元，按百万 token 单价换算，向上取整。
• 延迟：除特别标注的本机测试输出外，均为案例假设值。

小结

卷一只做一件事：把「调用一次模型」变成「承诺一项能力」。能力契约定义承诺，网关提供稳定入口，路由与降级保证承诺在异常时仍然可解释，缓存、计量与观测让承诺可以被验证。

后面的卷二到卷四会分别处理知识、工具与治理；它们都建立在这一卷的能力契约上。