罗罗编程学习记录
本页内容 展开查看

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 多阶段构建,镜像体积可控
  • [ ] 能配健康检查,完成一次滚动发布与回滚演练
  • [ ] 配置中不出现硬编码密钥

自测题(先自己想,再看要点):

  1. 模型加载为什么放应用启动事件?
    • 要点:每次请求加载会导致首字延迟不可接受;启动时加载一次常驻内存。
  2. 流式响应怎么不被缓冲?
    • 要点:StreamingResponse 逐段 yield,Nginx 配 X-Accel-Buffering: no。
  3. uvicorn 与 gunicorn 的区别?
    • 要点:uvicorn 是 ASGI 服务器;gunicorn 是进程管理器,用 UvicornWorker。
  4. Docker 多阶段构建解决什么?
    • 要点:构建依赖与运行时依赖分离,镜像瘦身。
  5. 健康检查端点有什么要求?
    • 要点:返回 200 表示存活;不依赖外部慢服务,快速返回。
  6. 流式响应为什么 Nginx 会 504?
    • 要点:默认 proxy_read_timeout 60s;要调大。
  7. 密钥为什么不能硬编码进代码?
    • 要点:代码进 Git 会泄露;用环境变量注入,不提交 .env。