Retinaface+CurricularFace保姆级教程：配置Prometheus监控推理服务健康状态

Retinaface+CurricularFace保姆级教程：配置Prometheus监控推理服务健康状态

你是不是也遇到过这样的问题：人脸识别服务跑得好好的，突然某天用户反馈“识别失败”“响应变慢”，但日志里找不到明显报错，重启又恢复正常？这种“玄学故障”背后，往往缺的不是模型能力，而是对服务运行状态的可观测性。

本文不讲模型原理，不堆参数调优，只聚焦一个工程师最关心的落地问题：如何给Retinaface+CurricularFace人脸识别推理服务装上“健康手环”——用Prometheus实现零侵入、可告警、能回溯的实时监控。全程基于你已有的镜像环境操作，无需重装依赖、不改一行业务代码，15分钟完成部署。

1. 先确认你的服务已经“活”着

在动手加监控前，得先确保你的Retinaface+CurricularFace服务本身是正常对外提供能力的。别跳过这步——很多监控配置失败，根源其实是服务压根没跑起来。

你手上的镜像默认不自动启动Web服务，它只预装了推理能力。所以第一步，我们要把它变成一个可被监控的HTTP服务。

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

cd /root/Retinaface_CurricularFace conda activate torch25

接着，用镜像里已有的inference_face.py为基础，快速封装一个轻量API服务。我们不用Flask或FastAPI大框架，就用Python标准库http.server写一个极简版（稳定、无额外依赖、适合生产验证）：

# 保存为 server.py，放在 /root/Retinaface_CurricularFace 目录下 import http.server import socketserver import json import os import subprocess import sys from urllib.parse import urlparse, parse_qs # 确保能导入模型代码 sys.path.insert(0, '/root/Retinaface_CurricularFace') class FaceRecognitionHandler(http.server.BaseHTTPRequestHandler): def do_GET(self): parsed_path = urlparse(self.path) if parsed_path.path == '/health': self.send_response(200) self.send_header('Content-type', 'application/json') self.end_headers() self.wfile.write(json.dumps({"status": "ok", "model": "RetinaFace+CurricularFace"}).encode()) return if parsed_path.path == '/metrics': # 这里未来会填入真实指标，现在先返回基础健康信息 self.send_response(200) self.send_header('Content-type', 'text/plain; charset=utf-8') self.end_headers() self.wfile.write(b'# HELP face_recognition_up Whether the face recognition service is up.\n') self.wfile.write(b'# TYPE face_recognition_up gauge\n') self.wfile.write(b'face_recognition_up 1\n') return self.send_error(404) def do_POST(self): if self.path != '/compare': self.send_error(404) return content_length = int(self.headers.get('Content-Length', 0)) post_data = self.rfile.read(content_length) try: data = json.loads(post_data.decode()) img1 = data.get('input1') img2 = data.get('input2') threshold = float(data.get('threshold', 0.4)) # 调用原生推理脚本（支持URL和本地路径） cmd = [sys.executable, 'inference_face.py'] if img1: cmd.extend(['--input1', img1]) if img2: cmd.extend(['--input2', img2]) if threshold != 0.4: cmd.extend(['--threshold', str(threshold)]) result = subprocess.run(cmd, capture_output=True, text=True, timeout=30) if result.returncode == 0: self.send_response(200) self.send_header('Content-type', 'application/json') self.end_headers() # 简单提取输出中的关键信息（实际项目中建议重构脚本输出结构） output_lines = result.stdout.strip().split('\n') score_line = [l for l in output_lines if '相似度得分' in l or 'score' in l.lower()] decision_line = [l for l in output_lines if '同一人' in l or '不同人' in l or 'decision' in l.lower()] response = { "status": "success", "score": float(score_line[0].split(':')[-1].strip()) if score_line else 0.0, "decision": decision_line[0].strip() if decision_line else "unknown" } self.wfile.write(json.dumps(response).encode()) else: self.send_response(500) self.send_header('Content-type', 'application/json') self.end_headers() self.wfile.write(json.dumps({ "status": "error", "message": result.stderr.strip() or result.stdout.strip() }).encode()) except Exception as e: self.send_response(500) self.send_header('Content-type', 'application/json') self.end_headers() self.wfile.write(json.dumps({"error": str(e)}).encode()) if __name__ == "__main__": port = 8000 with socketserver.TCPServer(("", port), FaceRecognitionHandler) as httpd: print(f"Face Recognition API server running on port {port}") httpd.serve_forever()

保存后，启动服务：

python server.py

新开一个终端，测试服务是否就绪：

curl http://localhost:8000/health # 应返回：{"status": "ok", "model": "RetinaFace+CurricularFace"} curl http://localhost:8000/metrics # 应返回基础指标文本

成功！你的服务现在有了两个关键端点：/health（健康检查）和/metrics（指标出口），这是Prometheus监控的基石。

2. 零配置部署Prometheus：三步到位

Prometheus不是要你编译安装，而是直接用官方Docker镜像——镜像里连配置文件模板都给你备好了。

2.1 创建监控配置文件

在宿主机（或容器内）新建目录/root/prometheus，然后创建配置文件prometheus.yml：

global: scrape_interval: 15s evaluation_interval: 15s scrape_configs: - job_name: 'face-recognition' static_configs: - targets: ['host.docker.internal:8000'] # 注意：这是Docker内部访问宿主的特殊地址 metrics_path: '/metrics' # 如果服务在宿主机运行（非Docker），改为 targets: ['localhost:8000']

小贴士：host.docker.internal是Docker Desktop（Mac/Windows）和较新Linux Docker的内置DNS，指向宿主机。如果你的服务也在Docker容器里运行，且与Prometheus同网络，可直接用服务名（如retinaface-service:8000）。

2.2 一键拉起Prometheus

执行以下命令（确保Docker已运行）：

docker run -d \ --name prometheus-face \ -p 9090:9090 \ -v /root/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \ -v /root/prometheus/data:/prometheus \ --restart=always \ prom/prometheus:v2.49.1 \ --config.file=/etc/prometheus/prometheus.yml \ --storage.tsdb.path=/prometheus \ --web.console.libraries=/usr/share/prometheus/console_libraries \ --web.console.templates=/usr/share/prometheus/consoles \ --storage.tsdb.retention.time=30d

等待10秒，打开浏览器访问http://localhost:9090，点击左上角"Status" → "Targets"，你应该看到face-recognition的状态是UP。

Prometheus已成功抓取到你的服务！

3. 让指标“活”起来：从空指标到真实业务洞察

目前/metrics端点只返回了一个静态值face_recognition_up 1。这远远不够。我们需要让服务主动上报真正反映业务健康度的指标：请求成功率、处理耗时、人脸检测数量、相似度分布……

好在我们不需要重写整个推理逻辑。只需在server.py里加几行代码，用最轻量的方式注入指标。

3.1 安装并集成Prometheus Python客户端

在已激活的torch25环境中安装：

pip install prometheus-client

3.2 改造server.py：添加4个核心业务指标

在server.py开头添加：

from prometheus_client import Counter, Histogram, Gauge, generate_latest, CONTENT_TYPE_LATEST import time # 定义指标 REQUEST_COUNT = Counter('face_recognition_requests_total', 'Total number of face recognition requests', ['method', 'status']) REQUEST_DURATION = Histogram('face_recognition_request_duration_seconds', 'Request duration in seconds', ['method']) FACE_DETECTED = Gauge('face_recognition_faces_detected', 'Number of faces detected in last request') SIMILARITY_SCORE = Gauge('face_recognition_similarity_score', 'Cosine similarity score of last comparison')

然后修改do_POST方法，在推理完成后、返回响应前，加入指标更新：

# ... 在 subprocess.run(...) 之后，response 构造之前 ... if result.returncode == 0: # 解析输出，提取关键数值 output_lines = result.stdout.strip().split('\n') score_line = [l for l in output_lines if '相似度得分' in l or 'score' in l.lower()] faces_line = [l for l in output_lines if '检测到人脸' in l or 'faces' in l.lower()] score = float(score_line[0].split(':')[-1].strip()) if score_line else 0.0 faces = int(faces_line[0].split(':')[-1].strip()) if faces_line else 0 # 更新指标 REQUEST_COUNT.labels(method='compare', status='success').inc() REQUEST_DURATION.labels(method='compare').observe(time.time() - start_time) # 需在do_POST开头加 start_time = time.time() FACE_DETECTED.set(faces) SIMILARITY_SCORE.set(score)

注意：你需要在do_POST函数开头加上start_time = time.time()，用于计算耗时。

保存并重启server.py。再访问http://localhost:9090/metrics，你会看到类似这样的动态指标：

# HELP face_recognition_requests_total Total number of face recognition requests # TYPE face_recognition_requests_total counter face_recognition_requests_total{method="compare",status="success"} 7.0 # HELP face_recognition_request_duration_seconds Request duration in seconds # TYPE face_recognition_request_duration_seconds histogram face_recognition_request_duration_seconds_bucket{method="compare",le="0.1"} 3.0 face_recognition_request_duration_seconds_bucket{method="compare",le="0.2"} 5.0 ...

指标不再是摆设，而是真实反映每一次请求的“生命体征”。

4. 告别“看数字”，用Grafana把监控可视化

光有Prometheus还不够直观。我们用Grafana把数据变成一眼看懂的图表。

4.1 启动Grafana

docker run -d \ --name grafana-face \ -p 3000:3000 \ -v /root/grafana-storage:/var/lib/grafana \ --restart=always \ -e "GF_SECURITY_ADMIN_PASSWORD=admin" \ grafana/grafana-enterprise:10.4.0

访问http://localhost:3000，用账号admin/admin登录（首次登录会提示改密码，可跳过）。

4.2 添加Prometheus数据源

• 左侧齿轮图标 →"Data Sources" → "Add data source"
• 选择Prometheus
• URL 填http://host.docker.internal:9090（同上，Docker Desktop环境）
• 点击"Save & test"，显示绿色 即成功。

4.3 导入现成的人脸识别监控面板

我们为你准备了一个开箱即用的JSON面板配置（含6个核心图表）：

• 请求成功率趋势（按分钟）
• 平均响应耗时 P95/P50
• 实时相似度分布直方图
• 检测到的人脸数量变化
• 错误请求明细（带错误类型）
• 服务健康状态（Up/Down）

复制以下JSON内容，回到Grafana首页 →"+" → "Import" → 粘贴JSON → Load

{ "dashboard": { "id": null, "title": "RetinaFace+CurricularFace Service Monitor", "panels": [ { "type": "graph", "title": "请求成功率（%）", "targets": [ { "expr": "100 * sum(rate(face_recognition_requests_total{status=\"success\"}[5m])) by (job) / sum(rate(face_recognition_requests_total[5m])) by (job)", "legendFormat": "{{job}}" } ] }, { "type": "graph", "title": "P95响应耗时（秒）", "targets": [ { "expr": "histogram_quantile(0.95, sum(rate(face_recognition_request_duration_seconds_bucket[5m])) by (le, job))", "legendFormat": "P95 {{job}}" } ] }, { "type": "histogram", "title": "相似度得分分布", "targets": [ { "expr": "face_recognition_similarity_score", "legendFormat": "Score" } ] } ] } }

提示：完整版JSON包含全部6个面板，此处为精简示意。实际使用请访问文末链接获取完整配置。

现在，你的Grafana首页就是一个专属的人脸识别服务“驾驶舱”，所有关键健康状态一目了然。

5. 关键问题实战解答：监控不是摆设，是排障利器

监控的价值，体现在你第一次用它定位到线上问题的那一刻。以下是三个高频场景的真实解法：

5.1 场景一：“识别变慢了，但没报错”

• 现象：用户反馈比对耗时从0.8秒涨到3秒，/health仍返回200。
• 排查路径：
  1. Grafana看"P95响应耗时"图表 → 确认是否真变慢；
  2. 切换到Prometheus查询页，输入：
     rate(face_recognition_request_duration_seconds_sum[5m]) / rate(face_recognition_request_duration_seconds_count[5m])
     → 查看平均耗时趋势；
  3. 再查：face_recognition_faces_detected→ 如果该值突增（如从1→5），说明图片中有多张人脸，RetinaFace在逐个检测，导致耗时上升；
• 结论：不是服务故障，是输入图片质量下降（多人混杂）。优化方案：前端增加图片预检，提示用户上传单人正面照。

5.2 场景二：“偶尔返回‘不同人’，但明明是同一人”

• 现象：相似度得分在0.38~0.42之间波动，阈值0.4导致判定不稳定。
• 排查路径：
  1. Grafana看"相似度得分分布"直方图 → 发现大量得分集中在0.35~0.45窄区间；
  2. 结合face_recognition_faces_detected→ 发现低分样本对应faces_detected=1，排除多脸干扰；
  3. 进一步查原始日志（docker logs retinaface-service）→ 发现部分请求出现CUDA out of memory警告。
• 结论：GPU显存不足导致特征提取精度下降。解决方案：降低batch size（修改inference_face.py中相关参数）或升级GPU。

5.3 场景三：“服务突然不可用，但容器没退出”

• 现象：/health返回503，/metrics无法访问，但docker ps显示容器仍在运行。
• 排查路径：
  1. Prometheus Targets页面 →face-recognition状态变为DOWN；
  2. 执行docker exec -it retinaface-service ps aux | grep python→ 发现server.py进程已僵死（Zombie）；
  3. 查看容器日志：docker logs --tail 50 retinaface-service→ 找到OSError: [Errno 24] Too many open files。
• 结论：文件描述符耗尽。根本原因：未正确关闭图片IO流。修复：在inference_face.py中所有open()后加with语句或.close()。

这些都不是靠“猜”出来的，而是监控数据给出的明确线索。

6. 总结：监控不是附加项，而是服务的“呼吸系统”

回顾整个过程，你只做了三件事：

1. 用10行Python，把推理脚本包装成带/health和/metrics的HTTP服务；
2. 用1个Docker命令，启动Prometheus，自动抓取指标；
3. 用1次Grafana导入，获得可交互、可告警、可回溯的可视化看板。

没有改模型、没有调超参、没有碰CUDA，却让整个服务从“黑盒”变成了“透明玻璃房”。这才是工程化落地的真正意义——不追求技术炫技，只解决真实痛点。

下一步，你可以轻松扩展：

• 加入Alertmanager，当成功率低于95%时微信告警；
• 把/metrics端点暴露给K8s，实现Pod级健康探针；
• 用face_recognition_similarity_score做A/B测试，对比不同模型版本效果。

技术永远服务于业务。而一个好的监控体系，就是你守护业务最可靠的哨兵。

获取更多AI镜像

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