YOLO12 WebUI 目标检测快速入门教程

3. WebUI 实操：两种上传方式 + 结果解读

界面无任何菜单栏、设置页或复杂按钮——设计哲学就是'只做一件事，并做到最好'：上传图片，给出检测结果。

3.1 方式一：点击上传（适合新手）

1. 鼠标点击虚线框区域（出现文件选择对话框）
2. 从本地电脑选取一张 JPG 或 PNG 图片（建议含人物、车辆、宠物等常见物体）
3. 点击'打开'，界面自动开始上传并检测

⏳ 检测耗时取决于图片分辨率与服务器性能，YOLO12-nano 在普通 GPU（如 RTX 3060）上平均响应 < 0.3 秒；纯 CPU 环境约 1–2 秒。

3.2 方式二：拖拽上传（效率翻倍）

1. 打开你的文件管理器，找到一张测试图
2. 用鼠标左键按住图片文件，直接拖入网页虚线框内
3. 松开鼠标，上传自动触发，无需点击确认

小技巧：可一次拖入多张图（当前版本仅处理首张，后续支持批量将在更新中上线）

3.3 看懂检测结果：三个关键信息

检测完成后，原图上方将叠加彩色边界框，右侧同步生成结构化列表。你需要关注以下三部分：

• 彩色边界框：每种物体类别对应唯一颜色（如 person=蓝色，car=绿色，dog=橙色），框体粗细统一，不遮挡主体
• 类别标签：每个框正上方显示文字，如 person、bottle、laptop，字体清晰可读
• 置信度列表：界面右侧滚动列表，逐条列出：
  • 物体名称（class_name）
  • 置信分数（confidence，保留小数点后 4 位，如 0.9732）
  • 坐标信息（bbox：[x_center, y_center, width, height]，单位为像素）

举个真实例子：上传一张办公室照片后，你可能看到：
person — 0.9823 — [420.5, 285.1, 112.3, 265.7]
表示画面中心坐标 (420.5, 285.1) 处检测到一人，框宽 112.3 像素、高 265.7 像素，模型有 98.23% 把握这是人。

4. 进阶操作：换模型、查日志、调 API

当你熟悉基础检测后，这几项操作能帮你深度掌控服务。

4.1 切换更高精度模型（30 秒完成）

YOLO12 提供 5 档模型，按精度与速度平衡划分。nano 最快，x 最准。切换只需两步：

1. 编辑配置文件：

nano /root/yolo12/config.py 

2. 修改 MODEL_NAME 行（取消注释并保留一行）：

MODEL_NAME = "yolov12x.pt" # ← 改为此行，删除其他 MODEL_NAME 行 

3. 重启服务：

supervisorctl restart yolo12 

重启后再次访问 http://<IP>:8001，新模型即生效。检测时间略有增加，但小物体识别率显著提升（如远处的自行车轮、空中的无人机）。

4.2 查看运行日志（定位问题第一现场）

所有日志集中存于 /root/yolo12/logs/，日常排查优先看这三类：

• app.log：记录每次请求的图片名、检测耗时、物体数量
• error.log：仅写入异常（如图片损坏、内存不足、CUDA 错误）
• supervisor.log：服务启停、崩溃、资源超限等系统级事件

快速查看最近 20 行应用日志：

tail -20 /root/yolo12/logs/app.log 

典型成功日志：

2025-04-12 10:23:45 INFO Uploaded: office.jpg → detected 3 objects in 0.28s 

典型错误日志：

2025-04-12 10:25:11 ERROR Failed to load image: OSError('Unsupported image format') 

4.3 调用 API 自动化集成（5 行代码接入）

WebUI 是前端，底层是标准 FastAPI 接口。你可以用任意语言调用，实现批量检测、定时任务或嵌入自有系统。

检测单张图的完整 curl 示例：

curl -F "file=@/path/to/test.jpg" http://localhost:8001/predict 

Python requests 版本（更易集成）：

import requests
url = "http://localhost:8001/predict"
with open("test.jpg", "rb") as f:
    files = {"file": f}
    res = requests.post(url, files=files)
    print(res.json()) # 输出同文档示例：含 filename、detections、count 

注意事项：

• 上传字段名必须为 file（大小写敏感）
• 返回 JSON 中 bbox 为 [x_center, y_center, width, height]，非左上角坐标
• 单次请求仅支持一张图，批量需循环调用

5. 常见问题速查：90% 的问题这里都有答案

我们整理了用户高频遇到的 5 类问题，按发生概率排序，覆盖从入门到进阶的全部盲区。

5.1 图片上传后无反应？先看这三点

• 检查浏览器控制台（F12 → Console）是否有 Failed to fetch 报错 → 若有，说明前端无法连接后端，确认 http://<IP>:8001 可访问且端口开放
• 检查图片格式是否为 JPG/PNG（不支持 WEBP、GIF 动图）
• 检查图片大小是否超过 10MB（镜像默认限制，如需放宽可修改 app.py 中 max_upload_size）

5.2 检测结果全是'person'，其他物体没框出来？

这通常不是模型问题，而是：

• 图片中目标过小（< 32×32 像素），YOLO12-nano 对微小物体敏感度有限 → 尝试放大图片或换 yolov12s.pt
• 物体被严重遮挡或光照极差（如逆光剪影、夜间低照度）→ YOLO12 未针对极端场景优化，建议预处理增强对比度
• 物体不属于 COCO 80 类（如'电饭煲''游戏手柄''快递盒'）→ 当前模型不支持自定义类别，需微调训练

5.3 如何保存带框的检测结果图？

WebUI 界面暂不提供'下载结果图'按钮，但你可以：

• 右键点击检测后图像 → '另存为'（部分浏览器支持保存 Canvas 渲染图）
• 更可靠方式：调用 API 获取 detections，用 OpenCV 或 PIL 自行绘制并保存（附简易代码）：

from PIL import Image, ImageDraw, ImageFont
import json

# 假设 res.json() 已获取
data = res.json()
img = Image.open("test.jpg")
draw = ImageDraw.Draw(img)
for det in data["detections"]:
    x, y, w, h = det["bbox"]
    # 转换为中心点→左上角坐标
    left = x - w/2
    top = y - h/2
    draw.rectangle([left, top, left+w, top+h], outline="red", width=3)
    draw.text((left, top-20), det["class_name"], fill="red")
img.save("result.jpg")

5.4 想在手机上用？可行但有前提

• 支持：Chrome / Safari 浏览器访问，上传相册图片正常
• 注意：iOS Safari 对大图上传有限制（常截断），建议压缩至 < 2MB 后上传
• 不支持：微信内置浏览器（禁用 file input）、QQ 浏览器（部分版本拦截 Canvas）

5.5 服务启动失败，supervisor 日志显示'torch not found'

说明 Conda 环境未正确激活。手动进入环境再启动：

source /opt/conda/bin/activate torch28
supervisorctl restart yolo12 

或检查 Supervisor 配置中 environment 是否指向正确路径（/root/yolo12/supervisord.conf）。

6. 总结：从'能用'到'用好'的关键一步

YOLO12 WebUI 的价值，不在于它有多复杂，而在于它把目标检测这件事，真正交还给了使用者本身。你不需要知道什么是注意力头、什么是特征金字塔，也不必纠结 NMS 阈值该设 0.45 还是 0.5；你只需要一张图、一个浏览器、一分钟等待，就能看见算法如何理解世界。

本文带你走完了全部关键路径：

• 服务一键启停（supervisorctl）
• 界面两种上传（点击/拖拽）
• 结果三要素解读（框、名、分）
• 模型自由切换（n→x 全档位）
• 日志精准定位（app.log 为主）
• API 快速集成（5 行 Python）

下一步，你可以尝试：

• 用手机拍一张街景图，检测实时交通参与者
• 上传产品包装图，验证'bottle''box'识别稳定性
• 写个脚本遍历文件夹，批量生成检测报告 CSV

技术的意义，从来不是堆砌参数，而是让能力触手可及。YOLO12 WebUI 正是这样一座桥——桥这边是好奇与需求，桥那边，是看得见、摸得着的智能。