课程阶段: 第 1 月 · 会调用 本周主题: 第 4 周 · 建立可靠的模型访问层 今日主课: 模型网关:把多家模型变成一个有边界的服务入口 今日成果: 运行一个带模型白名单、超时和统一结果的最小网关,证明拒绝请求不会调用上游 适用岗位: AI 应用工程师 / Agent 工程师 / AI 前端 / AI 后端 预计用时: 25 分钟
今日 TL;DR
模型网关是应用与模型供应商之间的受控入口:统一请求合同,集中授权与预算,并保留每次上游尝试的真实状态。统一 API 不意味着所有模型能力、错误和流式事件都一样。
今日面试经验 Top 3
- 为什么业务代码不能到处直接调用供应商?密钥、模型准入、超时、成本和追踪会分散,故障时难以统一控制。
- 网关该统一什么?统一身份、业务请求、结果与错误分类;供应商特有能力通过显式能力声明保留。
- 网关超时是否可以换模型?先判断有没有产生可见输出或副作用、是否满足能力和数据边界,再决定有限重试或降级。
为什么今天学这个
昨天 9 月 27 日复盘了流式对话状态机:HTTP 200 不是完成证明,收到 done 才进入成功,取消还要确认上游是否终止。今天按课程日历进入第 4 周,把这条对话链路接到模型网关之后。最近七天稿件存在周次标注不一致;本课承接昨天已明确的第 4 周计划,不据旧稿标题伪造补课记录。
“模型网关”可以先理解成一道服务总入口。前端只提交业务请求,网关决定当前用户允许访问哪个模型,带着服务端密钥请求供应商,再把响应转换成业务能理解的事件。它不是另一个会思考的 Agent,也不自动保证模型答案正确。对于只用一家模型的小项目,网关可以是后端一个模块,不必一开始就新增独立微服务。
岗位价值在于能解释集中治理带来的收益与代价:统一入口使限流、审计与切换更方便,但也新增网络跳数和故障点。是否拆成独立服务,要看调用方数量、团队边界与可用性要求;不要为了架构图漂亮而增加系统复杂度。
一张图讲清楚
认证在网关前完成,租户身份来自可信的服务端上下文,不接受客户端随意填写租户名。request_id 对应一次业务请求,attempt_id 对应一次上游尝试;一次业务请求可能重试多次,两者不可混用。模型网关控制的是访问链路,工具执行仍要做自己的业务授权。
三个核心要点
- 统一合同,同时保留能力差异。 业务接口可统一输入、模型别名、截止时间与结果类型,但 JSON Schema、工具调用、图像和流式能力应显式声明。缺少必需能力时拒绝或协商,不能静默删除参数后冒充等价替换。
- 准入和预算要在上游调用之前执行。 从可信身份得到租户,检查模型白名单、输入大小、并发与预计额度;结束后再用实际 usage 对账。预估 token 不是账单事实,供应商未返回 usage 时记录未知并补账,不填零。
- 可观测状态比统一字符串更重要。 记录版本、request_id、attempt_id、首 token 时间、总耗时和终止原因;认证失败、限流、上游错误、超时、部分输出分别处理。日志默认不保存完整用户文本和密钥。
最小可运行示例
保存为 gateway_demo.py,使用 Python 3.11+ 标准库运行 python3 gateway_demo.py。示例不读取密钥、不访问真实模型;用本地异步适配器验证网关控制流。tenant 参数在演示中手工传入,真实系统必须从认证中间件注入。
import asyncio
from dataclasses import dataclass
from uuid import uuid4
@dataclass(frozen=True)
class Request:
request_id: str
model: str
text: str
timeout: float = 0.1
POLICIES = {"team-a": {"demo-fast", "demo-slow"}}
calls = []
async def adapter(model, text):
calls.append(model)
await asyncio.sleep(0.02 if model == "demo-fast" else 0.2)
return {"text": "演示回答:" + text, "usage": None}
async def gateway(tenant, req):
base = {"request_id": req.request_id}
if req.model not in POLICIES.get(tenant, set()):
return base | {"status": "rejected", "code": "MODEL_DENIED"}
if not req.text.strip() or len(req.text) > 1000:
return base | {"status": "rejected", "code": "BAD_INPUT"}
if not 0 < req.timeout <= 1:
return base | {"status": "rejected", "code": "BAD_TIMEOUT"}
base["attempt_id"] = str(uuid4())
try:
result = await asyncio.wait_for(
adapter(req.model, req.text), timeout=req.timeout)
return base | {"status": "completed", "result": result}
except TimeoutError:
return base | {"status": "unknown", "code": "UPSTREAM_TIMEOUT"}
async def main():
ok = await gateway("team-a", Request("r1", "demo-fast", "你好"))
denied = await gateway("team-b", Request("r2", "demo-fast", "你好"))
slow = await gateway("team-a", Request("r3", "demo-slow", "你好"))
print(ok["status"], denied["status"], slow["status"])
print("upstream calls:", len(calls))
assert len(calls) == 2
asyncio.run(main())
预期输出为 completed rejected unknown,第二行是 upstream calls: 2。被拒绝的请求没有到达适配器;慢请求超时后没有被算作成功。这里 asyncio.wait_for 会取消本地协程,但真实 HTTP 请求对应的远端计算是否停止还要供应商确认,因此统一返回 unknown,而非承诺停止计费。示例没有实现持久化配额、并发控制或分布式事务,不应直接充当生产网关。
生产环境会怎么翻车
- 症状:降级后工具调用消失。 根因是把不同模型视为同一能力;处理是先匹配能力矩阵和地区/数据约束,无法满足时返回明确的不支持,保留原请求供用户处理。
- 症状:重试后用户付了两次生成费用。 根因是将超时视为上游未执行;处理是记录每次 attempt,先查任务状态,限制重试预算。供应商不保证幂等时,不能承诺一次计费。
- 症状:A 团队读到 B 团队缓存。 根因是缓存键只含提示词,遗漏租户、权限、模型版本和系统提示版本;处理是隔离敏感数据与缓存作用域,在鉴权之后查缓存。
- 症状:仪表盘成功率很高,用户仍频繁投诉。 根因是把 HTTP 200 算完成;处理是接回昨天的终态协议,只把完成且通过业务校验的任务计成功,取消和部分结果单列。
动手练习
用 20 分钟给示例补充 required_capabilities,为两个演示模型分别声明 text 与 tools 能力。请求需要 tools 而模型只支持 text 时必须拒绝,且 calls 数量不变。然后模拟一次上游限流,返回 retryable 和错误分类,但今天先不自动重试。
完成条件:未授权、超长输入、能力不匹配三种请求都不会调用上游;每次真正调用有不同 attempt_id;超时保留 request_id 与 unknown;打印日志不含完整用户输入。把结果写进本周“多模型网关”作品集 README,明天再把退避策略接入。
面试表达
30 秒回答
我会用一个受控网关集中管理模型访问:从服务端身份读取租户,先做模型白名单、能力和预算检查,再通过适配器调用上游。接口统一请求和错误合同,但保留供应商能力差异。每次业务请求和上游尝试分别追踪;超时不等于远端没执行,流式部分结果也不等于完成。是否独立部署取决于调用方规模与可用性要求。
追问与 3 分钟回答
如果追问“为什么不能直接用一个兼容接口”,我会说明兼容 JSON 格式只解决语法,不解决工具选择语义、结构化输出约束、区域边界与费用归属。我先写能力矩阵,再用真实回归样本验证替换。网关策略应可版本化和回滚,密钥保留服务端;业务工具的授权不能因模型通过网关就省略。
可靠性至少看四类指标:网关自身新增延迟 P95;有效请求中完成且通过业务校验的比例;每个已完成业务任务的总费用(含失败尝试);超时与取消的上游确认率。分母和口径要固定,不能把拒绝流量排除后又声称整个系统成功率提升。网关故障时是否允许旁路必须经过风险评估,不能让旁路绕过权限和配额。
今日自测
1. 基础理解
统一请求格式是否意味着两个模型可以互换?
不意味着。要同时核对工具、结构化输出、流式事件、上下文、区域与价格,再做任务评测。2. 工程取舍
一个用户请求重试三次,只留一个日志记录够吗?
不够。业务 request_id 保持关联,每次 attempt_id 分开记录耗时、状态和用量,才能还原成本与故障。3. 场景应用
网关超时且上游状态查不到,能直接换模型吗?
先标记 unknown,检查是否已经输出、是否有工具副作用以及剩余预算。若决定重试,应明确新 attempt,不能假定原调用没有费用或副作用。市场雷达
Claude Code v2.1.283 于 9 月 25 日新增可选 x-claude-code-prompt-id 网关提示头,并加入更严格的模型版本准入设置。它提供了现实案例:一次用户提示可能产生多个模型请求,需要聚合追踪;该更新不代表所有网关都支持这些头,也不构成岗位需求统计。
权威来源
以下于 2026-09-28 实际访问;精确时间与 HTTP 状态保留在本期取证目录。
- Microsoft Learn:生成式 AI 网关能力 — 网关的模型接入、治理和可观测能力。
- OWASP:Unbounded Consumption — 资源消耗与预算约束。
- Claude Code v2.1.283 官方发布说明 — 提示关联头和模型准入的当期变化。
- MDN:AbortController — 浏览器取消信号边界。
明天会用到
明天在网关内加入超时、指数退避、限流和熔断:先确定哪些错误可重试,再决定何时停止。周三再考虑多模型路由与降级,周六把本周模块拼成可演示网关。