一、什么是模型部署？

训练好的模型如果只存在于本地笔记本上，就像一台没有接线的电视——能力再强，也发挥不了价值。**部署（Deployment）**就是将模型从实验环境迁移到生产环境，让它真正为用户提供服务的过程。

模型从训练到服务的完整旅程：

  实验室                       生产环境
  ┌──────────┐               ┌──────────────────────────────────┐
  │          │   部署工程    │                                  │
  │ .pkl 文件 │ ─────────── ▶ │  API服务  →  用户请求  →  响应   │
  │ 模型权重  │               │                                  │
  └──────────┘               └──────────────────────────────────┘
  
  部署的核心挑战：
  ① 环境一致性 — 本地跑通，服务器也要跑通
  ② 性能要求   — 100ms以内响应，而非训练时的分钟级
  ③ 高可用性   — 24/7不中断服务
  ④ 可扩展性   — 并发1000+请求时不崩溃
  ⑤ 可监控性   — 出问题时能快速定位

---

二、三种主流部署范式

AI模型部署范式全景：

  ┌─────────────────────────────────────────────────────────┐
  │                   用户/业务系统                          │
  └───────────────┬─────────────┬───────────────────────────┘
                  │             │                │
                  ▼             ▼                ▼
         ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
         │   单机部署    │ │   云端部署    │ │   边缘部署    │
         │  On-Premise  │ │  Cloud-based │ │ Edge Deploy  │
         └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
                │                │                │
         本地服务器         弹性云资源         IoT/终端设备
         固定算力           按需扩缩容         离线可用
         数据不出境         运维成本低         低延迟

维度	单机/私有化部署	云端部署	边缘部署
算力	固定，升级成本高	弹性扩容，按量付费	受限（手机/嵌入式芯片）
延迟	内网低延迟	受网络影响	极低（本地推理）
数据安全	数据不出境，合规友好	需加密传输/合规审查	数据留在终端，最安全
运维成本	需专职运维团队	云厂商托管，成本低	设备管理复杂
典型场景	金融/医疗等敏感行业	互联网产品、快速上线	自动驾驶、工业质检
代表方案	Docker + Nginx	AWS/阿里云/腾讯云	TensorFlow Lite/ONNX Runtime

---

三、模型文件格式：选哪个？

模型文件格式演化：

  训练框架专有格式              跨平台通用格式            量化压缩格式
  ┌──────────────┐            ┌──────────────┐        ┌──────────────┐
  │  .pkl/.joblib│            │    ONNX       │        │    GGUF      │
  │  （sklearn）  │  ──转换── ▶ │  开放神经网络 │  ── ▶  │ （LLM量化）  │
  │  .pt/.pth    │            │  交换格式     │        │  INT4/INT8   │
  │  （PyTorch）  │            └──────────────┘        └──────────────┘
  │  SavedModel  │
  │  （TF/Keras） │
  └──────────────┘

格式	来源	跨平台	推理速度	适用场景
.pkl	scikit-learn	❌ 仅Python	★★★	传统ML模型（随机森林、SVM等）
.pt/.pth	PyTorch	❌ 需PyTorch	★★★	开发调试阶段
TorchScript	PyTorch	✅ 无需Python	★★★★	PyTorch生产部署
ONNX	开放标准	✅ 支持30+框架	★★★★	跨框架、跨平台部署首选
SavedModel	TensorFlow	✅（TF生态）	★★★★	TF/Keras生产部署
GGUF	llama.cpp	✅ CPU优化	★★★	LLM量化推理（本地部署大模型）

3.1 PyTorch 模型转 ONNX

import torch
import torch.nn as nn
import onnx
import onnxruntime as ort
import numpy as np

# 假设已有训练好的 PyTorch 模型
class SentimentModel(nn.Module):
    def __init__(self, input_dim=768, num_classes=3):
        super().__init__()
        self.classifier = nn.Sequential(
            nn.Linear(input_dim, 256),
            nn.ReLU(),
            nn.Dropout(0.3),
            nn.Linear(256, num_classes)
        )
    
    def forward(self, x):
        return self.classifier(x)

# 导出为 ONNX 格式
def export_to_onnx(model: nn.Module, onnx_path: str, input_dim: int = 768):
    """将 PyTorch 模型导出为 ONNX 格式"""
    model.eval()
    
    # 创建虚拟输入（batch_size=1, input_dim）
    dummy_input = torch.randn(1, input_dim)
    
    torch.onnx.export(
        model,
        dummy_input,
        onnx_path,
        export_params=True,
        opset_version=17,          # ONNX opset版本
        do_constant_folding=True,  # 常量折叠优化
        input_names=["input"],
        output_names=["output"],
        dynamic_axes={             # 支持动态batch_size
            "input": {0: "batch_size"},
            "output": {0: "batch_size"}
        }
    )
    print(f"模型已导出: {onnx_path}")
    
    # 验证 ONNX 模型
    onnx_model = onnx.load(onnx_path)
    onnx.checker.check_model(onnx_model)
    print("ONNX 模型验证通过")

# 使用 ONNX Runtime 推理（比 PyTorch 快 2-5 倍）
def onnx_inference(onnx_path: str, input_data: np.ndarray) -> np.ndarray:
    """使用 ONNX Runtime 进行推理"""
    # 创建推理会话（自动选择最优执行引擎）
    providers = ['CUDAExecutionProvider', 'CPUExecutionProvider']
    session = ort.InferenceSession(onnx_path, providers=providers)
    
    input_name = session.get_inputs()[0].name
    outputs = session.run(None, {input_name: input_data.astype(np.float32)})
    return outputs[0]

# 示例
model = SentimentModel()
export_to_onnx(model, "sentiment_model.onnx")

test_input = np.random.randn(4, 768)  # batch_size=4
result = onnx_inference("sentiment_model.onnx", test_input)
print(f"推理结果形状: {result.shape}")  # (4, 3)

---

四、部署环境配置

4.1 依赖管理

# requirements.txt（生产环境，固定版本号）
# requirements-lock.txt 由 pip freeze 生成

torch==2.1.0+cpu          # CPU版本，比GPU版本小4倍
onnxruntime==1.16.0        # ONNX Runtime
fastapi==0.104.1           # API框架
uvicorn[standard]==0.24.0  # ASGI服务器
pydantic==2.5.0            # 数据校验
numpy==1.24.4

# 生成锁定文件（确保环境可复现）
# pip freeze > requirements-lock.txt

# 创建独立虚拟环境（避免依赖冲突）
conda create -n sentiment_prod python=3.10 -y
conda activate sentiment_prod
pip install -r requirements.txt

# 验证环境
python -c "import torch; import onnxruntime; import fastapi; print('环境OK')"

4.2 Docker 容器化（推荐生产方式）

# Dockerfile — 多阶段构建，减小镜像体积
FROM python:3.10-slim AS builder

WORKDIR /app

# 先复制依赖文件，利用Docker缓存层加速构建
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 正式应用阶段
FROM python:3.10-slim

WORKDIR /app

# 从builder阶段复制已安装的包
COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin

# 复制应用代码和模型文件
COPY . .

# 创建非root用户（安全最佳实践）
RUN useradd -m appuser
USER appuser

# 暴露服务端口
EXPOSE 8000

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

# 启动命令
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

# 构建镜像
docker build -t sentiment-api:v2.1.0 .

# 运行容器
docker run -d \
  --name sentiment-service \
  -p 8000:8000 \
  -v $(pwd)/models:/app/models \  # 挂载模型目录
  --memory="2g" \                  # 限制内存
  --cpus="2.0" \                   # 限制CPU
  sentiment-api:v2.1.0

# 查看日志
docker logs -f sentiment-service

---

五、推理服务搭建（FastAPI 完整示例）

# app/main.py — 完整可运行的推理服务
import time
import logging
import numpy as np
from contextlib import asynccontextmanager
from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel, Field
from typing import Optional
import onnxruntime as ort

# 配置日志
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# 全局模型会话（避免每次请求重新加载）
ort_session: Optional[ort.InferenceSession] = None

@asynccontextmanager
async def lifespan(app: FastAPI):
    """应用生命周期管理：启动时加载模型"""
    global ort_session
    logger.info("正在加载 ONNX 模型...")
    ort_session = ort.InferenceSession(
        "models/sentiment_model.onnx",
        providers=['CPUExecutionProvider']
    )
    logger.info("模型加载完成")
    yield  # 应用运行期间
    logger.info("服务关闭，释放资源")

app = FastAPI(
    title="情感分析推理服务",
    version="2.1.0",
    lifespan=lifespan
)

# 请求/响应数据模型
class PredictRequest(BaseModel):
    text: str = Field(..., min_length=1, max_length=512, description="待分析文本")
    
class PredictResponse(BaseModel):
    text: str
    label: str
    confidence: float
    latency_ms: float

# 模拟文本向量化（实际项目中替换为真实Tokenizer+Encoder）
def encode_text(text: str) -> np.ndarray:
    """将文本转换为768维特征向量（示意）"""
    np.random.seed(len(text))  # 固定种子，同文本同结果
    return np.random.randn(1, 768).astype(np.float32)

LABEL_MAP = {0: "正面", 1: "中性", 2: "负面"}

@app.post("/predict", response_model=PredictResponse)
async def predict(request: PredictRequest):
    """情感分析推理接口"""
    start_time = time.perf_counter()
    
    try:
        # 1. 文本编码
        input_vector = encode_text(request.text)
        
        # 2. ONNX 推理
        input_name = ort_session.get_inputs()[0].name
        outputs = ort_session.run(None, {input_name: input_vector})
        logits = outputs[0][0]  # shape: (3,)
        
        # 3. Softmax → 概率
        exp_logits = np.exp(logits - logits.max())
        probs = exp_logits / exp_logits.sum()
        
        pred_class = int(np.argmax(probs))
        confidence = float(probs[pred_class])
        
        latency_ms = (time.perf_counter() - start_time) * 1000
        
        return PredictResponse(
            text=request.text,
            label=LABEL_MAP[pred_class],
            confidence=round(confidence, 4),
            latency_ms=round(latency_ms, 2)
        )
    
    except Exception as e:
        logger.error(f"推理失败: {e}")
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/health")
async def health_check():
    """健康检查接口（供负载均衡器探测）"""
    return {"status": "healthy", "model_loaded": ort_session is not None}

@app.get("/metrics/basic")
async def basic_metrics():
    """基础指标接口"""
    return {"service": "sentiment-api", "version": "2.1.0"}

# 启动命令: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 测试 API
curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{"text": "这个产品真的太好用了，强烈推荐！"}'

# 预期响应
# {"text":"这个产品真的太好用了，强烈推荐！",
#  "label":"正面","confidence":0.8734,"latency_ms":12.3}

---

六、部署前 Go/No-Go 检查清单

部署前 Go/No-Go 决策树：

  开始部署评审
        │
        ▼
  [检查1] 所有测试指标达标？
        │
    YES ──────▶ [检查2] 模型文件完整性验证通过？
        │              │
    NO  │          YES ──▶ [检查3] 推理延迟P99 ≤ 目标值？
        ▼              │          │
      STOP          NO │      YES ──▶ [检查4] 健康检查接口响应正常？
      修复指标         ▼              │          │
                    STOP          NO  │      YES ──▶ [检查5] 回滚方案已准备？
                    优化推理           ▼              │
                                   STOP          YES ──▶ 🟢 GO — 批准部署
                                   调查延迟        │
                                                NO  ▼
                                               🔴 NO-GO — 准备回滚方案

检查项	验证方法	通过标准
指标达标	运行测试套件	全部 P0 指标 ✅
文件完整性	md5sum/sha256 校验	与训练时哈希一致
推理延迟	locust/ab 压测	P99 ≤ 目标值
内存占用	压测时监控 RSS	不超过配额80%
健康检查	GET /health	返回200
日志正常	查看应用日志	无 ERROR 级别
回滚方案	演练回滚流程	≤5分钟完成回滚

---

七、主流云平台部署对比

平台	特点	适合场景	免费额度
阿里云 PAI	国内最完善，中文文档齐全，与阿里生态打通	国内企业部署	ECS抢占式实例低成本
腾讯云 TI	与微信/企微生态打通，金融级安全合规	有腾讯系业务需求	免费试用名额
HuggingFace Spaces	开源模型展示首选，部署极简（改配置文件）	开源项目演示/个人	免费CPU实例
AWS SageMaker	功能最全，MLOps工具链最完善	大型企业、全球化部署	免费套餐2个月
本地Docker	完全自控，无外部依赖，数据不出境	私有化部署、开发调试	无成本

---

八、考试重点

核心概念辨析

概念	定义	关键特征
单机部署	模型在单台服务器上运行	简单但无弹性扩缩
云端部署	利用云计算资源托管模型服务	弹性伸缩、按需付费
边缘部署	模型运行在终端设备上（手机/IoT）	离线推理、低延迟
ONNX	开放神经网络交换格式	跨框架跨平台，推理加速
容器化	将模型及其依赖打包为Docker镜像	环境一致性、可移植
推理延迟	从接收请求到返回结果的时间	P99通常要求≤200ms

高频考题 Q&A

Q1：ONNX 格式相比 .pt 文件有什么优势？
A：ONNX 是跨框架、跨平台的标准格式，可在 ONNX Runtime 上运行，无需安装 PyTorch，且推理速度通常比原始 PyTorch 快 2-5 倍，适合生产部署。

Q2：边缘部署的核心优势是什么？
A：①离线推理（无需网络）；②极低延迟（本地计算，无网络往返）；③数据隐私保护（数据不离开终端设备）。常见于自动驾驶、工业质检、智能手机端的AI功能。

Q3：Docker 容器化部署解决了什么核心问题？
A：解决了环境一致性问题（“在我电脑上能跑，服务器上不行”）。容器将模型、代码、依赖库、运行时环境全部打包，在任何支持Docker的机器上都能一致运行。

Q4：以下关于模型部署格式，说法错误的是？
A. ONNX 支持多种框架导出
B. .pkl 文件可以在 Java 环境中直接加载
C. TorchScript 可以脱离 Python 环境运行
D. SavedModel 是 TensorFlow 的生产部署格式

答案：B。.pkl 是 Python 专属的序列化格式，不能在 Java 等其他语言环境中直接加载。

Q5：模型服务的健康检查接口（/health）的主要作用是什么？
A：供负载均衡器或容器编排系统（如 Kubernetes）探测服务是否正常运行。若健康检查失败，负载均衡器会停止向该实例分发流量，自动路由到健康节点。

---

九、备考贴士

📝 三种范式记忆：单机（稳定不弹性）→ 云端（弹性付费）→ 边缘（离线低延迟）

🎯 格式优先级：生产环境首选 ONNX 或 TorchScript；调试阶段用 .pt；LLM量化用 GGUF

💡 Docker核心价值：解决环境一致性问题，考试最高频考点

⚠️ 易错点：.pkl 文件只能在 Python 中用，常被考察为跨语言限制；边缘部署的核心优势是离线+低延迟，不是"便宜"