08.8 阶段 7:AI 服务化落地与部署
所属:全栈开发面试题库 / 学习路径 / 08 Python 全栈
本页目录
一、阶段定位
前面阶段做的都是 CRUD、缓存、异步,本阶段把模型能力封装成可上线的在线服务。核心不是「怎么调模型 API」,而是「怎么把它做成稳定、可观测、可部署的服务」:模型加载放哪一层、流式响应怎么不被缓冲、超时与降级怎么配、Docker 镜像怎么瘦身、健康检查与滚动发布怎么演练。本阶段的产物是一个部署文档完整的 AI 服务化接口。
与前后阶段的衔接:因为阶段 6 已理解异步与性能定位,本阶段的流式响应、worker 配置才有抓手;因为阶段 5 已理解连接池与任务队列,本阶段的批量推理、超时控制才有基础。跳过本阶段,前面的代码只能在本地跑,无法上生产。
原有卡点及判断依据:
- 把模型加载写进每次请求导致首字延迟不可接受:判断现象是接口每次请求都加载模型,响应时间从毫秒级变成秒级。见 5.1。
- 流式响应被框架缓冲导致客户端迟迟收不到数据:判断现象是 SSE 接口等几秒才一次性返回全部内容。见 5.2。
- 镜像里缺少系统依赖或模型文件路径写死:判断现象是容器启动报
OSError: libgomp.so.1或找不到模型文件。见 5.6。 - 部署依赖本地环境,测试与生产行为不一致:判断现象是本地跑通,容器里报错。见 5.6。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能把模型加载放在应用启动时,请求只做推理 | 首字延迟在可接受范围 |
| 能实现流式响应,首字延迟可测量 | SSE 接口客户端逐段收到 |
| 能配置请求超时、限流与降级 | 上游慢响应不拖垮服务 |
| 能说清 uvicorn 与 gunicorn 的角色,配置 worker 数 | 压测下 worker 数合理 |
| 能写 Docker 多阶段构建,镜像体积可控 | 镜像不含编译依赖 |
| 能配健康检查,完成一次滚动发布与回滚演练 | 健康检查通过,回滚成功 |
建议学时:
- 全职:2 周,约 60 小时。模型封装 15 小时、流式与向量 15 小时、部署与 Docker 20 小时、健康检查与发布 10 小时。
- 在职:5–6 周,约 70 小时。
学时分配建议:模型加载与封装 20%、流式响应 15%、向量库 10%、超时限流降级 15%、uvicorn/gunicorn 10%、Docker 20%、Nginx 与发布 10%。
三、先修自检
| 先修项 | 合格标准 | 不合格时回到 |
|---|---|---|
| FastAPI | 能写异步端点 | 08.5 阶段 4 |
| asyncio | 能写 async def 与 await |
08.7 阶段 6 |
| HTTP 与 Nginx | 能说清反代 | 08.1 阶段 0 |
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| 推理服务封装 | 模型加载层级、同步/异步接口、错误降级 | 会用 | 10.5 LLM 工程化 |
| 流式响应 | SSE、逐段生成、首字延迟 | 会用 | 10.5 LLM 工程化 |
| 向量库 | pgvector、FAISS、Milvus 客户端 | 会用 | 05.6 向量数据库与语义检索 |
| 超时与限流 | 上游超时、降级、成本统计 | 会用 | 10.5 LLM 工程化 |
| uvicorn/gunicorn | ASGI 服务器、worker 数公式 | 能讲清原理 | 08.1 容器化 |
| Docker 多阶段 | 构建依赖与运行时依赖分离 | 会用 | 08.1 容器化 |
| Nginx 与发布 | 反代、超时、健康检查、滚动发布 | 会用 | 08.4 CI/CD 与可观测性 |
进度管理建议:本阶段以「能部署上线」为目标,建议本地用 Docker Compose 起服务。《知识点全清单》「数据与 AI 服务化」「部署」段是全量清单。
五、分模块精讲
5.1 推理服务封装与模型加载层级
为什么需要它:模型加载耗时几秒到几十秒,如果每次请求都加载,首字延迟不可接受。正确做法是应用启动时加载一次,常驻内存。
核心机制:
- 模型加载放在应用启动事件(FastAPI
lifespan),不放在请求函数里。 - 多 worker 时每个 worker 独立加载,内存 = 模型大小 × worker 数;需要权衡。
- 错误降级:上游模型 API 超时或报错时,返回兜底响应,不让接口 500。
- 成本统计:按接口统计 token 消耗,便于核算成本。
最小可运行示例:
from contextlib import asynccontextmanager
from fastapi import FastAPI
ml_model = None
@asynccontextmanager
async def lifespan(app: FastAPI):
global ml_model
# 启动时加载一次
ml_model = load_model("path/to/model")
yield
# 关闭时释放
ml_model = None
app = FastAPI(lifespan=lifespan)
@app.post("/predict")
async def predict(text: str):
try:
result = ml_model.predict(text)
return {"result": result}
except TimeoutError:
return {"result": "服务繁忙,请稍后重试", "degraded": True}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 首字延迟几秒 | 每次请求加载模型 | 启动时加载,放 lifespan |
| 内存爆掉 | worker 数 × 模型大小 | 减少 worker 或用共享内存 |
面试考法:常问「模型加载放哪一层」。答「应用启动事件,常驻内存;请求只做推理」。
5.2 批量推理与流式响应
为什么需要它:模型逐段生成时,用户等全部生成完才看到响应会很焦虑;流式响应让客户端逐段收到。批量推理则是把多个请求合批,提高 GPU 利用率。
核心机制:
- 流式响应:FastAPI
StreamingResponse,用生成器逐段 yield。 - SSE(Server-Sent Events):
text/event-stream,客户端用EventSource接收。 - 关键:Nginx 不要缓冲,配
X-Accel-Buffering: no;框架不要在中间件里收集整个响应。 - 批量推理:合批时机(攒够 N 个或等 T 毫秒),提高吞吐。
最小可运行示例:
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
async def generate(text: str):
# 模拟模型逐段生成
for i in range(5):
yield f"data: 第{i+1}段\n\n"
await asyncio.sleep(0.5)
@app.get("/stream")
async def stream(text: str):
return StreamingResponse(
generate(text),
media_type="text/event-stream",
headers={"X-Accel-Buffering": "no"}, # 禁止 Nginx 缓冲
)
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 客户端等几秒才一次性收到 | Nginx 或框架缓冲 | 加 X-Accel-Buffering: no;不用收集整个响应的中间件 |
| 首字延迟高 | 模型预热慢 | 启动时预热一次 |
面试考法:常问「流式响应怎么不被缓冲」。答「StreamingResponse 逐段 yield,Nginx 配 X-Accel-Buffering: no,中间件不收集响应」。
5.3 向量库客户端
为什么需要它:RAG 场景要把文本编码成向量,在向量库里检索相似条目。pgvector、FAISS、Milvus 各有适用场景。
核心机制:
- pgvector:PostgreSQL 扩展,在关系库内做向量检索,适合中小规模、需要事务一致性。
- FAISS:Meta 开源库,适合本地或服务端高性能检索,不支持分布式持久化。
- Milvus:专用向量数据库,适合大规模、分布式部署。
- 向量维度与索引类型(HNSW、IVF)影响召回率与延迟。
最小可运行示例:
# pgvector 示例
from pgvector.sqlalchemy import Vector
from sqlalchemy import Column, Integer, create_engine
from sqlalchemy.orm import DeclarativeBase
class Base(DeclarativeBase):
pass
class Document(Base):
__tablename__ = "documents"
id = Column(Integer, primary_key=True)
embedding = Column(Vector(1536)) # 1536 维
# 检索
# SELECT * FROM documents ORDER BY embedding <-> '[向量]' LIMIT 5
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 检索延迟高 | 没建索引或维度太大 | 用 HNSW 索引,降维 |
| 召回率低 | 索引类型选错 | 按数据量选 HNSW/IVF |
面试考法:常问「pgvector、FAISS、Milvus 怎么选」。答「中小规模要事务一致性选 pgvector;本地高性能选 FAISS;大规模分布式选 Milvus」。
5.4 超时、限流与降级
为什么需要它:上游模型 API 慢或挂,不能拖垮自己的服务。必须有超时、限流、降级三件套。
核心机制:
- 超时:httpx
timeout=5.0;流式响应单独配。 - 限流:按接口或按用户限制 QPS,用 Redis 计数器或令牌桶。
- 降级:上游报错时返回兜底响应,不抛 500。
- 成本统计:记录每次调用 token 数,按接口核算成本。
最小可运行示例:
import httpx
async def call_model(prompt: str) -> str:
try:
async with httpx.AsyncClient() as client:
resp = await client.post(
"https://api.example.com/v1/chat",
json={"prompt": prompt},
timeout=httpx.Timeout(5.0, connect=2.0),
)
resp.raise_for_status()
return resp.json()["content"]
except (httpx.TimeoutException, httpx.HTTPError):
return "服务繁忙,请稍后重试" # 降级
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 上游慢导致自己服务排队 | 没配超时 | 设 timeout |
| 超时叠加重试放大风险 | 超时短又重试多次 | 超时与重试次数乘积要合理 |
面试考法:常问「超时与重试怎么配」。答「超时设为预期延迟的 1.5–2 倍;重试次数 2–3 次,指数退避;乘积不要超过用户可接受等待时间」。
5.5 uvicorn 与 gunicorn worker 配置
为什么需要它:uvicorn 是 ASGI 服务器,gunicorn 常作为进程管理器。worker 数决定并发能力与内存开销。
核心机制:
- uvicorn:直接跑 ASGI 应用,适合开发或小规模。
- gunicorn:进程管理器,用
-k uvicorn.workers.UvicornWorker跑 ASGI 应用。 - worker 数公式:
2 × CPU 核数 + 1(CPU 密集可调小,IO 密集可调大)。 - 异步模型下 worker 主要承担进程隔离,单 worker 内靠协程并发。
最小可运行示例:
# 开发
uvicorn main:app --reload --port 8000
# 生产
gunicorn main:app \
-k uvicorn.workers.UvicornWorker \
--workers 4 \
--bind 0.0.0.0:8000 \
--timeout 120
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| gunicorn 跑 ASGI 没并发 | 用了默认 sync worker | -k uvicorn.workers.UvicornWorker |
| 内存爆掉 | worker 太多 | 按 2×CPU+1 调 |
面试考法:常问「uvicorn 与 gunicorn 的区别」。答「uvicorn 是 ASGI 服务器;gunicorn 是进程管理器,用 UvicornWorker 跑 ASGI」。
5.6 Docker 多阶段构建
为什么需要它:Python 镜像要装编译依赖(gcc、python-dev),运行时不需要,镜像体积会膨胀。多阶段构建把构建依赖与运行时分离。
核心机制:
- 第一阶段:构建依赖,编译 wheel。
- 第二阶段:只装运行时依赖,拷贝构建产物。
- 基础镜像选
python:3.11-slim,不含编译工具。 - 模型文件大,不要每次构建都拷贝;用 volume 或单独 layer。
最小可运行示例:
# 构建阶段
FROM python:3.11-slim AS builder
WORKDIR /app
RUN pip install uv
COPY pyproject.toml uv.lock ./
RUN uv sync --no-dev
# 运行阶段
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8000
CMD ["gunicorn", "main:app", "-k", "uvicorn.workers.UvicornWorker", "--workers", "4"]
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
容器启动报 libgomp.so.1 缺失 |
运行镜像缺系统库 | 装对应系统包或选含依赖的基础镜像 |
| 镜像体积大 | 编译依赖没清理 | 多阶段构建,只拷运行时 |
面试考法:常问「Docker 多阶段构建解决什么」。答「构建依赖与运行时依赖分离,镜像瘦身,减少攻击面」。
5.7 Nginx 反代与健康检查、滚动发布
为什么需要它:服务上线前要有健康检查(负载均衡探活)、滚动发布(不停机更新)、回滚演练。
核心机制:
- 健康检查:
/health端点,返回 200 表示存活;负载均衡定期探测。 - Nginx 反代:转发请求,配
proxy_read_timeout(流式响应要调大)。 - 滚动发布:新版本逐步替换旧版本,失败自动回滚。
- 配置与密钥:用环境变量注入,不硬编码进代码。
最小可运行示例:
# FastAPI 健康检查
@app.get("/health")
async def health():
return {"status": "ok"}
location /api/ {
proxy_pass http://127.0.0.1:8000/;
proxy_read_timeout 300s; # 流式响应要调大
proxy_set_header Host $host;
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 流式响应 504 | Nginx 默认超时 60s | 调大 proxy_read_timeout |
| 密钥进代码 | 没走环境变量 | 用 os.getenv,不提交 .env |
面试考法:常问「滚动发布怎么做」。答「新版本逐步替换,健康检查失败自动回滚;流量阶梯切换」。
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 模型加载放启动事件 | 把模型加载移到 lifespan | 首字延迟明显下降 | 1.5 小时 |
| 流式响应 | 用 StreamingResponse 逐段返回 | 客户端逐段收到 | 1.5 小时 |
| 健康检查 | 写 /health 端点 |
返回 200 | 0.5 小时 |
| Docker 构建 | 写多阶段 Dockerfile | 镜像体积可控 | 2 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 加超时与降级 | 给模型调用加超时与兜底 | 上游慢时不 500 | 1.5 小时 |
| 修 Nginx 缓冲 | 给流式响应加 X-Accel-Buffering: no |
客户端逐段收到 | 1 小时 |
| 配 worker | 按公式配 gunicorn worker | 压测下稳定 | 1 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| AI 服务化落地 | 封装模型接口,含流式、超时、降级、健康检查 | 部署文档完整 | 6 小时 |
| 压测与部署记录 | 压测记录 QPS/P99,附部署文档 | 指标完整 | 3 小时 |
| 回滚演练 | 完成一次滚动发布与回滚 | 回滚成功 | 2 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
| 首字延迟几秒 | 每次请求加载模型 | 看模型加载位置 | 移到 lifespan |
| 流式响应一次性返回 | Nginx 或框架缓冲 | 看 Nginx 配置 | 加 X-Accel-Buffering: no |
容器报 libgomp.so.1 |
运行镜像缺系统库 | 看启动日志 | 装系统依赖 |
| 上游慢导致自己排队 | 没配超时 | 看 httpx 配置 | 设 timeout |
| gunicorn 跑 ASGI 没并发 | 默认 sync worker | 看启动命令 | -k UvicornWorker |
| 流式响应 504 | Nginx 默认超时 | 看 Nginx 错误日志 | 调大 proxy_read_timeout |
| 密钥进代码 | 没走环境变量 | 看代码配置 | 用 os.getenv |
八、出口条件
全部勾选后再进入 08.9 阶段 8:进阶方向(可选)。
- [ ] 能把模型加载放在应用启动时,请求只做推理
- [ ] 能实现流式响应,首字延迟可测量
- [ ] 能配置请求超时、限流与降级
- [ ] 能说清 uvicorn 与 gunicorn 的角色,配置 worker 数
- [ ] 能写 Docker 多阶段构建,镜像体积可控
- [ ] 能配健康检查,完成一次滚动发布与回滚演练
- [ ] 配置中不出现硬编码密钥
自测题(先自己想,再看要点):
- 模型加载为什么放应用启动事件?
- 要点:每次请求加载会导致首字延迟不可接受;启动时加载一次常驻内存。
- 流式响应怎么不被缓冲?
- 要点:
StreamingResponse逐段 yield,Nginx 配X-Accel-Buffering: no。
- 要点:
- uvicorn 与 gunicorn 的区别?
- 要点:uvicorn 是 ASGI 服务器;gunicorn 是进程管理器,用 UvicornWorker。
- Docker 多阶段构建解决什么?
- 要点:构建依赖与运行时依赖分离,镜像瘦身。
- 健康检查端点有什么要求?
- 要点:返回 200 表示存活;不依赖外部慢服务,快速返回。
- 流式响应为什么 Nginx 会 504?
- 要点:默认
proxy_read_timeout60s;要调大。
- 要点:默认
- 密钥为什么不能硬编码进代码?
- 要点:代码进 Git 会泄露;用环境变量注入,不提交
.env。
- 要点:代码进 Git 会泄露;用环境变量注入,不提交