MogFace 人脸检测 WebUI 快速部署与使用指南

1. 上传你的图片

• 在界面中央，你会看到一个很大的上传区域，上面可能写着'点击上传图片或拖拽到这里'。
• 方法 A（点击）：直接点击这个区域，会弹出文件选择窗口，找到你电脑里想检测的图片。
• 方法 B（拖拽）：更简单，直接把图片文件从电脑文件夹拖到这个上传区域里。
• 支持常见的图片格式：.jpg, .jpeg, .png, .bmp, .webp。

2. 调整检测参数（可选） 上传图片后，旁边通常会有一些参数可以调整。如果你是第一次用，完全可以跳过这步，用默认设置就好。了解它们可以让你更灵活：

• 置信度阈值：这个值越高，检测标准越严格。比如设为 0.8，那么模型只有超过 80% 把握认为是人脸的区域才会被框出来。新手建议保持默认的 0.5，这样不容易漏检。
• 显示关键点：勾选后，会在检测到的人脸上标记出 5 个点（眼睛、鼻子、嘴角）。
• 显示置信度：勾选后，每个人脸框旁边会显示一个分数，就是这个'人脸'的把握有多大。
• 框线颜色：可以换个颜色，让框更醒目。

3. 开始检测并查看结果

• 点击页面上明显的'开始检测'或'检测'按钮。
• 等待几秒钟（速度取决于图片大小和服务器性能），右侧就会显示出结果。
• 你会看到：
  • 原图上，所有检测到的人脸都被彩色框框了出来。
  • 图片下方或侧边，会显示检测到的人脸数量。
  • 如果勾选了置信度，每个人脸框上会有分数（例如 0.95，代表 95% 的把握）。

4. 保存你的结果

• 保存图片：在结果图片上点击右键，选择'图片另存为'，就可以把带检测框的图片保存到本地。
• 复制数据：对于开发者，界面可能还会提供一个'JSON 数据'的文本框，里面包含了所有人脸的坐标、关键点等详细信息，可以直接复制用于编程。

3.2 高效功能：批量图片检测

如果你有很多图片需要处理，一张张上传太麻烦。批量检测功能就是为你准备的。

1. 在 Web 界面上找到并点击'批量检测'标签页。
2. 点击上传区域，这次你可以按住 Ctrl 键（Windows）或 Command 键（Mac），同时选择多张图片。或者直接把一个包含多张图片的文件夹拖进去。
3. 点击'批量检测'按钮。
4. 系统会依次处理所有图片，并以缩略图列表或可切换的方式展示每张图片的检测结果。你可以逐一检查，也可以批量下载结果。

3.3 开发者接口：API 调用说明

除了好用的 Web 界面，这个服务还提供了标准的 API 接口（端口 8080），方便你集成到自己的程序、网站或 APP 里。这里给出一个最常用的 Python 调用示例，你几乎可以直接复制使用。

import requests

# 1. 设置服务地址（将 <服务器 IP> 替换成你的实际 IP）
api_url = "http://<服务器 IP>:8080/detect"

# 2. 准备要检测的图片
image_file_path = "你的图片.jpg"  # 替换成你的图片路径

# 3. 发送检测请求
with open(image_file_path, 'rb') as img_file:
    # 以表单文件的形式上传图片
    files = {'image': img_file}
    response = requests.post(api_url, files=files)

# 4. 处理返回结果
if response.status_code == 200:
    result = response.json()
    if result.get('success'):
        faces = result['data']['faces']
        print(f"检测成功！共发现 {len(faces)} 个人脸。")
        for idx, face in enumerate(faces):
            # 人脸框坐标 [左上角 x, 左上角 y, 右下角 x, 右下角 y]
            bbox = face['bbox']
            # 置信度
            confidence = face['confidence']
            print(f"人脸 {idx+1}: 位置 {bbox}, 置信度 {confidence:.1%}")
            # 如果需要，还可以获取 5 个关键点坐标
            # landmarks = face['landmarks']  # 顺序是：[左眼，右眼，鼻尖，左嘴角，右嘴角]
    else:
        print("检测失败：", result.get('message'))
else:
    print(f"请求失败，状态码：{response.status_code}")

这段代码做了什么事呢？它读取一张本地图片，发送到 MogFace 服务，然后打印出检测到的每个人脸的位置和可信度。你可以把它嵌入到你的照片管理软件、门禁系统或者任何需要识别人脸的程序里。

4. 常见问题与排错指南

第一次使用，难免会遇到一些小问题。别担心，大部分问题都能快速解决。

4.1 问题一：Web 页面打不开（显示无法连接）

这是最常见的问题，原因通常是网络或服务没启动。

检查清单：

1. 服务是否在运行？ 如果你有服务器命令行权限，可以登录后运行 ./scripts/service_ctl.sh status 查看状态。如果不在运行，尝试 ./scripts/service_ctl.sh restart。
2. IP 地址和端口对吗？ 确认你浏览器里输入的 IP 和端口（默认 7860）是否正确。云服务器要使用公网 IP。
3. 防火墙/安全组放行了吗？ 这是云服务器上最可能的原因。你需要登录云服务器控制台，找到'安全组'或'防火墙'设置，添加一条规则，允许 TCP 协议的 7860 端口入站。
4. 本地运行时：检查 Docker 容器是否运行 (docker ps)，并确认端口映射正确。

4.2 问题二：检测不到人脸或漏检

上传了明明有人脸的图片，却一个框都没出来。

可能原因和解决办法：

• 人脸太小或太模糊：模型对极小（小于图片高度 1/10）或高度模糊的人脸检测能力会下降。尝试使用更清晰、人脸占比更大的图片。
• 光线极端：过暗或过曝（强光导致面部特征丢失）的图片会影响检测。尽量使用光线正常的图片。
• 姿态过于极端：虽然 MogFace 对侧脸有很好支持，但如果完全是后脑勺或者被完全遮挡，自然无法检测。
• 置信度阈值过高：如果你手动调高了'置信度阈值'（比如调到 0.9），可以把它调回默认的 0.5 或更低（如 0.3），以放宽检测标准。

4.3 问题三：检测结果不准（框的位置歪了）

框是出来了，但没完全套住人脸，或者框到了头发上。

• 这是正常现象：在极端角度、严重遮挡下，边界框的精度可能会略有下降。对于绝大多数正面、清晰的人脸，框的位置都是非常精准的。
• 关注关键点：如果开启了关键点显示，你会发现即使框略有偏差，眼睛、鼻子、嘴巴这 5 个关键点的位置通常是非常准的，这对于很多人脸应用来说已经足够了。

4.4 问题四：如何检测视频？

当前版本的 WebUI 主要针对图片设计。如果你想检测视频中的人脸，可以采用'抽帧'的方法：

1. 使用视频处理工具（如 FFmpeg）将视频按每秒若干帧（例如每秒 1 帧）提取成一系列图片。

ffmpeg -i 你的视频.mp4 -vf "fps=1" output_frame_%04d.jpg 

2. 然后使用本服务的批量检测功能，上传这些提取出来的图片帧进行处理。这虽然不是实时检测，但对于视频内容分析、人脸统计等场景完全够用。

5. 总结

让我们回顾一下今天学到的东西。MogFace 人脸检测 WebUI 将一个顶尖的学术模型，变成了一个人人可用的实用工具。通过这篇教程，你掌握了：

1. 极速部署：无论是在云平台一键部署，还是本地 Docker 运行，都能在 5 分钟内让服务跑起来。
2. 零代码使用：通过直观的 Web 界面，上传图片、点击按钮，就能完成高精度的人脸检测，并保存带框的结果图。
3. 批量处理与集成：利用批量检测功能处理大量图片，或者通过简单的 Python 代码调用 API，将人脸检测能力集成到你自己的项目中。
4. 问题排查：遇到页面打不开、检测不到人脸等常见问题，你知道该从哪里入手解决。

这个工具的强大之处在于它平衡了'能力'与'易用性'。你不需要是机器学习专家，也能享受到最前沿的人脸检测技术带来的便利。无论是整理家庭相册、开发一款有趣的社交应用，还是构建更严肃的门禁考勤系统，MogFace WebUI 都能成为一个可靠的基础组件。

现在，你已经具备了快速上手的能力。下一步，就是真正去部署它，上传你的第一张图片，亲眼看看它如何从复杂的画面中，精准地找到每一张面孔。实践是学习的最好方式，开始你的第一次人脸检测吧！