Retinaface+CurricularFace部署教程：Prometheus+Grafana监控GPU显存与推理延迟

1. 镜像基础与环境准备

Retinaface+CurricularFace 是一套开箱即用的人脸识别模型镜像，专为工程化部署设计。它把人脸检测和特征比对两个关键环节整合进一个轻量、稳定、可监控的运行环境中。不同于需要手动配置依赖、调试模型路径的原始项目，这个镜像已经完成了从 CUDA 驱动适配到推理脚本封装的全部工作，你只需要启动容器，就能立刻开始测试和集成。

这套方案特别适合需要快速验证人脸识别能力的场景——比如考勤系统原型开发、门禁设备算法评估、或者智慧通行系统的前期技术选型。它不追求最前沿的模型结构，而是聚焦于“能跑、跑得稳、看得清”，让开发者把精力放在业务逻辑上，而不是环境踩坑里。

1.1 环境组件一览

镜像内预装了经过严格版本匹配的底层组件，所有依赖均已编译优化，避免了常见兼容性问题。以下是核心运行环境清单：

组件	版本	说明
Python	3.11.14	稳定且性能良好的 Python 运行时
PyTorch	2.5.0+cu121	与 CUDA 12.1 深度绑定的 GPU 加速版本
CUDA / cuDNN	12.1 / 8.9	匹配 A10/A100/V100 等主流推理卡的驱动栈
ModelScope	1.13.0	支持模型自动下载与缓存管理
代码位置	/root/Retinaface_CurricularFace	所有推理脚本、配置与示例图片均在此目录

为什么版本匹配这么重要？
很多人在部署时遇到 CUDA error: no kernel image is available for execution on the device 或 undefined symbol: _ZNK3c104Type11isSubtypeOfERKS0_ 这类报错，根源往往就是 PyTorch 和 CUDA 版本不一致。本镜像已提前规避所有这类风险，省去你反复重装、查文档、改源码的时间。

1.2 启动前的硬件确认

在拉取并运行镜像前，请先确认你的宿主机满足以下最低要求：

• GPU：至少一块 NVIDIA 显卡（推荐 Tesla T4 / A10 / A100），驱动版本 ≥ 515.65.01
• 显存：≥ 8GB（单张卡即可支撑并发 4 路以上实时比对）
• 系统：Ubuntu 20.04 或 22.04（其他发行版需自行验证 nvidia-container-toolkit 兼容性）

你可以通过以下命令快速检查 GPU 可见性与驱动状态：

nvidia-smi -L  # 查看识别到的 GPU 列表
nvidia-smi --query-gpu=name,temperature.gpu,memory.total --format=csv

如果命令返回空或报错，请先完成 NVIDIA 驱动与 container toolkit 的安装，再继续后续步骤。

2. 快速部署与本地推理验证

部署过程分为三步：拉取镜像、启动容器、进入环境执行测试。整个流程无需修改任何代码，5 分钟内即可看到第一组人脸比对结果。

2.1 拉取与启动容器

假设你已安装 Docker 和 nvidia-docker2，执行以下命令一键启动：

docker run -it --gpus all \
  -p 8080:8080 \
  -v $(pwd)/data:/root/data \
  --name face-recog \
  registry.cn-hangzhou.aliyuncs.com/csdn-mirror/retinaface-curricularface:latest

• -p 8080:8080：预留端口，为后续 Prometheus 暴露指标做准备（暂未启用，但端口已映射）
• -v $(pwd)/data:/root/data：挂载本地 data 目录，方便你传入自己的测试图片
• --name face-recog：为容器指定易记名称，便于后续管理

容器启动后，终端将自动进入 /root 目录。此时你已处于一个完整、隔离、GPU 就绪的推理环境中。

2.2 进入工作目录并激活环境

虽然镜像中已预装所有依赖，但为了确保环境变量和路径准确无误，仍需手动进入代码目录并激活 Conda 环境：

cd /root/Retinaface_CurricularFace
conda activate torch25

小提示：torch25 环境是镜像内置的专用推理环境，它与系统 Python 完全隔离，不会干扰宿主机或其他项目。你无需担心 pip install 冲突或版本污染。

2.3 运行首次推理测试

镜像自带两张示例人脸图，位于 ./imgs/ 目录下。直接运行默认命令即可完成端到端验证：

python inference_face.py

你会看到类似这样的输出：

[INFO] Detecting faces in input1...
[INFO] Detected 1 face in input1 (confidence: 0.992)
[INFO] Detecting faces in input2...
[INFO] Detected 1 face in input2 (confidence: 0.987)
[INFO] Extracting features...
[INFO] Cosine similarity: 0.862
[RESULT] Same person: YES (threshold=0.4)

这表示：

• 两张图中各检测出 1 张清晰人脸
• 提取的 512 维特征向量余弦相似度为 0.862
• 因高于默认阈值 0.4，判定为同一人

成功标志：只要看到 Same person: YES 或 NO，且没有 ImportError 或 CUDA out of memory 报错，就说明推理链路完全打通。

2.4 自定义图片比对实操

把你的两张照片放入宿主机的 data 目录（即容器内的 /root/data），然后用绝对路径调用：

python inference_face.py \
  --input1 /root/data/person_a.jpg \
  --input2 /root/data/person_b.jpg \
  --threshold 0.55

• --threshold 0.55：提高判定门槛，减少误识（例如双胞胎、妆容相似者等场景更适用）
• 脚本支持 JPG/PNG 格式，也支持 HTTP URL（如 --input1 https://example.com/face1.jpg）

注意：不要使用相对路径如 ../data/xxx.jpg，容器内路径与宿主机不同，务必用 /root/data/xxx.jpg 这样的绝对路径。

3. 构建可观测性：Prometheus + Grafana 监控体系

仅能跑通推理还不够。在生产环境中，你需要知道：

• GPU 显存是否快爆了？
• 每次推理耗时是否突然飙升？
• 并发请求下延迟是否稳定？

本节教你如何在不修改模型代码的前提下，为这套人脸服务加上完整的监控能力。

3.1 在推理脚本中注入监控埋点

我们不引入复杂框架，只用几行标准 Python 代码，为 inference_face.py 添加 Prometheus 指标暴露能力。

首先，在文件开头添加依赖导入：

# 在 import torch 之后、main() 函数之前插入
from prometheus_client import Counter, Histogram, Gauge, start_http_server
import time

然后，在 main() 函数顶部初始化指标：

# 初始化 Prometheus 指标
REQUEST_COUNT = Counter('face_recog_requests_total', 'Total number of face recognition requests')
REQUEST_DURATION = Histogram('face_recog_request_duration_seconds', 'Request duration in seconds')
GPU_MEMORY_USAGE = Gauge('gpu_memory_used_bytes', 'GPU memory used in bytes', ['device'])

最后，在实际推理逻辑前后加入计时与指标更新：

# 在调用 detect_and_extract_features() 前
start_time = time.time()
REQUEST_COUNT.inc()

# 在计算完 similarity 后、打印结果前
duration = time.time() - start_time
REQUEST_DURATION.observe(duration)

# 获取当前 GPU 显存使用（需先 pip install pynvml）
try:
    import pynvml
    pynvml.nvmlInit()
    handle = pynvml.nvmlDeviceGetHandleByIndex(0)
    info = pynvml.nvmlDeviceGetMemoryInfo(handle)
    GPU_MEMORY_USAGE.labels(device='gpu0').set(info.used)
except:
    pass  # 忽略 pynvml 不可用情况

保存修改后，启动一个独立的指标服务端口（例如 8000）：

# 在另一个终端中，进入容器并启动 HTTP 服务器
docker exec -it face-recog bash
cd /root/Retinaface_CurricularFace
python -c "from prometheus_client import start_http_server; start_http_server(8000)"

现在，访问 http://localhost:8000/metrics，你将看到类似这样的原始指标：

# HELP face_recog_requests_total Total number of face recognition requests
# TYPE face_recog_requests_total counter
face_recog_requests_total 3.0

# HELP face_recog_request_duration_seconds Request duration in seconds
# TYPE face_recog_request_duration_seconds histogram
face_recog_request_duration_seconds_bucket{le="0.1"} 0.0
face_recog_request_duration_seconds_bucket{le="0.2"} 2.0
face_recog_request_duration_seconds_bucket{le="0.5"} 3.0
face_recog_request_duration_seconds_sum 0.672
face_recog_request_duration_seconds_count 3.0

3.2 配置 Prometheus 抓取任务

在宿主机创建 prometheus.yml：

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'face-recog'
    static_configs:
      - targets: ['localhost:8000']

启动 Prometheus（需提前下载二进制或使用 Docker）：

docker run -d \
  -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  --name prometheus \
  prom/prometheus

打开 http://localhost:9090，在查询框输入 face_recog_requests_total，即可看到请求总量曲线。

3.3 搭建 Grafana 可视化面板

使用 Docker 一键启动 Grafana：

docker run -d \
  -p 3000:3000 \
  --name grafana \
  -e GF_SECURITY_ADMIN_PASSWORD=admin \
  grafana/grafana-enterprise

访问 http://localhost:3000，用 admin/admin 登录，添加 Prometheus 数据源（URL 填 http://host.docker.internal:9090），然后导入一个预设面板（ID：18608），你将立即看到：

• 实时 GPU 显存占用率（折线图）
• 推理延迟 P50/P90/P99 分位数（柱状图）
• 每分钟请求数（时间序列）
• 错误率（Counter 差值计算）

这些不是“看起来很酷”的图表，而是真正能帮你定位瓶颈的信号灯。比如当 face_recog_request_duration_seconds_p99 突然从 0.3s 涨到 1.2s，结合 gpu_memory_used_bytes 是否接近上限，你就能快速判断是模型过载还是显存泄漏。

4. 生产级部署建议与避坑指南

镜像开箱即用，但要真正落地到业务系统，还需注意几个关键细节。这些经验来自真实项目踩坑总结，不是文档里的理想描述。

4.1 并发处理：别让单进程成为瓶颈

默认脚本是单线程同步执行。如果你计划每秒处理 10+ 请求，必须改造为服务化接口。推荐两种轻量方案：

• 方案一：Flask API（适合中小流量）
  新建 app.py，用 @app.route('/compare') 封装 inference_face.py 核心逻辑，配合 gunicorn --workers 4 --threads 2 启动。

• 方案二：FastAPI + Uvicorn（推荐）
  更现代、异步友好，天然支持 OpenAPI 文档。只需 20 行代码即可提供 /compare POST 接口，接收 base64 图片和阈值参数，返回 JSON 结果。

无论哪种，都务必在入口处加日志记录（时间戳、输入尺寸、耗时、结果），这是排障的第一手资料。

4.2 图像预处理：质量决定上限

模型再强，也救不了模糊、过曝、严重畸变的输入。我们在多个客户现场发现：80% 的低分相似度案例，根源都在图像采集环节。

建议在调用推理前增加简单质检：

• 检查图像宽高比是否在 0.5–2.0 之间（排除极端长条图）
• 计算灰度图标准差，低于 20 视为过暗/过曝，拒绝处理并返回提示
• 使用 OpenCV 快速检测是否存在大面积纯黑/纯白区域（遮挡预警）

这些操作耗时不到 5ms，却能大幅降低无效请求和误判率。

4.3 模型热更新：不重启也能换模型

业务中常需切换不同精度的模型（如从 CurricularFace 换成更轻量的 ArcFace-Lite）。镜像支持热加载：

• 将新模型 .pth 文件放入 /root/models/
• 修改 inference_face.py 中的 MODEL_PATH 变量
• 发送 kill -SIGHUP $(pidof python) 重载配置（需提前在代码中注册信号处理器）

无需停服、无需重建镜像，真正实现“模型即配置”。

5. 总结：从能跑到可观测，再到可运维

这篇教程带你走完了人脸识别模型落地的三个关键阶段：

• 第一阶段：能跑 —— 通过预置镜像，5 分钟完成环境搭建与首测，绕过所有依赖地狱；
• 第二阶段：可观测 —— 用 10 行埋点代码 + Prometheus + Grafana，把黑盒推理变成透明流水线；
• 第三阶段：可运维 —— 通过并发封装、图像质检、热更新机制，让模型真正融入你的 DevOps 流程。

它不鼓吹“最强 SOTA”，而是专注解决工程师每天面对的真实问题：怎么少踩坑、怎么快上线、怎么稳运行。

当你下次接到“做个刷脸打卡功能”的需求时，不再需要从 GitHub clone 五个仓库、调试三天环境、祈祷模型不报错——你只需要一条 docker run，然后把精力放在设计 UI、对接门禁硬件、写测试用例上。

这才是 AI 工程化的意义：让技术隐形，让人解决问题。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。