misc/onnx_export_guide.md

# YOLO11 PT 转 ONNX 教程

## 一、使用命令行导出

```bash
yolo export model=path/to/model.pt format=onnx imgsz=640 half=False simplify=True
```

常用参数：
- `format=onnx`: 导出为 ONNX 格式
- `imgsz=640`: 输入图像尺寸，需与训练时一致
- `half=False`: FP32 精度；设为 True 为 FP16（需设备支持）
- `simplify=True`: 简化 ONNX 图结构，减小模型体积
- `dynamic=True`: 支持动态 batch 和输入尺寸
- `nms=True`: 将 NMS 内置到模型中
- `device=0`: 指定 GPU 设备号

## 二、使用 Python API 导出

```python
from ultralytics import YOLO

model = YOLO("path/to/model.pt")
model.export(
    format="onnx",
    imgsz=640,
    half=False,
    simplify=True,
    device=0,
    verbose=True
)
```

导出后的 ONNX 文件默认保存在与 PT 文件同级目录下，文件名为 `model.onnx`。

## 三、使用 ONNXRuntime 加载推理

```python
import cv2
import numpy as np
import onnxruntime as ort

sess = ort.InferenceSession("model.onnx", providers=["CUDAExecutionProvider"])
input_name = sess.get_inputs()[0].name
output_name = sess.get_outputs()[0].name

# 预处理
img = cv2.imread("image.jpg")
img = cv2.resize(img, (640, 640))
img = img.astype(np.float32) / 255.0
img = np.transpose(img, (2, 0, 1))
input_tensor = np.expand_dims(img, axis=0)

# 推理
outputs = sess.run([output_name], {input_name: input_tensor})
```


# FQA
## Q1: export_to_onnx 中 imgsz 参数设置为640,意味着推理的时候,输入的图片必须要是640x640大小的吗?

答案：不是必须的。
ONNX模型导出时，imgsz=640 默认会固定输入形状为 1, 3, 640, 640。推理时需要 resize + pad 到 640x640。
但如果导出时加 dynamic=True，可以支持动态尺寸输入。
我需要解释清楚这两点，简洁回答。
不是。分两种情况：
1. 默认导出（静态 shape）：imgsz=640
- ONNX 输入被固定为 [1, 3, 640, 640]
- 推理时 必须 把图片处理成 640×640
- 但原始图片可以是任意尺寸，通过 resize + 等比填充 到 640×640（我代码里已经实现了）
2. 动态 shape 导出：加 dynamic=True
model.export(format="onnx", imgsz=640, dynamic=True)
- ONNX 输入为 [1, 3, ?, ?]
- 推理时可以用任意尺寸输入（如 320×320、800×800）
- 灵活性更高，但推理速度可能略慢
总结：你导出时写的 imgsz=640 只是指定训练/导出的参考尺寸，原始图片不需要是 640×640，推理前会 resize 处理。


## Q2: 默认参数设置

以下是 yolo export 各参数的默认值（来自 default.yaml）：

|参数 |	默认值	| 说明 |
|--- | --- | ---|
|save name	| 自动	| {原文件名}.{格式后缀}，如 yolo11n.pt → yolo11n.onnx|
|nms	| False	| 不把 NMS 内置到模型，需自己后处理|
|simplify	| True	| 默认启用 ONNX 图简化|
|dynamic	| False	| 默认固定输入 shape|
|half	| False	| 默认 FP32 精度|
|batch	| 1	| 导出时固定为 batch=1（与训练默认的16不同）|
|device	| None	| 自动选择（优先 GPU）
|verbose	| False	| 导出时静默输出（与训练默认的True不同）|
|int8	| False	| 不启用 INT8 量化|


所以你这行命令：
yolo export model=page-nano-best-epo50.pt format=onnx imgsz=640 half=False simplify=True
等价于：
- 保存为 page-nano-best-epo50.onnx
- FP32，固定 shape [1,3,640,640]
- 不带 NMS（需要自己后处理）
- 简化 ONNX 图
- 静默输出


## Q3: 建议使用dynamic, nms 参数吗?

dynamic=True:
- 优点：推理时可以用任意尺寸，灵活性高
- 缺点：某些部署环境不支持，推理可能稍慢，某些优化器无法优化
nms=True:
- 优点：模型输出直接就是过滤后的结果，推理代码简单
- 缺点：NMS 参数固化在模型中，不方便调整；某些后处理流程可能更复杂
需要根据用户是用于 ONNXRuntime 推理的场景来分析。
分场景：
dynamic=True：
- ✅ 建议开：你需要同一模型处理不同尺寸的图片
- ❌ 不建议：
  - 固定尺寸推理（如全 640×640）
  - 部署到某些不支持动态 shape 的环境（TensorRT、部分嵌入式）
nms=True：
- ✅ 建议开：
  - 想让推理代码更简单（模型直接输出最终结果）
  - 固定 conf/iou 阈值即可
- ❌ 不建议：
  - 需要频繁调 conf/iou（改了要重新 export）
  - 需要自定义后处理逻辑（如按类别不同阈值）
你当前场景（ONNXRuntime + 自己写后处理代码）：
dynamic=False  # 固定 640x640 性能更好
nms=False      # 你已经自己实现了后处理+NMS
如果未来想简化推理代码，可以重新 export：
yolo export model=xxx.pt format=onnx nms=True conf=0.25 iou=0.45
输出直接是 N x 7 的 [x1,y1,x2,y2,conf,cls_id]，省去后处理。

## Q4: 如何知道目前模型的iou, conf?

这两个参数不在模型里，是你在推理时自己设定的。模型权重里只存网络参数，不存 conf/iou。
但你可以查模型训练时用的默认验证参数：
from ultralytics import YOLO
model = YOLO("models/page-nano-best-epo50.pt")
print(model.model.args)
看 conf 和 iou（或 nms.iou_thres）字段，这是训练验证时用的参考值。
实际建议：
- 用 yolo val 看不同阈值下的 mAP，选平衡点
- 检测任务常用：conf=0.25, iou=0.45（Ultralytics 默认）
- 如果你 export 时用了 nms=True，需要显式指定

## Q5: mAP50-95 偏低是什么情况？

## mAP50-95 < 0.5 的效果判断

**不能一概而论**，需要结合任务难度和模型规模来看。以下是通用参考：

---

## 不同场景下的参考标准

### 通用目标检测（COCO 80类，复杂场景）

| mAP50-95 | 水平 | 代表模型 |
|----------|------|---------|
| > 0.55 | 优秀 | YOLOv8x、YOLOv10x |
| 0.45 ~ 0.55 | 良好 | YOLOv8m、YOLOv8l |
| 0.35 ~ 0.45 | 中等 | YOLOv8s、YOLOv8n |
| < 0.35 | 较差 | 小模型/训练不足 |

> 在 COCO 这种**80类、复杂场景**的基准上，0.5 已经是不错的水平了，YOLOv8s 也才 0.44 左右。

### 简单/少类别任务（工业质检、特定场景）

| mAP50-95 | 水平 |
|----------|------|
| > 0.8 | 优秀，可上线 |
| 0.6 ~ 0.8 | 良好，基本可用 |
| 0.4 ~ 0.6 | 中等，需要优化 |
| < 0.4 | 较差，不建议上线 |

> 类别少、场景简单时，0.5 只能算**及格线**，通常还有较大提升空间。

---

## 0.5 以下意味着什么

1. **定位精度不足**：mAP50-95 对框的位置很敏感，低于 0.5 说明很多框"检测到了但框得不准"
2. **可能存在的问题**：
   - 标注框质量差（标注本身就不准）
   - 小目标多（小目标 IoU 天然低）
   - 训练不充分（epoch 不够、数据量少）
   - 模型太小（容量不足）
   - 锚框不匹配

---

## 怎么判断能不能用

看你的**业务需求**：

- **只需要"有没有"**（如安防告警、粗略计数）：看 mAP50，如果 mAP50 高（>0.8），即使 mAP50-95 低也能用
- **需要精确位置**（如医疗影像、工业测量、自动驾驶）：mAP50-95 < 0.5 **不够用**，需要继续优化
- **需要区分密集目标**：mAP50-95 低可能导致框偏移，重叠目标分不清

---

## 提升 mAP50-95 的方向

1. **提高标注质量**：检查标注框是否紧密贴合目标
2. **增加训练轮次**：通常 300 epoch 比 100 epoch 定位更准
3. **用更大的模型**：m/l/x 版本定位精度更高
4. **数据增强**：Mosaic、MixUp 有助于定位
5. **调整锚框**：用 `autoanchor=True` 自动计算
6. **多尺度训练**：`imgsz` 设大一些（如 1280）

**总结**：如果是 COCO 级别的复杂任务，0.5 以下属正常中等水平；如果是简单少类别任务，0.5 以下说明还有明显优化空间。关键看你的 mAP50 是多少——如果 mAP50 高但 mAP50-95 低，问题主要在**定位精度**。