文档首页
阶段 08 · 工程化部署与模型接入 在线知识文档
学习路线 第 8 / 8 步 · 模块 ⑬⑭工程化部署 / 模型接入← 上一站 ⑦ 记忆与评估路线终点:跑得稳、成本可控、接得任一家模型。学完记得回 学习路线图 复盘。完整顺序:① Python → ② FastAPI → ③④ Prompt → ⑤⑥ Agent → ⑦ RAG → ⑧⑨ 框架与 MCP → ⑩ 多 Agent(回看)→ ⑪⑫ 记忆与评估 → ⑬⑭ 本阶段 · 查看学习路线图 →

跑得稳、接得广、成本可控

前面七个阶段让你「做得出来」,这一阶段解决「上线之后活得下去」:容器化与稳定性让它跑得稳,成本与缓存让账单一可控,多模型接入让豆包、DeepSeek、通义千问、OpenAI 等任一家服务都能接进来、可替换。学完这一章,你就走完了整条路线。

去做在线自测 → AI Agents 学习路线 →
6个章节
24个小节
30道章末小测
测
配套推荐
工程化部署与模型接入在线自测 - 我的图片

按 6 个模块、L1~L5 难度自己测一遍,10 题一组即答即批,适合学完几章之后查漏补缺。 链接:https://myimage.cn/deploy-models/

打开在线自测 →

全部章节

第 01 章

第 1 章 容器化与部署基础

1.1 镜像与容器

容器把代码和依赖打包成一个可复现的镜像(image),镜像启动后就是容器(container)。镜像是静态模板,容器是运行中的实例。它解决了「在我机器上能跑,到你那跑不起来」的环境一致性问题。

1.2 让服务无状态

想让服务能水平扩容,关键是无状态:任一实例都能处理任一请求。会话记忆、上传文件这类状态,要外置到数据库或对象存储,按会话键读取。

有状态(难扩容)无状态(易扩容)
会话存在实例内存会话存在 Redis/数据库
请求必须打到同一台任意实例都能处理
实例挂了状态就丢实例可随时替换

1.3 镜像构建与密钥

DOCKERFILE
# 多阶段构建:编译用大镜像,运行只留产物,显著减小体积
FROM python:3.11 AS build
COPY . /src
RUN pip install --prefix=/install -r /src/requirements.txt

FROM python:3.11-slim
COPY --from=build /install /usr/local
COPY app.py /app/app.py
USER 10001                 # 非 root 运行,最小权限
CMD ["python", "/app/app.py"]

密钥红线:API 密钥绝不写进源码、镜像层或前端。用环境变量 / Secret 管理,并在运行时注入。最小权限还包括非 root 用户、只读文件系统。

1.4 【本章小结】

你学到了什么关键记忆点
镜像 vs 容器静态模板 vs 运行实例
无状态状态外置,实例可任意替换
镜像体积多阶段构建 + 分层缓存
密钥运行时注入,不进镜像/前端
第 02 章

第 2 章 配置、健康检查与发布

2.1 一份镜像,多套配置

用环境变量区分开发/测试/生产配置,同一份镜像适配不同环境,减少环境漂移。启动时校验必需配置(密钥、模型名)是否齐全,让错误在启动期就暴露(fail-fast),而不是运行时才崩。

2.2 两种探针别用错

探针回答的问题失败时
readiness 就绪现在能接请求吗从流量入口摘除,不重启
liveness 存活进程还活着吗重启实例

常见陷阱:把「依赖暂时不可用」绑到 liveness 上,会导致实例被反复重启、故障放大。依赖抖动应交给就绪探针和熔断处理。

2.3 优雅关闭与灰度回滚

优雅关闭:收到停止信号后,先停止接新请求、处理完在途请求再退出,避免发布时切断用户请求。

灰度发布:先让小流量验证,降低故障影响面;一旦有问题,用保留的旧镜像快速回滚。一份上线清单通常包含:配置/密钥、探针、优雅关闭、灰度与回滚、监控告警、评估门禁。

2.4 【本章小结】

你学到了什么关键记忆点
环境变量同镜像不同配置 + 启动校验
readiness未就绪摘流量
liveness假死才重启
发布优雅关闭 + 灰度 + 可回滚
第 03 章

第 3 章 超时、重试与幂等

3.1 超时是第一道防线

外部模型和工具调用都可能变慢。没有超时,慢调用会长期占用连接和线程,最终拖垮整个服务。不同步骤应设分级超时:检索、生成、工具调用各有合理耗时,别用一个全局值。

3.2 重试要挑错误、要有上限

不是所有错误都值得重试:

错误是否重试
401 认证失败 / 400 参数错误否,重试不会改变结果
429 限流可有限重试,遵守 Retry-After
500/502/503 服务端错误可有限退避重试

用指数退避 + 抖动拉长并打散重试间隔,缓解重试风暴;用重试预算(最多 N 次或总时限)限制额外延迟与成本——每次重试都会重新消耗输入 token。

3.3 幂等让重试安全

PYTHON
def call_with_retry(prompt, idem_key, max_try=3):
    for i in range(max_try):
        try:
            # 用幂等键保证同一业务操作重试不会重复扣费/下发
            return model.chat(prompt, idempotency_key=idem_key, timeout=20)
        except TransientError:
            if i == max_try - 1:
                raise
            time.sleep(min(2 ** i, 8) + random.random())  # 退避 + 抖动

幂等指同一操作执行一次和多次效果相同。用幂等键或唯一业务 ID,能防止重试造成重复扣费、重复下单等副作用。流式输出中途断开时,也要如实记录已完成部分,避免重试重复计费。

3.4 【本章小结】

你学到了什么关键记忆点
超时分级设置,防资源耗尽
重试只重试暂时性错误 + 退避抖动 + 预算
幂等幂等键防止重复副作用
可靠性组合超时 + 有限重试 + 幂等 + 预算
第 04 章

第 4 章 限流、熔断与降级

4.1 限流:保护系统不被压垮

限流控制请求速率或并发,保障系统稳定和公平。为不同模型或租户设置独立限流,能把故障和滥用限制在局部。并发上限应基于压测得到的吞吐/延迟曲线和下游配额,而不是拍脑袋。

4.2 熔断:隔离坏掉依赖

熔断像电路保险丝,有三种状态:

状态行为
闭合正常调用,统计失败率
打开直接快速失败/降级,不打扰下游
半开少量试探请求,成功则恢复

别误用:熔断打开期间仍持续打真实调用,就失去了意义;只在半开状态少量试探。

4.3 降级、队列与背压

当依赖不可用时,降级给出可用且诚实的兜底(缓存答案、预设话术),并向用户明确说明能力受限,而不是静默失败或假装正常。对耗时长的任务用队列异步处理削峰,配合背压(容量上限 + 拒绝/降级策略),避免请求无限堆积导致延迟爆炸。

4.4 【本章小结】

你学到了什么关键记忆点
限流控速率/并发,按来源隔离
熔断闭合/打开/半开,快速失败
降级诚实兜底 + 明确告知
队列背压异步削峰,容量有上限
第 05 章

第 5 章 成本、缓存与可观测

5.1 钱花在哪

大模型 API 成本主要来自输入/输出 token 用量与调用次数。输出 token 通常更贵且影响延迟。治理成本的第一步是度量:为每次调用记录 token、模型、调用方,才能找到真正的大头。

5.2 两种缓存

缓存作用注意
提示缓存复用长提示前缀,降本降延迟命中率靠前缀稳定
结果缓存重复问题直接返回答案键要含影响因素,设 TTL

缓存风险:涉及隐私或时效的结果,必须按用户隔离缓存键并设置 TTL,否则会串扰或返回过期答案。

5.3 分级路由与预算

模型分级路由:简单任务用便宜小模型,复杂任务用强模型,在可接受质量下显著降本。但别把所有任务都压到最小模型——复杂任务质量下降带来的返工与重试,可能反而更贵。

最后用预算上限与告警兜底,成本异常飙升时能及时发现止损。成本治理 = 度量 + 缓存 + 路由 + 告警。

5.4 【本章小结】

你学到了什么关键记忆点
成本构成输入/输出 token + 调用次数
缓存提示缓存 + 结果缓存,注意隔离与 TTL
分级路由按难度选模型,质量是约束
治理闭环度量 + 缓存 + 路由 + 预算告警
第 06 章

第 6 章 多模型接入、选型与安全

6.1 统一适配层

不同厂商在消息格式、工具调用参数、错误码、流式事件上差异很大。统一适配层把这些差异收敛到一处,向上提供一致的消息与工具接口,让业务代码不依赖任何一家 SDK。

PYTHON
class ModelAdapter:
    def chat(self, messages, tools=None, **kw): ...

class OpenAIAdapter(ModelAdapter): ...
class DoubaoAdapter(ModelAdapter): ...   # 豆包
class DeepSeekAdapter(ModelAdapter): ...
class QwenAdapter(ModelAdapter): ...     # 通义千问

# 业务只依赖抽象;换模型改配置与适配器,不改业务逻辑
model = ADAPTERS[config.MODEL_PROVIDER]()

许多服务提供 OpenAI 兼容接口,可让已有客户端最小改动接入,降低迁移与多模型切换成本——但细节能力仍有差异,需逐项验证。

6.2 选型维度

维度关注点
能力质量在你真实任务上的表现,而非跑分
延迟 / 吞吐首字延迟、并发能力
成本输入/输出单价
上下文长度能否装下你的资料
合规数据是否用于训练、存储地域、保留期限

合规是硬约束,必须写进选型标准。故障转移要有条件、有顺序、有记录:主模型失败(可重试错误)时切备用,并考虑成本与数据合规。

6.3 安全边界

风险防范
密钥泄露后端代理调用,密钥只在服务端,前端不接触
提示注入不可信内容与指令隔离、工具最小权限、输出校验
间接注入检索来的网页/文档内容同样视为不可信输入

间接提示注入尤其危险:恶意指令藏在被检索的文档里,诱导 Agent 越权。RAG 场景要把外部内容当成「数据」而非「指令」,限制工具权限并校验动作。

6.4 【本章小结】

你学到了什么关键记忆点
统一适配层屏蔽差异,业务不绑厂商
选型能力/延迟/成本/上下文/合规
故障转移有条件、有顺序、有记录
安全密钥留后端 + 防(间接)提示注入