1. 项目概述：让自定义目标检测模型真正“跑起来”用起来

你训练好了一个 Detectron2 模型，它在自己的数据集上 mAP 达到了 42.7，推理速度在 V100 上稳定在 85ms/帧——但接下来呢？把它塞进 Jupyter Notebook 里跑几条测试图，还是写个 Python 脚本批量处理本地文件夹？这些都不是生产环境该有的样子。真正的落地，是让模型变成一个“服务”：前端网页上传一张图，后端秒级返回带框和标签的 JSON；IoT 设备拍张照片，通过 HTTP POST 就能拿到结构化结果；甚至集成进企业内部的 BI 系统，自动解析工单图片里的设备故障部位。这就是本项目要解决的核心问题—— Deploying Custom Detectron2 Models with a REST API 。它不是教你从零训练模型，而是聚焦在“最后一公里”：如何把你在研究阶段打磨好的、带 custom head、custom dataset、custom evaluator 的 Detectron2 模型，安全、稳定、低延迟、可监控地封装成一个标准的 REST 接口。关键词非常明确： Detectron2、REST API、Custom Model、Model Deployment、Flask、ONNX、Docker 。适合三类人：刚完成模型训练的算法工程师，急需把 demo 变成可用服务；负责 MLOps 的后端或 DevOps 工程师，需要快速接入 CV 模型；以及技术负责人，想评估一个视觉模型上线的完整技术栈成本与风险点。它不讲 PyTorch 分布式训练原理，也不讲 Detectron2 的 Registry 机制源码，只讲“怎么让模型在服务器上活下来，并且别人能调用”。我做过 7 个不同行业的 CV 模型部署，从医疗影像分割到工业质检，踩过所有坑——比如模型加载时显存不释放导致 OOM、多线程推理下 Detectron2 的 global config 冲突、JSON 序列化 numpy array 报错、Docker 镜像体积暴涨到 4GB……这些都不会出现在官方文档里，但会在这里一条条拆给你看。

2. 整体架构设计与方案选型逻辑

2.1 为什么不用 FastAPI？为什么坚持 Flask？

看到标题里写 REST API，很多人第一反应是 FastAPI——毕竟它自带 OpenAPI 文档、异步支持、Pydantic 校验，听着就高级。但我在线上跑了三年 Detectron2 服务， 全部采用 Flask ，原因非常实际：
第一，Detectron2 本身是同步框架，它的 DefaultPredictor 在推理时会锁住 CUDA context，强行用 async def predict() 包裹它，不仅不会提升吞吐，反而因 event loop 切换引入额外开销，实测 QPS 下降 12%~18%。我对比过同一台 T4 服务器上 100 并发压测：Flask + gunicorn（4 workers）稳定在 36 QPS；FastAPI + uvicorn（4 workers）只有 31 QPS，且错误率高 0.7%。
第二，Detectron2 的配置系统严重依赖全局状态（ detectron2.config.config.CfgNode ），在 FastAPI 的 async scope 下，多个请求共享 config 实例极易引发 race condition——比如 A 请求刚改了 MODEL.WEIGHTS 路径，B 请求就读到了脏数据，直接报 KeyError: 'MODEL' 。Flask 的 request context 虽然也是全局变量，但 gunicorn 的多进程模型天然隔离了 config 状态，每个 worker 进程独占一份 config 副本，彻底规避此问题。
第三，工程维护成本。FastAPI 的 Pydantic model 定义虽好，但 Detectron2 的输出是嵌套 dict + numpy array（如 instances.pred_boxes.tensor ），要写一个能完美序列化的 Pydantic model，得手动 flatten 所有字段、重写 __init__ 、处理 tensor → list 转换，代码量翻倍且易出错。而 Flask 用原生 json.dumps() 配合自定义 JSONEncoder ，3 行代码搞定：

class NumpyEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, np.ndarray): return obj.tolist()
        if isinstance(obj, np.float32): return float(obj)
        return super().default(obj)

所以， 选 Flask 不是守旧，而是对 Detectron2 运行时特性的尊重 。它不炫技，但稳——线上服务的第一性原理就是“不挂”。

2.2 为什么必须做 ONNX 导出？纯 PyTorch 模型不行吗？

官方文档说 Detectron2 支持 TorchScript，很多教程也教你怎么 torch.jit.trace 。但我要明确告诉你： 在生产部署中，TorchScript 是死路一条 。原因有三：

• 兼容性灾难 ：Detectron2 的 GeneralizedRCNN 包含大量动态控制流（如 if self.proposal_generator: ）、自定义算子（ ROIAlign ）、以及依赖 torchvision.ops 的 ops（如 nms ）。TorchScript trace 会静默失败或生成错误的图，尤其在 RPN 的 proposal 生成阶段，trace 出来的模型在推理时 pred_boxes 尺寸错乱，mAP 归零。我试过 12 种 trace 参数组合，无一成功通过全量测试集验证。
• 版本锁死 ：TorchScript 模型绑定 PyTorch 版本。你用 1.13.1 训练导出的 .pt ，在服务器上装 1.13.0 就直接 RuntimeError: version mismatch 。而线上环境升级 PyTorch 是高危操作，需全链路回归测试。
• 无法跨语言调用 ：TorchScript 本质还是 PyTorch 生态，Java/Go 服务想调用？得再包一层 Python subprocess，延迟飙升且不可控。

ONNX 则完全不同：它是开放标准，有成熟 C++ runtime（onnxruntime），支持 GPU/CPU/ARM 多后端，且版本向前兼容。更重要的是，Detectron2 官方提供了 export_model_to_onnx.py 工具（位于 tools/deploy/ ），它用 symbolic tracing 绕过动态分支，将 RPN 、 ROIHead 等模块拆解为静态子图，再拼接成完整 ONNX。我导出的 mask_rcnn_R_50_FPN_3x 模型，在 onnxruntime-gpu 1.16 上实测：

• 推理耗时比原生 PyTorch 快 9%（GPU 利用率从 72% 提升至 89%）
• 内存占用降低 31%（显存峰值从 3.2GB → 2.2GB）
• Docker 镜像体积减少 1.8GB（移除了整个 torch/torchvision 编译依赖）

所以，ONNX 不是“可选项”，而是 生产环境的强制路径 。它把模型从“Python 代码”变成了“标准数据流图”，这才是工程化的起点。

2.3 为什么 Docker 是底线？裸机部署有多危险？

有人觉得：“我服务器上已装好 CUDA、PyTorch，直接 pip install detectron2，写个 app.py run 就完事。” 这在开发机上 OK，但在生产环境等于埋雷。我见过最惨的案例：某工厂质检系统，裸机部署 Detectron2，某天运维执行 apt upgrade ，系统自动升级了 libcuda1 ，导致 nvidia-smi 显示驱动版本 525，而 PyTorch 1.12 编译时链接的是 515 的 stub，服务启动时报 undefined symbol: __cudaRegisterFatBinaryEnd ，全线停摆 4 小时。Docker 的价值在于：

• 环境原子性 ：镜像包含 OS base、CUDA driver、cudnn、PyTorch wheel、Detectron2 wheel 全部二进制，版本锁定，build once, run anywhere。
• 资源隔离 ：通过 --gpus device=0 --memory=4g --cpus=2 严格限制 GPU 显存、CPU 核数、内存，避免一个模型吃光整机资源。
• 发布可追溯 ： docker tag my-detectron2:v1.2.3-20240520 ，哪个 commit 对应哪个镜像，回滚只需 docker pull && docker stop && docker run ，5 分钟恢复。

我们不用 FROM nvidia/cuda:11.8.0-devel-ubuntu22.04 从头编译，而是用 FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime —— 它已预装 PyTorch + CUDA + cuDNN，省去 20 分钟编译时间，且 wheel 版本经 PyTorch 官方 QA 验证，稳定性远超自己编译。

3. 核心细节解析与实操要点

3.1 Detectron2 模型导出 ONNX 的避坑指南

Detectron2 官方 ONNX 导出脚本（ tools/deploy/export_model_to_onnx.py ）看似简单，但默认参数在 custom model 上 100% 失败。关键修改点如下：

第一，输入 shape 必须固定且合理 。
官方示例用 (1, 3, 800, 1200) ，这是 COCO 的短边缩放策略。但你的 custom dataset 图片尺寸可能全是 1024x768 或 1920x1080 。如果导出时用 (1,3,800,1200) ，而实际推理时送入 (1,3,1024,768) ，ONNX Runtime 会报 Input shape mismatch 。正确做法是：

• 用你的训练集统计真实尺寸分布，取 P95 尺寸（如 1080x810 ）
• 修改脚本中 dummy_input = torch.randn(1, 3, 1080, 810)
• 同时在 cfg.INPUT.MIN_SIZE_TEST 和 cfg.INPUT.MAX_SIZE_TEST 中设为相同值（如 1080 ），强制测试时不做 resize，保证输入 shape 一致

第二，必须 patch GeneralizedRCNN 的 inference 方法 。
Detectron2 的 inference 默认返回 dict ，含 instances （ Instances 对象）、 proposals 等。ONNX 不认识 Instances 类。需在导出前插入 monkey patch：

from detectron2.modeling import GeneralizedRCNN
original_inference = GeneralizedRCNN.inference
def patched_inference(self, batched_inputs, detected_instances=None, do_postprocess=True):
    outputs = original_inference(self, batched_inputs, detected_instances, do_postprocess)
    # 只返回最关键的 boxes, scores, labels, masks（如果用了 mask head）
    results = []
    for out in outputs:
        r = {}
        if "instances" in out:
            inst = out["instances"]
            r["pred_boxes"] = inst.pred_boxes.tensor.cpu().numpy()
            r["scores"] = inst.scores.cpu().numpy()
            r["pred_classes"] = inst.pred_classes.cpu().numpy()
            if hasattr(inst, "pred_masks"):
                r["pred_masks"] = inst.pred_masks.cpu().numpy()
        results.append(r)
    return results
GeneralizedRCNN.inference = patched_inference

这段代码把输出强制转为纯 numpy dict，ONNX tracer 才能识别。注意： cpu().numpy() 是必须的，GPU tensor 无法被 tracer 捕获。

第三，ONNX opset 版本必须 ≥ 12 。
opset 11 不支持 NonMaxSuppression 算子（Detectron2 的 batched_nms 依赖它），会导致导出失败。在 torch.onnx.export 调用中显式指定：

torch.onnx.export(
    model,
    dummy_input,
    "model.onnx",
    opset_version=12,  # 关键！
    input_names=["input"],
    output_names=["boxes", "scores", "labels", "masks"],
    dynamic_axes={
        "input": {0: "batch", 2: "height", 3: "width"},
        "boxes": {0: "num_detections"},
        "scores": {0: "num_detections"},
        "labels": {0: "num_detections"},
        "masks": {0: "num_detections", 1: "num_classes", 2: "mask_h", 3: "mask_w"} if has_mask else {}
    }
)

dynamic_axes 定义了哪些维度是动态的（如 batch size、图片尺寸），这是支持变长输入的基础。没有它，ONNX 模型只能处理固定尺寸图片。

提示：导出后务必用 onnx.checker.check_model(onnx.load("model.onnx")) 验证模型有效性。我曾因忘记 opset_version ，导出的模型 checker 直接报 Unsupported operator NonMaxSuppression ，浪费 3 小时排查。

3.2 Flask API 的健壮性设计：不只是写个 route

一个能上生产的 Flask API，绝不是 @app.route('/predict', methods=['POST']) 加几行 predict() 就完事。它必须解决四个核心问题：

问题一：模型加载时机与内存泄漏 。
新手常把 predictor = DefaultPredictor(cfg) 写在 route 函数里，每次请求都新建 predictor——这会导致：

• GPU 显存永不释放，100 次请求后 OOM
• DefaultPredictor 初始化耗时 1.2s（加载权重、构建图），QPS 直接崩盘

正确方案： 全局单例 + 延迟加载 。

# app.py
_predictor = None
_cfg = None

def get_predictor():
    global _predictor, _cfg
    if _predictor is None:
        _cfg = get_cfg()
        _cfg.merge_from_file("configs/custom.yaml")
        _cfg.MODEL.WEIGHTS = "model_final.pth"
        _cfg.MODEL.DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
        _predictor = DefaultPredictor(_cfg)
    return _predictor

@app.route('/predict', methods=['POST'])
def predict():
    predictor = get_predictor()  # 复用单例
    # ... 推理逻辑

但这样仍有风险：若服务器重启，第一个请求会卡 1.2s。更优解是 启动时预热 ：

# 在 app.run() 前
if __name__ == '__main__':
    # 预热：加载模型并跑一次空推理
    predictor = get_predictor()
    dummy_img = np.zeros((480, 640, 3), dtype=np.uint8)
    _ = predictor(dummy_img)
    print("Model warmed up!")
    app.run(host='0.0.0.0', port=5000)

问题二：多线程下的 config 冲突 。
Flask 默认单线程，但生产必须用 gunicorn。gunicorn 启动 4 个 worker 进程，每个进程有自己的 _cfg 和 _predictor ，看似隔离。但 Detectron2 的 CfgNode 有 __getattr__ 动态代理，若你在 route 中执行 _cfg.MODEL.ROI_HEADS.NUM_CLASSES = 5 ，这个修改会污染所有 worker 的 _cfg 实例。解决方案： 永远不要在 request 中修改 cfg 。所有配置必须在 get_predictor() 初始化时固化。若需动态 class 数，应在模型权重文件中固化（如 model_final.pth 的 roi_heads.box_predictor.cls_score.weight 形状为 [5+1, 1024] ），而非运行时改 cfg。

问题三：大图上传的 timeout 与内存爆炸 。
用户上传 20MB 的 8K 图片，Flask 默认 request.files['image'].read() 会把整个文件读入内存，瞬间吃光 16GB RAM。必须流式处理：

@app.route('/predict', methods=['POST'])
def predict():
    if 'image' not in request.files:
        return jsonify({"error": "No image file"}), 400
    
    file = request.files['image']
    # 用 PIL 流式解码，不加载全图到内存
    img = Image.open(file.stream)  # file.stream 是 BytesIO，PIL 直接解码
    img_array = np.array(img)  # 此时才转 numpy，且只存当前图
    
    # 添加尺寸校验，防 DOS 攻击
    if img_array.shape[0] > 2000 or img_array.shape[1] > 2000:
        return jsonify({"error": "Image too large, max 2000x2000"}), 400
    
    predictor = get_predictor()
    outputs = predictor(img_array)
    # ... 序列化返回

问题四：错误统一处理与日志 。
不能让 KeyError 或 CUDA out of memory 直接暴露给前端。需全局异常处理器：

@app.errorhandler(Exception)
def handle_exception(e):
    app.logger.error(f"Unhandled exception: {str(e)}", exc_info=True)
    return jsonify({"error": "Internal server error"}), 500

@app.errorhandler(400)
def bad_request(e):
    return jsonify({"error": "Bad request"}), 400

并在 gunicorn 配置中开启详细日志： gunicorn --log-level debug --access-logfile - --error-logfile - app:app 。

3.3 Dockerfile 的精简与加速技巧

一个 naive 的 Dockerfile 会这样写：

FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime
COPY requirements.txt .
RUN pip install -r requirements.txt  # 安装 detectron2, flask, opencv-python...
COPY . /app
WORKDIR /app
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

这会导致镜像体积超 3.5GB，build 时间 12 分钟，且 pip install detectron2 会触发源码编译，极不稳定。优化方案如下：

第一步：分层缓存最大化 。
把变动最少的层（base image, system deps）放最上，变动最多的（代码）放最下：

FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime

# 安装系统级依赖（极少变动）
RUN apt-get update && apt-get install -y \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    && rm -rf /var/lib/apt/lists/*

# 预编译 detectron2 wheel（关键！）
# 在宿主机上提前执行：python -m pip wheel --no-deps --wheel-dir /tmp/wheels detectron2
COPY wheels/ /tmp/wheels/
RUN pip install --find-links /tmp/wheels --no-index detectron2

# 安装其他纯 Python 包（requirements.txt 中去掉 detectron2）
COPY requirements.txt .
RUN pip install -r requirements.txt

# 复制模型权重和配置（体积大，但变动少）
COPY configs/ /app/configs/
COPY model_final.pth /app/model_final.pth

# 最后复制应用代码（最常变动）
COPY app.py /app/app.py
COPY utils/ /app/utils/

WORKDIR /app
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "--timeout", "120", "app:app"]

第二步：用 multi-stage build 进一步瘦身 。
pytorch/pytorch 镜像含大量 dev tools（gcc, cmake），运行时不需要。用 multi-stage：

# 构建阶段：编译 detectron2
FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-devel AS builder
RUN pip install cython && pip install -e detectron2_repo

# 运行阶段：仅含运行时依赖
FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime
# ... 复制编译好的 wheel 和其他依赖

实测可将镜像从 3.5GB 压至 1.4GB。

第三步：GPU 驱动兼容性兜底 。
NVIDIA Container Toolkit 要求宿主机驱动 >= 镜像 CUDA 版本。 pytorch:2.0.1-cuda11.7 要求驱动 >= 450.80.02。若客户环境驱动老旧（如 418.x），可降级用 pytorch:1.13.1-cuda11.6-cudnn8-runtime ，但需同步降级 Detectron2 版本（v0.6 对应 PyTorch 1.13）。

4. 实操过程与核心环节实现

4.1 从训练完成到 ONNX 导出的完整命令流

假设你的训练已完成，目录结构如下：

my_project/
├── configs/
│   └── custom.yaml          # 你的 custom config
├── output/
│   └── model_final.pth      # 训练好的权重
├── datasets/
│   └── custom/              # 自定义数据集
└── tools/deploy/
    └── export_model_to_onnx.py  # Detectron2 官方导出脚本

Step 1：准备导出环境
创建独立 conda env，避免污染主环境：

conda create -n onnx-export python=3.9
conda activate onnx-export
pip install torch==2.0.1+cu117 torchvision==0.15.2+cu117 --extra-index-url https://download.pytorch.org/whl/cu117
pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu117/torch2.0/index.html

注意： torch 和 detectron2 的 CUDA 版本（cu117）必须严格匹配，否则 import detectron2 报 undefined symbol 。

Step 2：修改导出脚本
编辑 tools/deploy/export_model_to_onnx.py ，定位到 def main() 函数，修改以下三处：

# 1. 加载你的 config 和权重
cfg = get_cfg()
cfg.merge_from_file("configs/custom.yaml")  # 改为你自己的路径
cfg.MODEL.WEIGHTS = "output/model_final.pth"
cfg.MODEL.DEVICE = "cuda"

# 2. 设置输入 dummy tensor（关键！）
# 用你的数据集统计的 P95 尺寸，例如 1024x768
dummy_input = torch.randn(1, 3, 1024, 768).to("cuda")

# 3. Patch inference 方法（前面 3.1 节的代码，粘贴到这里）
# ... （插入 patched_inference 定义和 monkey patch）

# 4. 调用 export
torch.onnx.export(
    model,
    dummy_input,
    "model.onnx",
    opset_version=12,
    input_names=["input"],
    output_names=["boxes", "scores", "labels", "masks"],  # 若无 mask，删掉 "masks"
    dynamic_axes={...}  # 按 3.1 节填写
)

Step 3：执行导出

cd my_project
python tools/deploy/export_model_to_onnx.py

成功后生成 model.onnx 。用 Netron（https://netron.app）打开，检查：

• 输入节点名是否为 input
• 输出节点名是否为 boxes , scores 等
• Graph 中是否有 NonMaxSuppression 算子（证明 opset 12 生效）

Step 4：验证 ONNX 模型
写一个 verify_onnx.py ：

import onnxruntime as ort
import numpy as np

# 加载 ONNX 模型
ort_session = ort.InferenceSession("model.onnx", providers=['CUDAExecutionProvider'])

# 构造 dummy input（必须与导出时 shape 一致）
dummy_img = np.random.randint(0, 255, (1, 3, 1024, 768), dtype=np.uint8).astype(np.float32)
dummy_img = dummy_img / 255.0  # Normalize to [0,1]

# 推理
outputs = ort_session.run(
    None,
    {"input": dummy_img}
)

print("ONNX inference success!")
print(f"Boxes shape: {outputs[0].shape}")
print(f"Scores shape: {outputs[1].shape}")

若输出正常，说明 ONNX 模型可用。此时可删除整个 conda env，导出工作完成。

4.2 Flask API 的完整代码实现与配置

app.py 是核心，代码需兼顾简洁与健壮：

import os
import json
import numpy as np
import torch
from flask import Flask, request, jsonify
from PIL import Image
import onnxruntime as ort

app = Flask(__name__)

# 全局 ONNX session 单例
_ort_session = None

def get_ort_session():
    global _ort_session
    if _ort_session is None:
        # 指定 provider，优先 GPU
        providers = ['CUDAExecutionProvider', 'CPUExecutionProvider']
        _ort_session = ort.InferenceSession("model.onnx", providers=providers)
    return _ort_session

class NumpyEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, np.ndarray):
            return obj.tolist()
        if isinstance(obj, (np.float32, np.float64)):
            return float(obj)
        if isinstance(obj, (np.int32, np.int64)):
            return int(obj)
        return super().default(obj)

@app.route('/health', methods=['GET'])
def health_check():
    """健康检查 endpoint，供 k8s liveness probe 使用"""
    return jsonify({"status": "healthy", "gpu_available": torch.cuda.is_available()})

@app.route('/predict', methods=['POST'])
def predict():
    try:
        # 1. 文件校验
        if 'image' not in request.files:
            return jsonify({"error": "Missing 'image' field in form data"}), 400
        
        file = request.files['image']
        if file.filename == '':
            return jsonify({"error": "Empty filename"}), 400
        
        # 2. 图片解码（流式，防大图 OOM）
        try:
            img = Image.open(file.stream)
            if img.mode != 'RGB':
                img = img.convert('RGB')
            img_array = np.array(img)
        except Exception as e:
            return jsonify({"error": f"Invalid image format: {str(e)}"}), 400
        
        # 3. 尺寸校验
        h, w = img_array.shape[:2]
        if h > 2000 or w > 2000:
            return jsonify({"error": "Image too large, max 2000x2000"}), 400
        
        # 4. 预处理：归一化、CHW 转换、添加 batch 维度
        img_tensor = img_array.astype(np.float32) / 255.0
        img_tensor = np.transpose(img_tensor, (2, 0, 1))  # HWC -> CHW
        img_tensor = np.expand_dims(img_tensor, axis=0)   # Add batch dim
        
        # 5. ONNX 推理
        ort_session = get_ort_session()
        outputs = ort_session.run(
            None,
            {"input": img_tensor}
        )
        
        # 6. 解析输出（按导出时的 output_names 顺序）
        boxes = outputs[0]   # [N, 4]
        scores = outputs[1]  # [N]
        labels = outputs[2]  # [N]
        masks = outputs[3] if len(outputs) > 3 else None  # [N, H, W]
        
        # 7. 置信度过滤（阈值 0.5）
        keep = scores > 0.5
        boxes = boxes[keep]
        scores = scores[keep]
        labels = labels[keep]
        if masks is not None:
            masks = masks[keep]
        
        # 8. 构建响应
        result = {
            "detections": [
                {
                    "bbox": box.tolist(),
                    "score": float(score),
                    "label_id": int(label),
                    "label_name": ["person", "car", "dog"][int(label)]  # 替换为你的类别名
                }
                for box, score, label in zip(boxes, scores, labels)
            ]
        }
        
        if masks is not None:
            # 将 mask 转为 RLE 或 base64（此处简化为 list）
            result["masks"] = [mask.tolist() for mask in masks]
        
        return jsonify(result), 200

    except ort.capi.onnxruntime_pybind11_state.RuntimeException as e:
        app.logger.error(f"ONNX Runtime error: {e}")
        return jsonify({"error": "Model inference failed"}), 500
    except Exception as e:
        app.logger.error(f"Unexpected error: {e}", exc_info=True)
        return jsonify({"error": "Internal server error"}), 500

if __name__ == '__main__':
    # 预热 ONNX session
    get_ort_session()
    print("ONNX model loaded and warmed up!")
    app.run(host='0.0.0.0', port=5000, debug=False)  # 生产禁用 debug

配套 requirements.txt ：

Flask==2.3.3
onnxruntime-gpu==1.16.0
Pillow==10.0.1
numpy==1.24.3

Gunicorn 启动配置 ：
创建 gunicorn.conf.py ：

bind = "0.0.0.0:5000"
bind_address = "0.0.0.0:5000"
workers = 4
worker_class = "sync"
timeout = 120
keepalive = 5
max_requests = 1000
max_requests_jitter = 100
preload = True  # 关键！确保每个 worker 都加载模型

启动命令：

gunicorn --config gunicorn.conf.py app:app

4.3 Docker 部署全流程与 GPU 调用验证

Step 1：构建镜像
确保 Dockerfile 、 requirements.txt 、 app.py 、 model.onnx 在同一目录：

# 构建（指定平台，避免 arm64 兼容问题）
docker build --platform linux/amd64 -t detectron2-api:v1.0 .

# 查看镜像大小
docker images | grep detectron2-api
# 应显示 < 1.5GB

Step 2：本地 GPU 测试

# 运行容器，映射 GPU 和端口
docker run --gpus all -p 5000:5000 -it detectron2-api:v1.0

# 在另一终端测试
curl -X POST http://localhost:5000/health
# 返回 {"status": "healthy", "gpu_available": true}

# 上传测试图
curl -X POST http://localhost:5000/predict \
  -F "image=@test.jpg"

Step 3：生产级启动（带资源限制）

docker run \
  --gpus device=0 \          # 指定使用 GPU 0
  --memory=4g \              # 限制内存 4GB
  --cpus=2 \                 # 限制 CPU 2 核
  --restart=always \         # 自动重启
  -p 5000:5000 \
  -d \                       # 后台运行
  --name detectron2-prod \
  detectron2-api:v1.0

Step 4：验证 GPU 利用率

# 进入容器
docker exec -it detectron2-prod bash

# 查看 GPU 使用
nvidia-smi
# 应显示 python 进程占用 GPU 显存

# 查看进程
ps aux | grep gunicorn
# 应显示 4 个 worker 进程

Step 5：压力测试
用 wrk 测试 QPS：

# 安装 wrk
sudo apt-get install wrk

# 100 并发，持续 30 秒
wrk -t4 -c100 -d30s http://localhost:5000/health
# 健康检查应 > 1000 QPS

wrk -t4 -c100 -d30s -s post.lua http://localhost:5000/predict
# post.lua 内容：设置 multipart/form-data 上传 test.jpg

实测指标（T4 GPU）：

• 健康检查：1250 QPS
• 图片推理：36 QPS（平均延迟 2.7s，P95 3.1s）
• GPU 利用率：85%~92%
• 显存占用：2.3GB（稳定，无泄漏）

5. 常见问题与排查技巧实录

5.1 ONNX 导出失败： RuntimeError: Exporting the operator xxx to ONNX opset version 12 is not supported

这是最常见错误，根本原因是 ONNX opset 12 不支持 Detectron2 某些算子。典型场景：

• torch.nn.functional.interpolate ：Detectron2 的 ROIAlign 后常接 interpolate 做 mask upsampling。
  解法 ：在导出前，用 torch.nn.Upsample 替换 interpolate 调用，或在 config 中关闭 mask head（若不需要 mask）。
• **`torch