在命令行列出一堆参数只为框出图片里的物体，很多人都被劝退过。YOLO12 WebUI 把这事简化了：打开浏览器，上传图片，等一会儿结果就出来。它能标注 80 类常见物体——从桌上的苹果、手机，到窗外的汽车、行人，背后跑的是 2025 年初发布的 YOLO12-nano 模型，由纽约州立大学布法罗分校与中国科学院大学团队联合研发，以注意力机制为核心，响应毫秒级。
你可以随时切换更大更准的模型（s/m/l/x），查看日志排查问题，或者通过 API 接入自己的系统。下面走一遍从零到看到检测结果的整个过程。
部署服务
YOLO12 WebUI 镜像已经预置好运行环境，不用编译源码或折腾依赖。
检查服务状态
登录 Linux 服务器（支持 Ubuntu 22.04 / CentOS 7+），看看服务是不是已经在跑：
supervisorctl status yolo12
正常输出类似：
yolo12 RUNNING pid 1234, uptime 0:05:23
如果显示 FATAL 或 STOPPED，启动它：
supervisorctl start yolo12
首次启动可能需要 10～20 秒加载模型。如果一直卡在 STARTING，用 supervisorctl tail yolo12 看日志定位原因。
访问地址
服务默认监听端口 8001。浏览器里输入：
http://<你的服务器 IP>:8001
比如 IP 是 192.168.1.100，就访问 http://192.168.1.100:8001。打开后是一个干净的界面，中央有带虚线边框的上传区。
健康检查（可选）
在终端执行：
curl http://localhost:8001/health
预期返回：
{"status":"ok","model":"yolov12n.pt"}
如果返回 Connection refused，检查：
- 是否在服务器本机执行
- 端口
8001是否被防火墙挡了（ufw status或firewall-cmd --list-ports） - Supervisor 本身是不是在运行（
systemctl status supervisor）
在 WebUI 里做检测
界面没有菜单栏和设置页，就是上传图片、看结果。
点击上传
- 点虚线框区域，弹出文件选择对话框
- 选一张 JPG 或 PNG 图片（建议包含人物、车辆、宠物等常见物体）
- 点'打开'，上传和检测自动开始
YOLO12-nano 在普通 GPU（如 RTX 3060）上平均响应不到 0.3 秒；纯 CPU 环境大概 1～2 秒。
拖拽上传
直接把图片文件从文件管理器拖到网页虚线框里，松手就行。当前版本只处理第一张图，后续会支持批量。
看懂结果
检测完，原图上会叠加彩色边界框，右边同步生成结构化列表。你主要看三样东西：
- 彩色边界框：不同类别有固定颜色（比如 person 蓝色、car 绿色、dog 橙色），框体粗细统一。
- 类别标签：每个框上方都有文字，如
person、bottle。 - 置信度列表：右侧滚动列表逐条给出物体名、置信分数（保留 4 位小数，如 0.9732）和坐标
[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% 的把握。
进阶操作
换更高精度的模型
YOLO12 有 5 档模型，nano 最快，x 最准。切换步骤：
- 编辑配置文件：
nano /root/yolo12/config.py
- 修改
MODEL_NAME行，比如改成：
MODEL_NAME = "yolov12x.pt"
确保只有一行生效，删掉其他 MODEL_NAME 行。
- 重启服务：
supervisorctl restart yolo12
模型参数对比：
| 模型 | CPU 推理速度 | COCO [email protected] | 适用场景 |
|---|---|---|---|
| yolov12n.pt | ~18 FPS | 42.1 | 实时监控、边缘设备 |
| yolov12s.pt | ~12 FPS | 46.7 | 通用检测、中等算力 |
| yolov12m.pt | ~8 FPS | 50.3 | 精准识别、科研验证 |
| yolov12l.pt | ~5 FPS | 52.9 | 高要求工业质检 |
| yolov12x.pt | ~3 FPS | 54.6 | 学术研究、极限精度 |
查看日志
日志都放在 /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')
调用 API
WebUI 底层是标准 FastAPI 接口，你可以用任何语言调用。
检测单张图的 curl 示例：
curl -F "file=@/path/to/test.jpg" http://localhost:8001/predict
Python 版本：
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())
几点注意：
- 上传字段名必须是
file（区分大小写） - 返回的
bbox是中心点坐标加宽高，不是左上角坐标 - 单次请求只支持一张图，批量就循环调用
常见问题
图片上传后没反应
- 打开浏览器控制台（F12 → Console），看有没有
Failed to fetch报错。有的话说明前端连不上后端，确认http://<IP>:8001能访问且端口开放。 - 图片格式只支持 JPG/PNG（WEBP 和 GIF 动图不行）。
- 默认文件大小限制 10MB，需要放宽可以改
app.py里的max_upload_size。
检测结果全是'person'，其他物体没框出来
- 目标太小（小于 32×32 像素），nano 模型对小物体敏感度有限，可以试试放大图片或换成
yolov12s.pt。 - 严重遮挡或光照极差（逆光剪影、夜间低照度）——YOLO12 没针对极端场景优化，预处理一下增强对比度会好些。
- 物体不在 COCO 80 类里（比如电饭煲、游戏手柄），当前模型不支持自定义类别，得自己微调训练。
想保存带框的结果图
界面没有'下载结果图'按钮，但你可以：
- 右键点检测后的图像 → '另存为'（部分浏览器支持保存 Canvas 渲染图）
- 更可靠的办法是调 API 拿
detections，然后用 OpenCV 或 PIL 自己画框保存。简单示例：
from PIL import Image, ImageDraw
import 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")
想在手机上用
Chrome / Safari 访问没问题，能上传相册图片。但 iOS Safari 对大图上传有限制，建议先压到 2MB 以下。微信内置浏览器和部分版本 QQ 浏览器不支持。
服务启动失败，supervisor 日志显示'torch not found'
这说明 Conda 环境没激活。手动激活再重启：
source /opt/conda/bin/activate torch28
supervisorctl restart yolo12
或者检查 Supervisor 配置文件里 environment 是否指向了正确路径（/root/yolo12/supervisord.conf）。
上面这些步骤走完，基本够日常使用了。下一步你可以试试拿手机拍一张街景图看看交通参与者识别，或者写个脚本批量处理图片导出 CSV。
