中小团队模型部署选型实践：FastAPI+Gunicorn+Docker 本文基于 FastAPI、Gunicorn 和

前言

在算法迭代的日常工作中，算法工程师几乎都会遇到一个核心困境 ——Notebook 里验证通过的模型，想快速变成能稳定调用的在线服务，往往要踩不少坑。从本地实验到生产部署的过程中，常见问题包括环境依赖冲突、并发能力不足、服务稳定性差以及迭代效率低等 —— 这些障碍不仅拖慢算法落地节奏，更会让业务侧对算法服务的可靠性产生疑虑。

为解决这一痛点，本文将聚焦算法模型的生产级部署落地，基于 FastAPI、Gunicorn 和 Docker 三大工具链，结合自托管 GitLab Runner 构建自动化 CI/CD 流程，实现从模型权重到可调用服务的端到端交付。该方案轻量且适应中小团队快速迭代的需求，可适用于线性模型、CNN、Transformer 等各类算法模型。

第一章部署痛点与目标

Notebook 的价值在于快速验证模型思路，而生产级部署需满足稳定、可靠、可调用、易迭代四大诉求。核心差距在于实验环境与部署环境脱节，具体体现在四个关键环节：

环境一致性痛点
算法工程师本地环境（Python 3.9 + CUDA 11.8 + PyTorch 2.0）与部署环境（Python 3.10 + CUDA 12.2）存在差异，常导致 “本地跑通、线上报错”。尤其是 CUDA 与 GPU 驱动不兼容，会引发推理失败，排查周期长。
并发与可靠性不足
Notebook 单进程运行，每秒仅能处理 1-2 个请求，无法支撑 10-50 QPS 的业务峰值。进程崩溃后无自动恢复机制，一旦推理超时或异常，服务会中断，影响业务正常运行。
可观测性缺失
部署后缺乏结构化日志、关键指标监控（推理延迟、GPU 使用率）和健康检查机制。出现响应延迟飙升或请求错误时，无法快速定位根因，排查效率低，MTTR（平均故障恢复时间）常超过 30 分钟。
迭代效率低
模型更新需手动停止服务、替换权重、重启，整个过程耗时 5-10 分钟且存在中断风险。缺乏版本管理，回滚和灰度发布操作复杂。

本次部署目标

构建最小可生产化模型部署体系，指标如下：

FastAPI 定义接口契约，支持批量请求，确保与业务侧契约一致；
Gunicorn+UvicornWorker 支持多进程并发与异常自动重启，支撑 10-50 QPS 峰值；
Docker+NVIDIA Runtime 封装环境，实现一次构建，多节点一致运行；
GitLab Runner 自动化 CI/CD，实现零停机模型迭代；
配套结构化日志、健康检查和基础监控，MTTR 缩短至 5 分钟以内。

第二章部署整体架构：职责明确的工具链组合

2.1 部署体系链路图

plaintext

Notebook → 代码工程化 → API封装 → 容器化 → 应用服务器 → 容器编排 → CI/CD → 监控
业务侧 → FastAPI服务 → 推理引擎 → JSON响应

2.2 核心组件部署职责划分

组件层级	部署核心职责	技术选型	选型理由（贴合中小团队需求）	部署价值
API 接入层	定义部署接口契约、输入参数校验、请求分发、异常处理	FastAPI	1. 自动生成 Swagger API 文档（业务侧可直接在线调试）；2. 支持 Pydantic 输入校验（提前拦截非法数据）；3. 原生支持异步（提升并发能力）；4. 轻量易上手，学习成本低	降低业务侧调用成本，避免因输入格式错误导致部署故障；接口文档自动化，减少对接文档编写工作量
进程管理层	部署后多进程调度、Worker 崩溃自动恢复、请求分发、优雅退出	Gunicorn + UvicornWorker	1. Gunicorn 是成熟的生产级进程管理器，支持 Worker 异常重启；2. UvicornWorker 基于 uvloop 实现异步 IO，相比 Gunicorn 默认的同步 Worker（如 sync Worker），并发能力能提升 3-5 倍；3. 配置简单，无需编写复杂调度逻辑	保障服务高可用（崩溃自动恢复），支撑业务 10-50 QPS 并发请求；避免单进程瓶颈
环境封装层	打包部署依赖（Python/CUDA/PyTorch/ 代码）、GPU 资源映射、环境隔离	Docker + NVIDIA Container Toolkit	1. Docker 容器化能实现 “一次构建，多环境一致”—— 不管是本地测试、开发联调还是生产部署，跑的环境完全一样；2. NVIDIA Runtime 支持容器内调用 GPU；3. 镜像体积可控（用 CUDA Runtime 镜像比 Devel 镜像小 50%）；4. 运维成本低，仅需基础 Docker 命令	解决环境一致性问题，杜绝 “本地能跑线上不行”；隔离不同服务的依赖，避免冲突
自动化部署层	代码提交触发构建、镜像推送、远程部署、版本管理	自托管 GitLab Runner + GitLab CI/CD	1. 自托管 Runner 可部署在私有网络，安全可控；2. GitLab CI/CD 通过配置文件定义流程，无需编写复杂脚本；3. 支持与 Git 版本控制联动，每个 commit 对应一个部署版本	缩短模型上线周期（从小时级降至分钟级）；实现无感知更新，避免业务中断；版本可追溯，回滚方便
可观测层	部署后日志采集、健康检查、基础指标监控	Python Logging + 原生工具（docker logs/nvidia-smi）	1. Python Logging 可配置结构化输出（JSON 格式，便于解析）；2. docker logs 直接查看容器日志，无需额外部署日志系统；3. nvidia-smi 原生支持 GPU 监控，零成本	降低部署后运维成本，快速定位问题（如通过请求 ID 查完整日志）；实时掌握服务状态与 GPU 资源使用情况

2.3 部署设计原则

轻量化优先：不依赖 Kubernetes、Istio 等复杂编排工具，用 Docker+Docker Compose 即可完成部署，运维成本低（1 名算法工程师可兼顾部署运维）；
解耦设计：API 逻辑与推理逻辑严格分离（FastAPI 负责接口，inference.py 负责模型计算），部署时模型替换不影响接口契约，支持独立迭代（如 API 改参数无需改模型代码）；
生产级可靠性：Gunicorn 主进程实时监控 Worker 状态，当 Worker 因显存溢出、超时等原因退出时，自动重启新 Worker；Uvicorn 基于 uvloop 实现异步 IO，在 IO 密集型场景（如多请求等待 GPU 推理）下性能优势明显；
可复现性：Docker 镜像封装所有部署依赖（含 Python 版本、PyTorch 版本、CUDA 版本），CI/CD 流程确保每次构建的镜像一致，杜绝 “Works on my machine” 问题；
成本可控：不追求 “大而全”，仅保留部署核心功能（如日志用原生工具，监控用基础指标），避免引入过多工具导致运维负担增加。

第三章部署前置准备：生成可迁移的模型权重

部署的前提是 “模型产物可迁移”—— 需严格区分 “训练代码” 与 “部署推理代码”，避免将训练依赖（如数据预处理、优化器、数据集加载）引入部署环境（部署环境仅需模型结构与权重），降低部署复杂度与镜像体积。

3.1 训练脚本设计（聚焦 “输出可部署权重”）

训练脚本的核心目标是 “生成可用于部署的权重文件”，而非 “实现复杂训练逻辑”。关键是通过state_dict格式保存模型参数（而非完整模型对象），确保部署时只需对齐模型结构即可加载，不受训练侧代码路径、类名变更影响。

# train.py（训练脚本，仅用于生成部署用权重）
import torch
import torch.nn as nn
import torch.optim as optim

# 1. 固定随机种子，确保训练结果可复现（部署前验证权重一致性）
torch.manual_seed(42)
torch.cuda.manual_seed(42)

# 2. 定义模型结构（必须与部署侧推理代码完全一致，包括层名、输入输出维度）
# 示例：线性回归模型（拟合y=2x+1），实际可替换为CNN/Transformer等复杂模型
class SimpleLinearModel(nn.Module):
    def __init__(self, in_features: int = 1, out_features: int = 1):
        super().__init__()
        self.linear = nn.Linear(in_features=in_features, out_features=out_features)  # 核心层
        
    def forward(self, x: torch.Tensor) -> torch.Tensor:
        # 前向传播逻辑（部署侧推理时会复用此逻辑，需确保无训练特有代码）
        return self.linear(x)

# 3. 设备适配（兼容本地CPU训练与服务器GPU训练，不影响后续部署）
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(f"Training device: {device}")

# 4. 准备训练数据（仅用于训练，部署时无需此部分）
X = torch.tensor([[1.0], [2.0], [3.0], [4.0], [5.0]], dtype=torch.float32, device=device)  # 输入特征
y = torch.tensor([[3.0], [5.0], [7.0], [9.0], [11.0]], dtype=torch.float32, device=device)  # 标签（y=2x+1）

# 5. 初始化训练组件（训练特有，部署时无需）
model = SimpleLinearModel().to(device)
criterion = nn.MSELoss()  # 损失函数
optimizer = optim.SGD(model.parameters(), lr=0.05)  # 优化器

# 6. 训练循环（简化版，核心是更新模型参数）
num_epochs = 500
for epoch in range(num_epochs):
    # 训练模式（部署时会切换为eval模式，此处仅训练用）
    model.train()
    # 梯度清零
    optimizer.zero_grad()
    # 前向传播
    outputs = model(X)
    # 计算损失
    loss = criterion(outputs, y)
    # 反向传播与参数更新
    loss.backward()
    optimizer.step()
    
    # 每100轮打印训练进度（可选，用于观察训练是否收敛）
    if (epoch + 1) % 100 == 0:
        print(f"Epoch [{epoch+1}/{num_epochs}], Loss: {loss.item():.4f}")

# 7. 保存部署用权重（核心步骤：仅保存state_dict，不保存完整模型）
# state_dict只保存模型的核心参数（比如权重、偏置），不仅体积更小，兼容性也更强——哪怕训练和部署的代码路径不一样，只要模型结构对齐就能加载
torch.save(model.state_dict(), "model.pth")
print(f"Deployable model weights saved to ./model.pth")

# 8. 验证权重有效性（部署前预检查，避免生成无效权重）
model.eval()  # 切换为评估模式（关闭训练特有层）
with torch.no_grad():  # 禁用梯度计算，节省资源
    test_x = torch.tensor([[6.0]], dtype=torch.float32, device=device)  # 测试输入
    test_y = model(test_x)  # 测试推理
    print(f"Weight validation: x=6 → y={test_y.item():.2f} (expected 13.0)")  # 符合预期则可用于部署

3.2 为什么选择 state_dict 而非 save 保存完整模型？

体积优势：state_dict只保存模型的核心参数（比如权重、偏置），相比torch.save(model)（保存完整模型对象）体积减少 50% 以上。例如：本文线性模型的state_dict仅几 KB，而完整模型保存后约 10KB；复杂模型（如 ResNet50）的state_dict约 100MB，完整模型则需额外保存代码结构，体积更大。
兼容性强：部署时只要模型结构（如SimpleLinearModel的层定义、输入输出维度）与训练侧一致，即可跨设备、跨代码路径加载。例如：CPU 训练的权重可在 GPU 部署（通过map_location指定设备）；训练侧代码路径是train.models，部署侧是app.models，只要类名和层结构一致，仍可正常加载。
解耦代码：state_dict不依赖训练侧的代码结构（如训练脚本中的优化器、损失函数），部署侧只需维护推理相关代码（模型结构、推理逻辑），避免因训练代码变更（如修改优化器）导致部署失败。

3.3 权重生成步骤

# 步骤1：安装训练依赖（务必与后续部署环境的版本兼容，否则可能出现“权重能训练但部署加载失败”的问题）
# 若本地有GPU（CUDA 12.2），安装GPU版本（与后续Docker基础镜像的CUDA版本一致）
pip install torch==2.3.1 torchvision==0.18.1 torchaudio==2.3.1 --index-url https://download.pytorch.org/whl/cu121
# 若本地无GPU，安装CPU版本（仅用于生成权重，不影响后续GPU部署）
pip install torch==2.3.1 torchvision==0.18.1 torchaudio==2.3.1 --index-url https://download.pytorch.org/whl/cpu

# 步骤2：执行训练脚本，生成部署权重
python train.py

# 步骤3：验证权重有效性（部署前必做！避免无效权重流到生产）
# 1. 确认当前目录下生成model.pth文件；
# 2. 查看训练脚本输出的验证结果，确保test_y接近13.0（如12.98~13.02），说明权重正确。
# 若验证结果偏差大（如y=10.0），需检查训练循环（如学习率、迭代次数），重新生成权重。

第四章 API 服务化部署：FastAPI 构建调用入口

API 层是算法服务与业务侧的 “桥梁”，部署时需确保接口契约清晰、输入校验严格、支持批量请求，同时暴露健康检查接口供运维监控。FastAPI 凭借 “自动化 API 文档、强类型输入校验、异步支持” 三大特性，成为部署 API 层的首选工具，能显著降低业务对接与运维成本。

4.1 部署项目结构

采用 “功能模块化” 设计，将 API、推理、配置、日志等拆分为独立文件，避免所有代码堆在一个脚本中（后期维护困难）。结构如下：

model-deployment/  # 项目根目录
├── app/                  # 部署核心代码（API+推理+配置+日志）
│   ├── __init__.py       # 空文件，标识为Python模块
│   ├── app.py            # FastAPI入口（部署接口定义：健康检查、推理接口）
│   ├── inference.py      # 推理引擎（部署时模型加载、推理计算逻辑）
│   ├── models.py         # 模型结构定义（与训练侧一致，部署加载权重用）
│   ├── config.py         # 部署配置管理（端口、Worker数、模型路径等，支持环境变量注入）
│   ├── logging.json      # 结构化日志配置（定义日志格式、输出方式，部署后便于解析）
│   └── requirements.txt  # 部署依赖清单（固定版本，避免依赖自动升级导致冲突）
├── model.pth             # 部署用权重文件（训练脚本生成，需放在根目录）
└── .gitlab-ci.yml        # 自动化部署配置文件（GitLab CI/CD流程定义）

4.2 核心模块部署实现

4.2.1 部署配置管理（config.py：统一配置入口，避免硬编码）

通过环境变量注入配置，支持部署时灵活调整参数（如开发环境用端口 9999，生产环境用 8080；不同服务器根据 GPU 显存调整 Worker 数），无需修改代码。

# app/config.py（部署配置统一入口）
import os
from dotenv import load_dotenv

# 加载.env文件（本地开发用，生产部署时通过Docker环境变量覆盖）
# 好处：本地调试时无需手动设置环境变量，生产部署时可灵活修改
load_dotenv()

# -------------------------- 模型部署相关配置 --------------------------
# 部署时模型权重路径（默认在项目根目录，可通过环境变量修改）
MODEL_PATH = os.getenv("MODEL_PATH", "./model.pth")
# 是否启用混合精度推理（GPU场景下启用，提升推理速度、降低显存占用）
# 1=启用，0=禁用，通过环境变量控制（如小模型可禁用，大模型建议启用）
USE_AMP = os.getenv("USE_AMP", "1") == "1"
# 部署时最大批量大小（防止超大批量请求导致GPU显存溢出）
# 可根据模型大小调整（如线性模型设32，Transformer大模型设8）
MAX_BATCH_SIZE = int(os.getenv("MAX_BATCH_SIZE", 32))

# -------------------------- 服务部署相关配置 --------------------------
# 部署时服务端口（默认9999，生产环境可改为80/8080）
PORT = int(os.getenv("PORT", 9999))
# 部署时Gunicorn Worker数量（核心参数，需根据GPU显存调整）
# 每个Worker加载1份模型，避免显存溢出（如1GB模型设2，5GB模型设1）
WORKER_NUM = int(os.getenv("WORKER_NUM", 1))
# 推理超时时间（秒，防止单个请求阻塞Worker太久）
INFERENCE_TIMEOUT = int(os.getenv("INFERENCE_TIMEOUT", 10))

4.2.2 模型结构定义（models.py：部署加载权重的基础，必须与训练侧一致）

部署侧需复用训练侧的模型结构（类名、层定义、输入输出维度），否则权重无法正常加载（会报 “key mismatch” 错误）。此处直接复用训练侧的SimpleLinearModel，确保一致性。

# app/models.py（部署侧模型结构，必须与训练侧train.py完全对齐）
import torch
import torch.nn as nn

class SimpleLinearModel(nn.Module):
    def __init__(self, in_features: int = 1, out_features: int = 1):
        super().__init__()
        # 层定义必须与训练侧一致（包括层名、输入输出维度）
        self.linear = nn.Linear(in_features=in_features, out_features=out_features)
    
    def forward(self, x: torch.Tensor) -> torch.Tensor:
        # 前向传播逻辑必须与训练侧一致（无训练特有代码，如Dropout已在eval模式下关闭）
        return self.linear(x)

# （可选）部署时模型工厂函数（便于后续扩展多模型）
def create_model(model_name: str = "linear", **kwargs) -> nn.Module:
    if model_name == "linear":
        return SimpleLinearModel(** kwargs)
    else:
        raise ValueError(f"Unsupported model name: {model_name}")

4.2.3 推理引擎封装（inference.py：部署核心逻辑，解决模型加载与推理优化）

推理引擎是部署的 “核心大脑”，负责：部署时加载模型（仅加载一次，避免重复占用显存）、处理推理请求（数据格式转换、GPU 计算）、优化推理性能（混合精度、模型预热）。需重点解决 “GPU 冷启动”“显存溢出”“跨设备兼容” 三大问题。

# app/inference.py（部署时推理逻辑封装，与API层解耦）
import torch
from torch.cuda.amp import autocast  # 混合精度推理
from typing import Optional
from .models import create_model
from .config import MODEL_PATH, USE_AMP, MAX_BATCH_SIZE

class InferenceEngine:
    """推理引擎类：部署时单进程单例，仅加载一次模型，避免显存泄漏与重复加载"""
    _instance: Optional["InferenceEngine"] = None  # 单例实例（确保全局仅一个引擎）
    
    def __new__(cls, *args, **kwargs):
        # 单例模式：确保每个部署进程仅初始化一次引擎（避免多Worker重复加载模型）
        if cls._instance is None:
            cls._instance = super().__new__(cls, *args, **kwargs)
        return cls._instance
    
    def __init__(self):
        """初始化：部署时进程启动后执行一次，加载模型并预热"""
        # 1. 设备适配（部署时自动识别GPU/CPU，无需手动指定）
        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
        print(f"Deploy inference device: {self.device}")
        
        # 2. 模型初始化与权重加载（部署核心步骤）
        # 调用模型工厂函数创建模型（便于后续扩展多模型）
        self.model = create_model(model_name="linear", in_features=1, out_features=1)
        # 加载权重：map_location确保跨设备兼容（如CPU部署加载GPU训练的权重）
        try:
            self.model.load_state_dict(torch.load(MODEL_PATH, map_location=self.device))
        except Exception as e:
            # 权重加载失败是部署致命错误，需终止进程并提示
            raise RuntimeError(f"Failed to load model weights from {MODEL_PATH}: {str(e)}") from e
        
        # 3. 切换评估模式（部署时必须执行，关闭训练特有层）
        # 如Dropout层会禁用，BatchNorm层会使用训练时的移动均值/方差
        self.model.eval()
        self.model.to(self.device)  # 将模型移动到目标设备（GPU/CPU）
        print(f"Deploy: Model loaded from {MODEL_PATH}, status: eval, device: {self.device}")
        
        # 4. 模型预热（解决GPU部署后首请求延迟问题）
        # GPU首次执行推理时，需初始化CUDA Context、编译内核，耗时100-500ms（冷启动）
        # 预热通过dummy输入触发初始化，确保首条业务请求延迟正常（与后续请求一致）
        if self.device.type == "cuda":
            with torch.no_grad():
                # 生成与实际请求格式一致的dummy输入（批量大小1，特征数1）
                dummy_input = torch.ones((1, 1), dtype=torch.float32, device=self.device)
                _ = self.model(dummy_input)  # 执行一次推理，触发预热
            print("Deploy: Model warmed up (GPU cold start solved)")
        else:
            print("Deploy: CPU mode, no need to warm up")
    
    @torch.inference_mode()  # 部署优化：完全禁用autograd，降低显存占用（比torch.no_grad()更彻底）
    def predict(self, input_data: list[list[float]]) -> list[list[float]]:
        """
        推理核心方法：接收业务侧输入（Python列表），返回推理结果（Python列表）
        Args:
            input_data: 批量输入数据，格式为[[x1], [x2], ..., [xn]]（n为批量大小，每个样本1个特征）
        Returns:
            推理结果，格式为[[y1], [y2], ..., [yn]]（与输入批量大小一致）
        """
        # 1. 输入批量大小校验（部署防过载：避免超大批量导致显存溢出）
        batch_size = len(input_data)
        if batch_size == 0:
            raise ValueError("Input batch size cannot be 0 (no data provided)")
        if batch_size > MAX_BATCH_SIZE:
            raise ValueError(f"Batch size exceeds maximum limit {MAX_BATCH_SIZE}, current: {batch_size}")
        
        # 2. 数据格式转换（业务侧输入→模型输入：Python列表→PyTorch张量）
        try:
            input_tensor = torch.tensor(input_data, dtype=torch.float32)
        except Exception as e:
            raise ValueError(f"Invalid input data format: {str(e)} (expected list of lists of floats)") from e
        
        # 3. 数据设备迁移（CPU→GPU，非阻塞模式提升并发效率）
        # non_blocking=True：数据迁移与后续计算并行（仅GPU支持），减少等待时间
        input_tensor = input_tensor.to(self.device, non_blocking=(self.device.type == "cuda"))
        
        # 4. 执行推理（根据设备与配置选择是否启用混合精度）
        # 混合精度推理：GPU场景下用FP16计算，提升速度（约2倍）、降低显存（约30%），不影响精度
        if self.device.type == "cuda" and USE_AMP:
            with autocast():
                output_tensor = self.model(input_tensor)
        else:
            output_tensor = self.model(input_tensor)
        
        # 5. 结果处理（模型输出→业务侧输出：PyTorch张量→Python列表）
        # detach()：脱离计算图（避免显存泄漏）；cpu()：迁移到CPU（业务侧通常处理CPU数据）；tolist()：转换为列表
        output_data = output_tensor.detach().cpu().tolist()
        
        # 6. 结果格式校验（确保输出与输入批量大小一致，避免业务侧解析错误）
        if len(output_data) != batch_size:
            raise RuntimeError(f"Output batch size mismatch: expected {batch_size}, got {len(output_data)}")
        
        return output_data

4.2.4 FastAPI 部署入口（app.py：定义接口，对接业务与推理引擎）

FastAPI 入口文件需完成三件事：1. 初始化 FastAPI 应用与推理引擎；2. 定义健康检查接口（运维监控用）；3. 定义推理接口（业务调用用），并做好输入校验与异常处理。

# app/app.py（FastAPI部署入口，定义接口契约）
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
from pydantic import BaseModel, conlist, Field
import time
import logging
from typing import List
from .inference import InferenceEngine
from .config import PORT

# -------------------------- 初始化配置 --------------------------
# 1. 初始化FastAPI应用（配置API文档，降低业务对接成本）
app = FastAPI(
    title="Simple Linear Model Inference Service",
    description="Deployed with FastAPI + Gunicorn + Docker (GPU Supported)",
    version="1.0.0",
    # 自动生成API文档的路径（业务侧可访问/swagger-ui查看并调试）
    docs_url="/swagger-ui",
    openapi_url="/openapi.json"
)

# 2. 初始化日志（结构化输出，部署后便于排查问题）
logging.config.fileConfig("app/logging.json")
logger = logging.getLogger("inference_service")

# 3. 初始化推理引擎（部署时进程启动后执行一次，单例模式确保仅加载一次模型）
# 注意：需在FastAPI初始化后、接口定义前执行，避免接口调用时未加载模型
try:
    engine = InferenceEngine()
except RuntimeError as e:
    # 推理引擎初始化失败（如权重加载失败），服务无法启动，直接终止
    logger.critical(f"Failed to initialize inference engine: {str(e)}")
    raise SystemExit(1) from e

# -------------------------- 接口数据模型（Pydantic输入校验） --------------------------
# 定义推理接口输入模型（Pydantic）：强制校验输入格式，提前拦截非法数据
# 业务侧调用时必须按此格式传参，否则直接返回400错误（无需进入推理逻辑）
class PredictRequest(BaseModel):
    # 输入特征：批量列表，每个样本至少1个特征（min_items=1），特征值为float
    features: List[conlist(float, min_items=1, max_items=1)] = Field(
        ...,  # 必须传该字段
        example=[[6.0], [7.0], [8.0]],  # 示例值（API文档中显示，便于业务侧参考）
        description="Batch of input features, each sample has 1 feature (for linear model)"
    )

# 定义推理接口输出模型（Pydantic）：规范输出格式，降低业务侧解析成本
class PredictResponse(BaseModel):
    # 推理结果：与输入批量大小一致的列表
    prediction: List[List[float]] = Field(
        ...,
        example=[[13.0], [15.0], [17.0]],
        description="Batch of predictions, one per input sample"
    )
    # 请求ID：用于日志追踪（业务侧可根据该ID查询完整日志）
    request_id: str = Field(..., description="Unique request ID for logging and tracing")
    # 推理耗时：单位毫秒（便于业务侧了解性能，优化调用频率）
    inference_time_ms: float = Field(..., description="Inference time in milliseconds")

# -------------------------- 中间件（请求日志与异常捕获） --------------------------
# 1. 请求日志中间件：记录每个请求的基本信息（方法、路径、耗时、状态码）
@app.middleware("http")
async def log_request(request: Request, call_next):
    # 生成唯一请求ID（用于追踪单次请求的完整链路）
    request_id = f"req-{int(time.time() * 1000)}-{hash(request.client)}"
    # 记录请求开始时间（计算耗时）
    start_time = time.time()
    
    # 将请求ID存入请求状态，便于接口中获取
    request.state.request_id = request_id
    
    # 执行请求处理（调用后续接口函数）
    response = await call_next(request)
    
    # 计算请求耗时（毫秒）
    process_time = (time.time() - start_time) * 1000
    
    # 记录结构化日志（包含请求ID，便于排查时关联）
    logger.info(
        "Request processed",
        extra={
            "request_id": request_id,
            "method": request.method,
            "path": request.url.path,
            "client_ip": request.client.host,
            "status_code": response.status_code,
            "process_time_ms": round(process_time, 2)
        }
    )
    
    return response

# 2. 全局异常处理：统一异常返回格式，避免业务侧接收Python堆栈信息
@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    # 获取请求ID（若未生成则用默认值）
    request_id = getattr(request.state, "request_id", "unknown-request-id")
    
    # 判断异常类型，返回对应HTTP状态码
    if isinstance(exc, HTTPException):
        # 已知异常（如输入校验失败、批量大小超限）
        status_code = exc.status_code
        detail = exc.detail
        logger.error(
            "Known exception occurred",
            extra={"request_id": request_id, "detail": detail, "status_code": status_code}
        )
    else:
        # 未知异常（如推理逻辑错误），返回500（服务内部错误）
        status_code = 500
        detail = "Internal server error (please contact administrator with request ID)"
        logger.error(
            "Unknown exception occurred",
            extra={"request_id": request_id, "error": str(exc)},
            exc_info=True  # 记录完整堆栈信息，便于排查
        )
    
    # 统一返回JSON格式异常
    return JSONResponse(
        status_code=status_code,
        content={
            "error": detail,
            "request_id": request_id,
            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S")
        }
    )

# -------------------------- 接口定义 --------------------------
# 1. 健康检查接口（GET /healthz）：运维监控用，判断服务是否存活
# 监控工具（如Prometheus、Zabbix）可定期调用该接口，返回200表示服务正常
@app.get(
    "/healthz",
    summary="Health Check",
    description="Check if the inference service is alive (for monitoring)",
    tags=["Monitoring"]  # 归类到Monitoring标签（API文档中分组显示）
)
async def health_check(request: Request):
    return {
        "status": "healthy",
        "service": "fastapi-gpu-inference",
        "model_loaded": True,  # 标识模型已加载（便于监控模型状态）
        "request_id": request.state.request_id,
        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S")
    }

# 2. 推理接口（POST /predict）：业务核心调用接口
@app.post(
    "/predict",
    response_model=PredictResponse,  # 强制按PredictResponse格式返回
    summary="Model Inference",
    description="Submit batch features to get predictions (supports up to {MAX_BATCH_SIZE} samples per request)".format(
        MAX_BATCH_SIZE=engine.MAX_BATCH_SIZE  # 动态显示最大批量大小
    ),
    tags=["Inference"]  # 归类到Inference标签
)
async def predict(request: Request, req_data: PredictRequest):
    # 记录推理开始时间（计算推理耗时）
    inference_start = time.time()
    
    try:
        # 调用推理引擎执行推理（核心步骤）
        prediction = engine.predict(input_data=req_data.features)
        
        # 计算推理耗时（毫秒）
        inference_time_ms = (time.time() - inference_start) * 1000
        
        # 记录推理成功日志（包含批量大小、耗时）
        logger.info(
            "Inference completed successfully",
            extra={
                "request_id": request.state.request_id,
                "batch_size": len(req_data.features),
                "inference_time_ms": round(inference_time_ms, 2)
            }
        )
        
        # 返回规范的推理结果
        return PredictResponse(
            prediction=prediction,
            request_id=request.state.request_id,
            inference_time_ms=round(inference_time_ms, 2)
        )
    
    except ValueError as e:
        # 输入数据错误（如批量大小超限、格式错误），返回400
        raise HTTPException(status_code=400, detail=str(e)) from e
    except Exception as e:
        # 推理过程中未知错误（如GPU显存溢出），返回500
        raise HTTPException(status_code=500, detail="Inference failed") from e

# -------------------------- 服务启动入口（本地开发用） --------------------------
if __name__ == "__main__":
    # 本地开发时用uvicorn启动（支持热重载），生产部署用Gunicorn
    import uvicorn
    uvicorn.run(
        "app.app:app",
        host="0.0.0.0",
        port=PORT,
        reload=True,  # 热重载：代码修改后自动重启服务（仅本地开发用）
        workers=1     # 本地开发用1个Worker即可
    )

4.2.5 结构化日志配置（logging.json：部署后日志可解析）

日志是部署后排查问题的关键，需配置为 JSON 格式（结构化），便于后续用工具（如 grep、jq）解析。配置文件如下：

{
    "version": 1,
    "disable_existing_loggers": false,
    "formatters": {
        "json": {
            "class": "pythonjsonlogger.jsonlogger.JsonFormatter",
            "format": "%(asctime)s %(name)s %(levelname)s %(message)s %(request_id)s %(batch_size)s %(inference_time_ms)s",
            "datefmt": "%Y-%m-%d %H:%M:%S"
        }
    },
    "handlers": {
        "stdout": {
            "class": "logging.StreamHandler",
            "formatter": "json",
            "stream": "ext://sys.stdout"
        }
    },
    "loggers": {
        "inference_service": {
            "handlers": ["stdout"],
            "level": "INFO",
            "propagate": false
        }
    },
    "root": {
        "handlers": ["stdout"],
        "level": "WARNING"
    }
}

4.2.6 部署依赖清单（requirements.txt：固定版本，避免冲突）

部署依赖需明确指定版本，避免pip install时自动升级到不兼容版本（如 FastAPI 0.100 + 与 Pydantic 1.x 不兼容）。清单如下：

# app/requirements.txt（部署依赖，固定版本）
# API框架
fastapi==0.110.3
# ASGI服务器（本地开发+Gunicorn Worker）
uvicorn[standard]==0.29.0
# 生产级进程管理器
gunicorn==21.2.0
# 数据校验（FastAPI依赖）
pydantic==2.7.1
# 环境变量加载（本地开发用）
python-dotenv==1.0.1
# 深度学习框架（匹配Docker基础镜像的CUDA版本）
torch==2.3.1+cu121
# 数值计算库（PyTorch依赖）
numpy==1.26.4
# JSON日志格式化（结构化日志）
python-json-logger==2.0.7

4.3 本地部署验证

在将代码容器化前，需先在本地验证 API 服务是否正常，避免容器化后发现问题（排查更复杂）。步骤如下：

# 步骤1：安装部署依赖（务必与后续部署环境的版本兼容，否则可能出现“依赖能本地安装但容器内报错”的问题）
pip install -r app/requirements.txt -f https://download.pytorch.org/whl/torch_stable.html

# 步骤2：启动本地开发服务（用uvicorn，支持热重载）
# 注意：本地验证时Worker数设1，避免多进程重复加载模型（显存占用过高）
python -m app.app

# 步骤3：验证健康检查接口（确保服务存活，运维监控的基础）
# 打开浏览器访问http://localhost:9999/healthz，或用curl命令
curl http://localhost:9999/healthz
# 预期返回：{"status":"healthy","service":"fastapi-gpu-inference",...}

# 步骤4：验证API文档（业务侧对接用，减少文档沟通成本）
# 打开浏览器访问http://localhost:9999/swagger-ui，可看到接口列表（/healthz、/predict）
# 点击/predict接口的"Try it out"，输入示例数据（如{"features":[[6.0],[7.0]]}），点击"Execute"
# 预期返回：{"prediction":[[13.0],[15.0]],"request_id":"...","inference_time_ms":...}

# 步骤5：验证日志输出（确保结构化日志正常，后续排查问题的关键）
# 查看终端输出的日志，应为JSON格式，包含request_id、batch_size、inference_time_ms等字段
# 示例：{"asctime":"2024-05-20 15:30:00","name":"inference_service","levelname":"INFO","message":"Inference completed successfully","request_id":"req-123456789-xxx","batch_size":2,"inference_time_ms":1.23}

# 步骤6：验证异常场景（确保输入校验生效，提前拦截非法请求）
# 用curl发送非法输入（如批量大小超过32、特征数不为1）
curl -X POST http://localhost:9999/predict \
  -H "Content-Type: application/json" \
  -d '{"features":[[6.0],[7.0],...]}'  # 此处省略31个元素，共33个样本（超过MAX_BATCH_SIZE=32）
# 预期返回400错误，且日志中记录异常信息（包含request_id，便于定位问题）

若所有验证步骤均通过，说明 API 服务代码正常，可进入下一步容器化部署。

第五章生产级部署：Gunicorn 保障服务稳定

本地开发模式的 Uvicorn 仅支持单进程，无法满足生产部署的 “高并发、高可用” 需求 —— 单进程每秒仅能处理 1-2 个请求，且崩溃后无自动恢复机制。需通过 Gunicorn 作为进程管理器，结合 UvicornWorker 实现部署后的多进程调度与故障恢复，支撑业务侧 10-50 QPS 的峰值请求。

5.1 为什么需要 Gunicorn+UvicornWorker？

Gunicorn（Master 进程） ：部署后作为主进程，负责三件核心事情：
1. 监听指定端口（如 9999），接收业务侧的 HTTP 请求；
2. 管理 Worker 进程生命周期：启动指定数量的 Worker、将请求分发给 Worker 处理、监控 Worker 状态；
3. 故障恢复：当 Worker 因异常（如显存溢出、推理超时）退出时，Master 会立即启动新的 Worker，确保服务不中断（可用性达 99.9% 以上）。
UvicornWorker（Worker 进程） ：基于 uvloop 实现异步 IO 的 Worker 进程，相比 Gunicorn 默认的同步 Worker（如 sync Worker），有两大优势：
1. 异步 IO 支持：在 IO 密集型场景（如多请求等待 GPU 推理）下，Worker 可同时处理多个请求（无需等待前一个请求完成），并发能力能提升 3-5 倍；
2. 低资源占用：uvloop 基于 libuv 实现，性能接近 Node.js，内存占用比同步 Worker 低 20%。
多进程与 GPU 显存的平衡：每个 Worker 会独立加载一份模型（因 Python 进程间内存不共享），部署时需根据 GPU 显存调整 Worker 数量 —— 若模型体积为 1GB，1 块 16GB 显存的 GPU 可设 10-12 个 Worker；若模型体积为 5GB，仅能设 2-3 个 Worker（需预留部分显存用于推理计算）。

5.2 生产部署启动命令

Gunicorn 的启动命令需根据部署场景（模型大小、GPU 显存、业务 QPS）调整参数，以下是针对 GPU 部署的优化配置：

# Gunicorn生产部署命令（建议保存为start.sh脚本，便于容器启动时调用）
gunicorn \
  -k uvicorn.workers.UvicornWorker \  # 指定Worker类型为UvicornWorker（异步）
  -w ${WORKER_NUM} \                  # Worker数量（从环境变量获取，部署时灵活调整）
  -b 0.0.0.0:${PORT} \                # 绑定地址与端口（0.0.0.0支持外部访问，避免仅localhost可访问）
  app.app:app \                       # FastAPI应用路径（模块.实例：app目录下的app.py中的app实例）
  --timeout 60 \                      # 请求超时时间（秒）：超过该时间未完成的请求，Worker会被终止并重启
                                      # 配置依据：设为平均推理耗时的3-5倍（如平均耗时2s，设10s）
  --graceful-timeout 30 \             # 优雅退出时间（秒）：收到停止信号后，Worker会等待30秒完成当前请求，再退出
                                      # 避免强制终止导致请求失败（如批量推理到一半被中断）
  --max-requests 2000 \               # 每个Worker处理的最大请求数：达到后Worker会自动重启
                                      # 配置依据：解决长期运行的内存/显存泄漏问题（如PyTorch显存碎片）
                                      # 按QPS计算：若QPS=10，2000请求对应3.3小时重启一次，平衡稳定与性能
  --max-requests-jitter 200 \         # 最大请求数的随机偏移量：避免所有Worker同时达到最大请求数并重启
                                      # 配置依据：偏移量设为max-requests的10%（2000→200），确保Worker分批重启
  --log-config app/logging.json \     # 加载结构化日志配置（确保日志格式统一，便于解析）
  --access-logfile - \                # 访问日志输出到stdout（容器日志采集的标准方式，避免写本地文件）
  --error-logfile -                   # 错误日志输出到stdout（与访问日志统一，便于查看）
  --worker-tmp-dir /dev/shm \         # Worker临时目录：设为内存文件系统（/dev/shm），提升临时文件读写速度
                                      # 优化点：避免频繁读写磁盘，尤其在推理时需生成临时文件的场景

5.3 部署参数配置依据

不同模型、不同 GPU 配置的部署参数差异较大，需根据实际场景调整，以下是实战中的配置建议：

参数	配置依据（核心影响因素）	中小团队实战建议
`-w ${WORKER_NUM}`	1. GPU 显存大小：每个 Worker 加载 1 份模型，需预留 30% 显存用于推理计算（如 16GB 显存，实际可用 11GB）； 2. 模型体积：如线性模型（100KB）可多设 Worker，Transformer 大模型（5GB）需少设； 3. 业务 QPS：QPS=50 需至少 5 个 Worker（每个 Worker 处理 10 QPS）	1 块 GPU 场景： - 小模型（<500MB）：Worker 数 = GPU 显存（GB）× 2（如 16GB→32 个，需测试显存占用）； - 中模型（500MB-2GB）：Worker 数 = GPU 显存（GB）× 1（如 16GB→16 个）； - 大模型（>2GB）：Worker 数 =（GPU 显存（GB）- 3）÷ 模型体积（GB）（如 16GB、5GB 模型→(16-3)/5≈2 个）；多 GPU 场景：用`CUDA_VISIBLE_DEVICES`绑定 Worker 与 GPU（如 Worker 1-2 绑定 GPU 0，Worker 3-4 绑定 GPU 1）
`--timeout 60`	1. 模型推理耗时：批量大小 10 的 ResNet50 推理约 1s，批量 32 约 3s； 2. 业务容忍度：电商场景容忍 5s 超时，金融场景容忍 2s	1. 先测试单批次最大推理耗时（如批量 32 耗时 5s）； 2. 超时时间设为最大耗时的 3 倍（5s×3=15s），避免正常请求被误判超时； 3. 若频繁超时，需检查：GPU 是否过载（显存 / 使用率 100%）、批量大小是否过大（需降低 MAX_BATCH_SIZE）
`--max-requests 2000`	1. 内存泄漏风险：PyTorch 虽无明显泄漏，但长期运行可能有显存碎片； 2. 业务稳定性要求：核心业务需更频繁重启（如 1000 请求），非核心业务可放宽（如 5000 请求）	1. 按 QPS 计算重启周期：若 QPS=20，2000 请求对应 100 分钟重启一次； 2. 观察显存变化：部署后用`nvidia-smi`持续监控，若显存随请求数增长，需减小 max-requests（如从 2000 改为 1000）； 3. 避免设过小：如 max-requests=100，QPS=20 时 5 分钟重启一次，可能导致服务波动
`--worker-tmp-dir /dev/shm`	1. 临时文件读写频率：推理时需生成临时数据（如预处理后的图像），频率高则需优化； 2. 磁盘性能：若服务器磁盘 IO 慢（如机械硬盘），设为内存目录可显著提升速度	1. 所有 GPU 部署场景均建议启用：/dev/shm 是内存文件系统，读写速度比 SSD 快 10 倍以上； 2. 注意内存大小：/dev/shm 默认大小为物理内存的一半，若临时文件大（如批量图像），需确保内存充足（可通过`mount -o remount,size=16G /dev/shm`调整大小）

5.4 本地生产模式验证

在容器化前，建议用 Gunicorn 启动服务，模拟生产环境验证并发能力与稳定性：

# 步骤1：设置环境变量（模拟生产部署时的配置，避免硬编码）
export PORT=9999
export WORKER_NUM=2  # 假设本地GPU显存充足，设2个Worker
export MAX_BATCH_SIZE=32

# 步骤2：用Gunicorn启动生产模式服务（与容器内启动命令完全一致，确保环境一致）
gunicorn -k uvicorn.workers.UvicornWorker -w $WORKER_NUM -b 0.0.0.0:$PORT app.app:app --timeout 60 --max-requests 2000 --log-config app/logging.json

# 步骤3：验证多进程与并发能力（生产环境核心需求）
# 1. 查看进程：用ps命令确认Gunicorn Master进程与2个Worker进程
ps aux | grep gunicorn
# 预期输出：1个gunicorn: master process，2个gunicorn: worker process

# 2. 测试并发请求：用ab工具（Apache Bench）发送100个请求，并发10（模拟业务峰值）
ab -n 100 -c 10 -p test_data.json -T application/json http://localhost:9999/predict
# test_data.json内容：{"features":[[6.0],[7.0],...,[15.0]]}（10个样本）
# 预期结果：所有请求成功（失败率0%），平均响应时间<100ms，QPS>10

# 步骤4：验证故障恢复（生产级服务必备能力）
# 1. 找到一个Worker进程ID（从ps命令输出中获取）
# 2. 杀死该Worker进程：kill -9 <worker_pid>
# 3. 立即查看进程：确认Master已启动新的Worker进程（进程ID变化）
ps aux | grep gunicorn
# 预期输出：原Worker进程消失，新Worker进程出现（证明故障自动恢复，服务不中断）

若本地生产模式验证通过，说明 Gunicorn 配置合理，服务具备高并发与高可用能力，可进入容器化部署阶段。

第六章环境容器化部署：Docker 确保一致性

容器化是解决 “部署环境不一致” 的核心方案 —— 通过 Docker 将代码、依赖、CUDA Runtime、模型权重打包为镜像，确保在任意服务器上部署时，环境完全一致（Python 版本、PyTorch 版本、CUDA 版本均相同），彻底杜绝 “本地能跑线上不行” 的问题。同时，Docker 镜像便于版本管理与迁移，是自动化部署的基础。

6.1 Dockerfile 部署设计

Dockerfile 的设计需兼顾 “构建速度” 与 “镜像体积”：采用分层构建策略，优先缓存不变的依赖层（如系统依赖、Python 依赖），仅在代码或权重变化时重新构建上层；同时使用轻量化基础镜像（如 NVIDIA CUDA Runtime 而非 Devel），减小镜像体积（节省仓库存储空间与部署拉取时间）。

# app/Dockerfile（部署环境容器化，GPU支持）
# 基础镜像：选择NVIDIA CUDA Runtime镜像（仅含运行依赖，体积小；Devel含编译工具，体积大，部署无需）
# 版本选择：Ubuntu 22.04（长期支持版）+ CUDA 12.2（与PyTorch版本匹配）
FROM nvidia/cuda:12.2.0-runtime-ubuntu22.04

# 维护者信息（可选，便于团队协作）
LABEL maintainer="ai-team@example.com"
LABEL description="Docker image for linear model inference (FastAPI+Gunicorn+PyTorch GPU)"

# 部署环境配置：设置时区（避免安装系统依赖时弹出交互框，阻塞构建）
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

# 安装系统基础依赖（仅安装部署必需的，避免冗余）
# 必需依赖：python3（运行代码）、python3-pip（安装Python依赖）、python3-dev（编译部分Python包）
# 清理apt缓存：rm -rf /var/lib/apt/lists/*，减小镜像体积
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        python3 \
        python3-pip \
        python3-dev \
        && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# 设置部署工作目录（后续命令均在此目录下执行，避免文件混乱）
WORKDIR /app

# 复制Python依赖清单并安装（利用Docker缓存：仅requirements.txt变更时重新安装）
# 关键：将requirements.txt单独复制并安装，避免代码变更导致依赖层重新构建（节省构建时间）
COPY app/requirements.txt ./
RUN pip3 install --no-cache-dir \
    -r requirements.txt \
    -f https://download.pytorch.org/whl/torch_stable.html \
    && \
    # 清理pip缓存：减小镜像体积（pip默认缓存下载的包，部署无需）
    rm -rf /root/.cache/pip

# 复制部署核心代码与模型权重（代码或权重变更时，此层及以上需重新构建）
# 注意：先复制代码，再复制权重（权重文件更大，变更频率更低，可部分利用缓存？不，复制顺序不影响缓存，仅文件变更影响）
COPY app ./app
COPY model.pth ./

# 部署安全优化：创建非root用户并切换（避免容器内使用root权限，降低安全风险）
# 若代码需写文件，需给该用户授权（如chown -R appuser:appuser /app）
RUN useradd -m appuser && \
    chown -R appuser:appuser /app  # 授予用户对工作目录的读写权限
USER appuser

# 部署环境变量（默认值，可通过docker run -e或CI/CD注入覆盖）
# 注意：环境变量仅在容器启动时生效，构建时无法访问（如需构建时变量，用ARG）
ENV PORT=9999 \
    MODEL_PATH=./model.pth \
    USE_AMP=1 \
    MAX_BATCH_SIZE=32 \
    WORKER_NUM=1

# 暴露部署端口（仅声明容器内服务监听的端口，不实际映射到宿主机；实际映射用docker run -p）
EXPOSE $PORT

# 容器启动命令（生产级Gunicorn服务，与本地生产模式一致）
# 用sh -c包裹，支持环境变量替换（如$WORKER_NUM）
CMD ["sh", "-c", "gunicorn \
    -k uvicorn.workers.UvicornWorker \
    -w $WORKER_NUM \
    -b 0.0.0.0:$PORT \
    app.app:app \
    --timeout 60 \
    --graceful-timeout 30 \
    --max-requests 2000 \
    --max-requests-jitter 200 \
    --log-config app/logging.json \
    --access-logfile - \
    --error-logfile - \
    --worker-tmp-dir /dev/shm"]

6.2 容器化部署操作步骤

6.2.1 部署前置条件（目标服务器需满足）

安装 Docker：参考Docker 官方文档，确保版本≥20.10（支持 NVIDIA Runtime）；
安装 NVIDIA Container Toolkit：支持 Docker 容器内调用 GPU，参考官方指南；
- 验证：执行docker run --rm --gpus all nvidia/cuda:12.2.0-runtime-ubuntu22.04 nvidia-smi，若能显示 GPU 信息，说明配置成功；
配置私有镜像仓库（可选，推荐）：如 Harbor、Nexus，用于存储 Docker 镜像（避免每次部署都在目标服务器构建镜像，节省时间）；
自托管 GitLab Runner（自动化部署用）：已部署在具备 Docker 权限的节点，可访问 GitLab 仓库、私有镜像仓库与目标服务器。

6.2.2 构建部署镜像（本地或 CI/CD 构建）

镜像构建可在本地执行（测试用）或由 GitLab Runner 自动执行（生产用）。本地构建步骤如下：

# 步骤1：登录私有镜像仓库（若使用，如Harbor）
# 格式：docker login <仓库地址> -u <用户名> -p <密码>
docker login harbor.example.com -u ai-deploy-user -p xxxxxxxx

# 步骤2：构建Docker镜像（核心步骤，确保镜像包含所有部署依赖）
# -t：指定镜像标签（格式：<仓库地址>/<命名空间>/<镜像名>:<版本>，便于追溯与管理）
# -f：指定Dockerfile路径（此处在app目录下）
# .：构建上下文（当前目录，Docker会读取该目录下的文件）
docker build \
  -t harbor.example.com/ai-team/linear-model-inference:v1.0 \
  -f app/Dockerfile \
  .

# 步骤3：验证镜像构建成功（避免构建失败的镜像流到部署环节）
# 查看镜像列表，确认新构建的镜像存在
docker images | grep linear-model-inference
# 预期输出：harbor.example.com/ai-team/linear-model-inference   v1.0   xxxxxxxx   5 minutes ago   4.2GB（体积因基础镜像与依赖而异）

# 步骤4：推送镜像到私有仓库（若使用，供目标服务器拉取，避免重复构建）
docker push harbor.example.com/ai-team/linear-model-inference:v1.0

6.2.3 目标服务器启动部署容器

镜像构建并推送后，在目标服务器拉取镜像并启动容器，步骤如下：

# 步骤1：登录私有镜像仓库（目标服务器执行，确保能拉取镜像）
docker login harbor.example.com -u ai-deploy-user -p xxxxxxxx

# 步骤2：拉取部署镜像（从私有仓库拉取，比本地构建快）
docker pull harbor.example.com/ai-team/linear-model-inference:v1.0

# 步骤3：停止并删除旧容器（若存在，用于模型更新，避免服务冲突）
# 先停止旧容器，再删除（避免直接删除运行中的容器导致业务中断）
docker stop linear-model-service || true
docker rm linear-model-service || true

# 步骤4：启动新部署容器（核心命令！重点配置GPU绑定与崩溃自动重启）
docker run -d \
  --name linear-model-service \  # 容器名称（便于后续运维，如查看日志、重启）
  --gpus device=0 \              # 绑定GPU设备（0表示第1块GPU，多GPU用device=0,1）
  -p 9999:9999 \                 # 端口映射：宿主机端口:容器端口（业务侧通过宿主机端口调用）
  -e WORKER_NUM=2 \              # 注入环境变量：Worker数量（根据GPU显存调整，避免显存溢出）
  -e MAX_BATCH_SIZE=32 \         # 注入环境变量：最大批量大小（防止超大请求压垮服务）
  --restart always \             # 容器异常退出时自动重启（如服务器重启、容器崩溃，保障高可用）
  --log-opt max-size=100m \      # 日志轮转：单个日志文件最大100MB（避免日志占满磁盘）
  --log-opt max-file=3 \         # 日志轮转：最多保留3个日志文件（平衡日志追溯与磁盘占用）
  harbor.example.com/ai-team/linear-model-inference:v1.0

# 步骤5：验证容器启动成功（确认服务已正常运行）
# 查看容器状态（Up状态表示正常运行，Exited表示启动失败）
docker ps | grep linear-model-service
# 预期输出：xxxxxxxx   harbor.example.com/ai-team/linear-model-inference:v1.0   "sh -c 'gunicorn -k ..."   10 seconds ago   Up 9 seconds   0.0.0.0:9999->9999/tcp   linear-model-service

# 步骤6：验证服务可用性（目标服务器本地或业务侧调用，确保服务能正常使用）
# 健康检查（监控工具会定期调用，确认服务存活）
curl http://localhost:9999/healthz
# 推理测试（验证模型能正常计算，结果符合预期）
curl -X POST http://localhost:9999/predict \
  -H "Content-Type: application/json" \
  -d '{"features":[[6.0],[7.0]]}'
# 预期返回：{"prediction":[[13.0],[15.0]],"request_id":"...","inference_time_ms":...}

# 步骤7：查看部署日志（排查问题用，若服务启动失败或推理报错，先看日志）
docker logs -f linear-model-service
# 预期输出：结构化JSON日志，包含模型加载成功、请求处理等信息（无ERROR级日志）

6.2.4 部署后基础运维命令（日常管理）

容器启动后，日常运维需用到以下命令：

# 1. 查看实时日志（跟踪请求处理情况，排查实时问题）
docker logs -f linear-model-service

# 2. 查看历史日志（排查过往问题，如1小时前的请求失败）
docker logs --tail 100 linear-model-service  # 查看最后100行日志

# 3. 重启部署服务（如修改环境变量后，需重启生效；或服务偶发卡顿）
docker restart linear-model-service

# 4. 停止部署服务（如服务器维护、版本回滚前，需先停止当前服务）
docker stop linear-model-service

# 5. 进入容器内部（排查问题，如查看文件、执行命令，相当于“登录”到容器）
docker exec -it linear-model-service bash

# 6. 查看GPU使用情况（确认模型是否在GPU上运行，避免CPU推理速度慢）
nvidia-smi
# 预期输出：进程列表中包含python3（Gunicorn Worker进程），且显存占用符合预期（如2个Worker各占1GB）

第七章进阶优化与自动化部署

7.1 自动化部署：GitLab CI/CD + 自托管 Runner

通过自托管 GitLab Runner 与 GitLab CI/CD，实现 “代码提交→镜像构建→推送→部署” 全自动化，无需手动操作。核心是编写.gitlab-ci.yml配置文件，定义三个阶段：build（构建镜像）、push（推送镜像）、deploy（远程部署）。关键配置如下：

stages:
  - build
  - push
  - deploy

variables:
  DOCKER_REGISTRY: harbor.example.com
  IMAGE_NAME: ai-team/linear-model-inference
  IMAGE_TAG: ${CI_COMMIT_SHORT_SHA}  # 用Git commit哈希作为标签，便于追溯（每个提交对应一个版本）
  TARGET_SERVER: 192.168.1.100      # 目标服务器IP（部署的目标节点）
  TARGET_USER: ubuntu               # 目标服务器用户名（需有Docker操作权限）

# 构建镜像
build_image:
  stage: build
  tags: [ai-gpu-runner]  # 匹配自托管Runner标签（确保在有GPU的Runner上构建，避免依赖问题）
  script:
    - docker login $DOCKER_REGISTRY -u $REGISTRY_USER -p $REGISTRY_PWD
    - docker build -t $DOCKER_REGISTRY/$IMAGE_NAME:$IMAGE_TAG -f app/Dockerfile .
  only: [main]  # 仅main分支提交触发（确保只有稳定代码才会部署）
  artifacts:
    expire_in: 1 hour  # 构建产物过期时间（避免占用仓库空间）

# 推送镜像
push_image:
  stage: push
  tags: [ai-gpu-runner]
  script:
    - docker push $DOCKER_REGISTRY/$IMAGE_NAME:$IMAGE_TAG
  only: [main]
  dependencies: [build_image]  # 依赖build_image阶段，确保先构建再推送

# 远程部署
deploy:
  stage: deploy
  tags: [ai-gpu-runner]
  script:
    # 配置SSH免密登录目标服务器（避免手动输入密码，实现自动化）
    - mkdir -p ~/.ssh && echo "$TARGET_SSH_KEY" > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -H $TARGET_SERVER >> ~/.ssh/known_hosts
    # 远程执行部署命令（拉取镜像、启动容器，与手动部署步骤一致）
    - ssh $TARGET_USER@$TARGET_SERVER "
        docker login $DOCKER_REGISTRY -u $REGISTRY_USER -p $REGISTRY_PWD;
        docker pull $DOCKER_REGISTRY/$IMAGE_NAME:$IMAGE_TAG;
        docker stop linear-model-service || true;
        docker rm linear-model-service || true;
        docker run -d --name linear-model-service --gpus device=0 -p 9999:9999 -e WORKER_NUM=2 $DOCKER_REGISTRY/$IMAGE_NAME:$IMAGE_TAG;
        docker logout $DOCKER_REGISTRY;
      "
  only: [main]
  dependencies: [push_image]  # 依赖push_image阶段，确保先推送再部署

第八章总结

本文通过 FastAPI + Gunicorn + Docker + GitLab CI/CD，为中小团队搭建了一套 轻量、可复现、生产可用 的模型服务化方案：

开发侧：Notebook 快速实验 → 导出 state_dict 权重（确保可迁移）；
部署侧：API 契约通过 FastAPI 固定，环境一致性由 Docker 保障（不用再调环境）；
运维侧：Gunicorn 提供并发与容错（Worker 崩了自动重启），CI/CD 实现零停机更新（代码提交后自动部署）；
监控侧：结构化日志 + 健康检查 + GPU 利用率监控，组成最小可观测性闭环（出问题能快速定位）。

这套方案最核心的价值在于：算法工程师不用再陷在 “环境调不通”“部署崩了要救火” 的琐碎里，能把精力聚焦在模型效果迭代上 —— 这才是算法团队最核心的价值。同时，方案不依赖复杂工具，不用投入大量资源搭建平台，1-2 人就能搞定从模型训练到服务上线的全流程，为中小团队打通了算法从 “实验验证” 到 “业务产生价值” 的落地路径。无论是线性模型、CNN 图像模型，还是 Transformer 类 NLP 模型，都能基于这套框架快速适配，真正实现 “一次搭建，多模型复用”。

中小团队模型部署选型实践：FastAPI+Gunicorn+Docker

前言

第一章 部署痛点与目标