MogFace-large部署教程：Docker Compose编排MogFace+Redis队列服务

MogFace-large部署教程：Docker Compose编排MogFace+Redis队列服务

1. 引言

人脸检测是计算机视觉领域的基础任务，从安防监控到手机美颜，从社交应用到身份验证，几乎无处不在。但现实世界的人脸检测挑战重重：光线明暗变化、人脸角度各异、背景复杂干扰、多人密集出现……这些因素都让传统检测方法力不从心。

今天要介绍的MogFace，正是为解决这些难题而生。它在权威的Wider Face人脸检测榜单上，已经在六个子项中霸榜超过一年，其论文也被CVPR 2022收录。简单来说，MogFace是目前最先进的人脸检测方法之一。

但技术再先进，如果部署复杂、使用困难，对大多数开发者来说也只是“纸上谈兵”。本文将带你用最简单的方式，通过Docker Compose一键部署完整的MogFace-large服务，不仅包含模型本身，还集成了Redis队列服务，让批量处理、异步推理变得轻松自如。

无论你是想快速体验SOTA人脸检测的效果，还是需要在项目中集成稳定的人脸检测服务，这篇教程都能帮你快速上手。我们不需要深入复杂的算法细节，只需要跟着步骤操作，就能拥有一个随时可用的人脸检测服务。

2. 环境准备与快速部署

2.1 系统要求与前置条件

在开始之前，确保你的系统满足以下基本要求：

• 操作系统：Linux（Ubuntu 18.04+、CentOS 7+）或 macOS，Windows用户建议使用WSL2
• Docker版本：20.10.0或更高版本
• Docker Compose版本：2.0.0或更高版本
• 硬件要求：
  • 内存：至少8GB（推荐16GB以上）
  • 存储：至少10GB可用空间
  • GPU：可选，有GPU可以加速推理（支持NVIDIA GPU）

如果你还没有安装Docker和Docker Compose，可以按照以下命令快速安装：

# 安装Docker（以Ubuntu为例） sudo apt-get update sudo apt-get install docker.io # 安装Docker Compose sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose # 验证安装 docker --version docker-compose --version

2.2 一键部署MogFace服务

我们提供了完整的Docker Compose配置文件，让你可以一键启动所有服务。首先创建一个项目目录并下载配置文件：

# 创建项目目录 mkdir mogface-deployment cd mogface-deployment # 创建docker-compose.yml文件 cat > docker-compose.yml << 'EOF' version: '3.8' services: # Redis服务，用于任务队列 redis: image: redis:7-alpine container_name: mogface-redis ports: - "6379:6379" volumes: - redis_data:/data command: redis-server --appendonly yes restart: unless-stopped # MogFace模型服务 mogface: image: registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-py38-torch2.0.1-tf1.15.5-1.8.0 container_name: mogface-service ports: - "7860:7860" volumes: - ./models:/root/.cache/modelscope/hub - ./data:/app/data environment: - REDIS_HOST=redis - REDIS_PORT=6379 depends_on: - redis command: > sh -c "pip install gradio==3.50.2 && python /usr/local/bin/webui.py" restart: unless-stopped deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] # 队列处理服务（可选） worker: build: context: . dockerfile: Dockerfile.worker container_name: mogface-worker environment: - REDIS_HOST=redis - REDIS_PORT=6379 depends_on: - redis - mogface restart: unless-stopped volumes: redis_data: EOF # 创建worker的Dockerfile cat > Dockerfile.worker << 'EOF' FROM python:3.8-slim WORKDIR /app # 安装系统依赖 RUN apt-get update && apt-get install -y \ libgl1-mesa-glx \ libglib2.0-0 \ && rm -rf /var/lib/apt/lists/* # 安装Python依赖 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制工作代码 COPY worker.py . # 启动worker CMD ["python", "worker.py"] EOF # 创建worker代码 cat > worker.py << 'EOF' import redis import json import time import requests from typing import Dict, Any class MogFaceWorker: def __init__(self, redis_host='redis', redis_port=6379): self.redis_client = redis.Redis( host=redis_host, port=redis_port, decode_responses=True ) self.queue_name = 'mogface_tasks' def process_task(self, task_data: Dict[str, Any]) -> Dict[str, Any]: """处理单个人脸检测任务""" try: # 这里可以添加具体的处理逻辑 # 例如调用MogFace API进行人脸检测 response = { 'task_id': task_data.get('task_id'), 'status': 'completed', 'result': {'faces_detected': 0}, # 示例结果 'timestamp': time.time() } return response except Exception as e: return { 'task_id': task_data.get('task_id'), 'status': 'failed', 'error': str(e), 'timestamp': time.time() } def run(self): """持续处理队列中的任务""" print("Worker started, waiting for tasks...") while True: # 从队列中获取任务 task_json = self.redis_client.brpop(self.queue_name, timeout=30) if task_json: _, task_str = task_json task_data = json.loads(task_str) print(f"Processing task: {task_data.get('task_id')}") # 处理任务 result = self.process_task(task_data) # 将结果存储到Redis result_key = f"result:{task_data.get('task_id')}" self.redis_client.setex( result_key, 3600, # 1小时过期 json.dumps(result) ) print(f"Task completed: {task_data.get('task_id')}") if __name__ == "__main__": worker = MogFaceWorker() worker.run() EOF # 创建requirements.txt cat > requirements.txt << 'EOF' redis==4.5.4 requests==2.28.2 numpy==1.24.3 opencv-python-headless==4.7.0.72 EOF

2.3 启动服务

配置文件准备好后，只需要一条命令就能启动所有服务：

# 启动所有服务（在后台运行） docker-compose up -d # 查看服务状态 docker-compose ps # 查看服务日志 docker-compose logs -f mogface

服务启动后，你会看到类似下面的输出：

[+] Running 3/3 ✔ Container mogface-redis Started ✔ Container mogface-service Started ✔ Container mogface-worker Started

现在，所有服务都已经在后台运行了：

• MogFace Web界面：访问 http://localhost:7860
• Redis服务：运行在 localhost:6379
• 队列处理服务：正在等待处理任务

3. MogFace模型快速上手

3.1 访问Web界面

打开浏览器，访问 http://localhost:7860（如果你在远程服务器部署，请将localhost替换为服务器IP地址）。

第一次访问时，系统需要加载MogFace-large模型，这可能需要几分钟时间，具体取决于你的网络速度和硬件配置。请耐心等待，直到页面完全加载。

页面加载完成后，你会看到一个简洁的Web界面，主要包含以下几个部分：

1. 图片上传区域：可以拖拽或点击上传图片
2. 示例图片：系统预置的一些测试图片，点击即可使用
3. 检测按钮：开始人脸检测
4. 结果显示区域：显示检测结果和标注后的图片

3.2 进行第一次人脸检测

让我们从最简单的开始，使用系统提供的示例图片：

1. 选择示例图片：在界面中找到示例图片区域，点击任意一张带有人脸的图片
2. 点击检测按钮：图片加载后，点击"开始检测"按钮
3. 查看结果：系统会显示检测到的人脸数量，并在图片上用方框标出每个人脸的位置

如果你有自己的图片，也可以直接上传：

• 支持格式：JPG、PNG、BMP等常见图片格式
• 建议尺寸：不超过2000×2000像素，太大的图片可能会影响处理速度
• 上传方式：拖拽到上传区域，或点击选择文件

3.3 理解检测结果

MogFace的检测结果不仅告诉你图片中有多少人脸，还提供了丰富的信息：

• 人脸位置：用矩形框标出每个人脸的位置
• 置信度分数：每个人脸检测的置信度（0-1之间，越高表示越确定是人脸）
• 人脸关键点：可以检测眼睛、鼻子、嘴巴等关键点位置
• 边界框坐标：精确的坐标信息，可用于后续处理

对于开发人员来说，这些数据可以通过API接口获取，方便集成到自己的应用中。

4. 使用Redis队列进行批量处理

4.1 为什么需要队列服务

在实际应用中，我们经常需要处理大量图片：

• 批量上传的用户照片
• 监控视频的逐帧分析
• 社交媒体内容的批量审核

如果直接调用模型接口，可能会遇到以下问题：

• 同时处理太多请求，服务器压力大
• 某个请求处理时间过长，阻塞其他请求
• 需要记录处理状态和结果

Redis队列就是为了解决这些问题而设计的。它的工作原理很简单：

1. 将检测任务放入队列
2. 工作进程从队列中取出任务
3. 调用MogFace进行处理
4. 将结果存储起来
5. 客户端可以查询处理状态和结果

4.2 提交批量检测任务

下面是一个简单的Python脚本，演示如何向队列提交任务：

# submit_tasks.py import redis import json import base64 import os from typing import List, Dict, Any class TaskSubmitter: def __init__(self, redis_host='localhost', redis_port=6379): self.redis_client = redis.Redis( host=redis_host, port=redis_port, decode_responses=True ) self.queue_name = 'mogface_tasks' def submit_single_task(self, image_path: str, task_id: str = None) -> str: """提交单个人脸检测任务""" if task_id is None: import uuid task_id = str(uuid.uuid4()) # 读取图片并编码为base64 with open(image_path, 'rb') as f: image_data = base64.b64encode(f.read()).decode('utf-8') # 构建任务数据 task_data = { 'task_id': task_id, 'image_data': image_data, 'image_name': os.path.basename(image_path), 'timestamp': time.time(), 'priority': 'normal' # 可以设置优先级 } # 将任务放入队列 self.redis_client.lpush(self.queue_name, json.dumps(task_data)) # 记录任务状态为等待中 status_key = f"status:{task_id}" self.redis_client.setex(status_key, 3600, 'pending') print(f"Task submitted: {task_id}") return task_id def submit_batch_tasks(self, image_paths: List[str]) -> List[str]: """批量提交任务""" task_ids = [] for image_path in image_paths: task_id = self.submit_single_task(image_path) task_ids.append(task_id) print(f"Submitted {len(task_ids)} tasks") return task_ids def get_task_status(self, task_id: str) -> str: """查询任务状态""" status_key = f"status:{task_id}" result_key = f"result:{task_id}" # 检查是否有结果 result = self.redis_client.get(result_key) if result: return 'completed' # 检查状态 status = self.redis_client.get(status_key) return status or 'unknown' def get_task_result(self, task_id: str) -> Dict[str, Any]: """获取任务结果""" result_key = f"result:{task_id}" result_json = self.redis_client.get(result_key) if result_json: return json.loads(result_json) return None if __name__ == "__main__": # 使用示例 submitter = TaskSubmitter() # 提交单个任务 task_id = submitter.submit_single_task('test_image.jpg') # 查询状态 import time while True: status = submitter.get_task_status(task_id) print(f"Task status: {status}") if status == 'completed': result = submitter.get_task_result(task_id) print(f"Task result: {result}") break time.sleep(2) # 等待2秒再查询

4.3 监控队列状态

了解队列的运行状态对于维护服务很重要。Redis提供了一些命令来监控队列：

# 进入Redis容器 docker exec -it mogface-redis redis-cli # 查看队列长度 LLEN mogface_tasks # 查看等待中的任务 LRANGE mogface_tasks 0 10 # 查看Redis内存使用情况 INFO memory # 查看连接数 INFO clients

你也可以编写一个简单的监控脚本：

# monitor_queue.py import redis import time from datetime import datetime def monitor_queue(redis_host='localhost', redis_port=6379, interval=5): """监控队列状态""" client = redis.Redis(host=redis_host, port=redis_port, decode_responses=True) print("Queue Monitor Started") print("=" * 50) while True: try: # 获取队列信息 queue_length = client.llen('mogface_tasks') memory_info = client.info('memory') used_memory = int(memory_info['used_memory']) / 1024 / 1024 # 转换为MB # 获取最近的任务状态 recent_tasks = [] for key in client.scan_iter("status:*", count=10): task_id = key.split(':')[1] status = client.get(key) recent_tasks.append((task_id, status)) # 打印监控信息 current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") print(f"\n[{current_time}]") print(f"Queue Length: {queue_length}") print(f"Memory Usage: {used_memory:.2f} MB") print(f"Recent Tasks: {len(recent_tasks)}") for task_id, status in recent_tasks[:5]: # 只显示最近5个 print(f" - {task_id[:8]}...: {status}") time.sleep(interval) except KeyboardInterrupt: print("\nMonitor stopped by user") break except Exception as e: print(f"Error: {e}") time.sleep(interval) if __name__ == "__main__": monitor_queue(interval=10) # 每10秒检查一次

5. 高级功能与实用技巧

5.1 调整检测参数

MogFace提供了一些参数可以调整，以适应不同的使用场景。虽然Web界面没有直接提供这些选项，但我们可以通过修改代码或API调用来调整：

# 调整检测参数示例 def detect_faces_with_params(image_path, confidence_threshold=0.5, max_faces=50): """ 使用自定义参数进行人脸检测 参数： - confidence_threshold: 置信度阈值，高于此值才认为是人脸 - max_faces: 最多检测的人脸数量 """ # 这里调用MogFace的检测函数 # 实际使用时需要根据具体的API或函数调用方式调整 detection_params = { 'confidence_threshold': confidence_threshold, 'max_faces': max_faces, 'enable_landmarks': True, # 是否检测关键点 'enable_attributes': False, # 是否检测属性（年龄、性别等） } # 不同的场景建议使用不同的参数： # 1. 安防监控：confidence_threshold=0.7，确保准确率 # 2. 社交应用：confidence_threshold=0.3，提高召回率 # 3. 密集人群：max_faces=100，检测更多人脸 return detection_params

5.2 处理常见问题

在实际使用中，你可能会遇到一些问题，这里提供一些解决方案：

问题1：检测速度慢

• 可能原因：图片太大、硬件性能不足、同时处理任务太多
• 解决方案：

  # 1. 压缩图片尺寸 def compress_image(image_path, max_size=1024): """将图片压缩到指定最大尺寸""" from PIL import Image img = Image.open(image_path) # 计算缩放比例 width, height = img.size if max(width, height) > max_size: ratio = max_size / max(width, height) new_size = (int(width * ratio), int(height * ratio)) img = img.resize(new_size, Image.Resampling.LANCZOS) return img # 2. 使用GPU加速（如果可用） # 确保Docker Compose中正确配置了GPU支持

问题2：检测准确率不够

• 可能原因：图片质量差、光线条件不好、人脸角度极端
• 解决方案：
  • 对图片进行预处理（调整亮度、对比度）
  • 尝试不同的置信度阈值
  • 使用多尺度检测（如果支持）

问题3：服务意外停止

• 可能原因：内存不足、Docker容器异常、模型加载失败
• 解决方案：

  # 查看容器状态 docker-compose ps # 查看容器日志 docker-compose logs mogface-service # 重启服务 docker-compose restart mogface-service # 如果模型加载失败，尝试重新拉取 docker-compose down docker-compose pull docker-compose up -d

5.3 集成到现有系统

如果你已经有一个现有的系统，想要集成MogFace人脸检测功能，这里有几个集成方案：

方案1：直接API调用

import requests import base64 class MogFaceClient: def __init__(self, base_url="http://localhost:7860"): self.base_url = base_url def detect_from_file(self, image_path): """从文件检测人脸""" with open(image_path, 'rb') as f: files = {'image': f} response = requests.post(f"{self.base_url}/detect", files=files) return response.json() def detect_from_url(self, image_url): """从URL检测人脸""" data = {'url': image_url} response = requests.post(f"{self.base_url}/detect_url", json=data) return response.json() def batch_detect(self, image_paths): """批量检测（通过队列）""" import redis import json # 连接到Redis队列 redis_client = redis.Redis(host='localhost', port=6379) results = {} for path in image_paths: with open(path, 'rb') as f: image_data = base64.b64encode(f.read()).decode('utf-8') task = { 'image_data': image_data, 'options': {'return_image': False} } # 提交到队列 redis_client.lpush('mogface_tasks', json.dumps(task)) return {"message": "Tasks submitted to queue", "count": len(image_paths)}

方案2：微服务架构如果你需要更高的可用性和扩展性，可以考虑将MogFace部署为微服务：

# docker-compose.scale.yml - 支持水平扩展的配置 version: '3.8' services: redis: image: redis:7-alpine deploy: replicas: 1 mogface-api: image: mogface-api:latest deploy: replicas: 3 # 启动3个实例 resources: limits: memory: 4G environment: - REDIS_HOST=redis depends_on: - redis load-balancer: image: nginx:alpine ports: - "80:80" volumes: - ./nginx.conf:/etc/nginx/nginx.conf depends_on: - mogface-api

6. 总结

通过这篇教程，我们完成了一个完整的MogFace-large人脸检测服务的部署和使用。让我们回顾一下关键要点：

6.1 部署要点回顾

1. 一键部署：使用Docker Compose，只需要一个配置文件就能启动所有服务
2. 完整架构：不仅部署了MogFace模型，还集成了Redis队列服务，支持批量处理
3. 易于使用：提供Web界面，无需编程基础也能快速体验人脸检测
4. 易于扩展：队列架构设计，方便后续增加更多工作节点

6.2 核心价值

MogFace-large作为当前最先进的人脸检测模型之一，在实际应用中表现出色：

• 高准确率：在Wider Face榜单上长期霸榜，检测准确率有保障
• 强鲁棒性：针对各种复杂场景（光线、角度、遮挡）都有良好表现
• 易于部署：通过Docker容器化，避免了复杂的环境配置问题
• 生产就绪：结合Redis队列，能够处理实际生产环境中的批量任务

6.3 下一步建议

如果你已经成功部署并体验了MogFace，可以考虑以下几个方向进一步探索：

1. 性能优化：根据你的硬件配置调整参数，获得更好的性能
2. 功能扩展：在检测基础上增加人脸识别、属性分析等功能
3. 系统集成：将服务集成到你的现有系统中
4. 监控告警：添加对服务的监控，确保稳定运行

人脸检测只是计算机视觉应用的起点，基于准确的人脸检测，你可以构建更多有趣和有用的应用，比如人脸识别系统、表情分析、虚拟试妆、智能相册等等。

获取更多AI镜像

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