主题
推理输入参数说明
本文说明 15 个 YOLO 推理接口（YoloDetect* / YoloClassify* / YoloSegment* / YoloPose* / YoloObb*）的入参含义、取值范围与调参建议。返回 JSON 见 推理结果JSON说明；持久化默认值见 ModelInfo与ModelConfig说明 中的 YoloSetModelConfig。
参数与任务对照
| 参数 | Detect | Classify | Segment | Pose | Obb |
|---|---|---|---|---|---|
x1,y1,x2,y2 | 屏幕版 ✓ | 屏幕版 ✓ | 屏幕版 ✓ | 屏幕版 ✓ | 屏幕版 ✓ |
imagePtr | Ptr 版 ✓ | Ptr 版 ✓ | Ptr 版 ✓ | Ptr 版 ✓ | Ptr 版 ✓ |
imagePath | File 版 ✓ | File 版 ✓ | File 版 ✓ | File 版 ✓ | File 版 ✓ |
modelHandle | ✓ | ✓ | ✓ | ✓ | ✓ |
classes | ✓ | — | — | — | — |
confidence | ✓ | — | ✓ | ✓ | ✓ |
iou | ✓ | — | ✓ | ✓ | ✓ |
maxDetections | ✓ | — | — | — | — |
topK | — | ✓ | — | — | — |
公共参数
ola
OLAPlug 对象指针，由 CreateCOLAPlugInterFace 创建。所有 YOLO 接口第一个参数。
modelHandle
加载模型 返回的句柄。任务类型必须与接口一致（如对 Classify 模型调用 YoloDetect 会失败）。用完须 YoloReleaseModel。
屏幕区域 x1, y1, x2, y2（仅屏幕版）
| 项 | 说明 |
|---|---|
| 含义 | 截取屏幕上的矩形区域再送入模型；坐标为屏幕绝对坐标，原点左上角 |
| 约定 | (x1,y1) 左上角，(x2,y2) 右下角；须满足 x2 > x1 且 y2 > y1 |
| 输出坐标 | 推理结果 JSON 中的 Center / Vertices 等同为屏幕坐标，可直接用于 MoveTo 等 |
| 建议 | 尽量只截目标可能出现的区域，减小分辨率可明显降低 LatencyMs |
imagePtr（仅 FromPtr 版）
LoadImage 等返回的图像句柄（内部为 OpenCV Mat）。推理结果坐标相对该图左上角。推理后须自行 FreeImagePtr（与 JSON 指针释放无关）。
imagePath（仅 FromFile 版）
磁盘图片路径（支持常见格式如 png、jpg、bmp）。坐标相对整张图片。插件内部读图推理，无需先 LoadImage。
Detect 专用
classes（类别过滤）
| 项 | 说明 |
|---|---|
| 格式 | 竖线 ` |
| 名称 vs ID | 加载了 names 标签文件（或加密包内嵌类别表）时写类别名；未加载时写 class_id 数字字符串，如 0|2 |
| 行为 | 与模型类别表求交集；无交集时不做推理，返回 ClassFilterSkipped: true 且 Regions: []（见 推理结果JSON说明） |
| 对比 ModelConfig | YoloSetModelConfig 的 Classes / ClassesFilter 语义类似，但 classes 以本次 API 传入为准，便于脚本按场景切换 |
maxDetections（最大检测数）
| 项 | 说明 |
|---|---|
| 含义 | NMS 之后最多保留的检测框数量上限 |
| 作用 | 密集场景（人群、虫群）防止返回成百上千框；超出上限时保留 Score 最高 的若干条 |
| 建议 | 一般 50~300；UI 只需一个目标时可设为 1~10 |
| 对比 ModelConfig | 对应 MaxDetections；单次调用传入值覆盖当次推理 |
Classify 专用
topK（Top-K 分类）
| 项 | 说明 |
|---|---|
| 含义 | 返回置信度最高的前 K 个类别（不是检测框数量） |
| 输出 | JSON 中 RegionCount ≤ topK；Regions[i].Rank 为 0…K-1（0 为 Top-1）；顶层 TopClassName / TopScore 与 Regions[0] 一致 |
| 取值 | 建议 1~10；topK=1 时仅一条结果，适合「判断当前画面是哪一种状态」 |
| 与 confidence | Classify 无 confidence / iou 参数；低分类别仍会按分数排序返回，若需过滤可在脚本中判断 Score |
| 对比 ModelConfig | 对应 TopK；以 API 参数为准 |
示例：topK=3 时可能得到 tench(0.92)、goldfish(0.05)、shark(0.02) 三条 Region。
检测类共用（Detect / Segment / Pose / Obb）
confidence（置信度阈值）
| 项 | 说明 |
|---|---|
| 范围 | 0.0 ~ 1.0 |
| 含义 | 模型输出的每个候选（框或实例）都有一个 Score；Score < confidence 的候选在 NMS 之前即丢弃，不会进入最终结果 |
| 调参 | 提高 → 更少框、更少误检、更多漏检；降低 → 更多框、更易误检。常见起点 0.25~0.5（与 Ultralytics 默认接近） |
| 任务差异 | Segment / Pose 在框阈值外还有掩码/关键点；框被滤掉则对应实例整个不出现 |
iou（NMS IoU 阈值）
| 项 | 说明 |
|---|---|
| 范围 | 0.0 ~ 1.0 |
| 全称 | Non-Maximum Suppression 使用的 Intersection over Union（交并比） 阈值 |
| 作用 | 同一类多个候选框往往重叠。NMS 按 Score 从高到低保留框；当两个框 IoU > iou 时，认为描述同一目标，抑制（删除）得分较低的那个。用于去除重复框，而不是判断「是否为同一类」 |
| IoU 直观理解 | 两框重叠越多，IoU 越接近 1。iou=0.5 表示重叠面积超过两框并集 50% 即视为重复 |
| 调参 | 降低 iou（如 0.3）→ 更容易判定为重复 → 框更少，相邻近目标可能被误删；提高 iou（如 0.7）→ 允许更多重叠框共存 → 密集小目标更易留下。常用 0.45~0.7，默认约 0.45 |
| 适用任务 | Detect、Segment、Pose、Obb 均参与框级 NMS；Classify 无此参数 |
| 对比 ModelConfig | 对应 IouThreshold；单次 API 传入优先 |
示意（同一目标两个重叠框，得分 B > A）：
IoU(A,B) > iou → 只保留 B，丢弃 A
IoU(A,B) ≤ iou → A、B 都保留（可能是两个相邻目标）与 YoloSetModelConfig 的关系
| 方式 | 说明 |
|---|---|
| 每次 API 传参 | 适合脚本里按场景临时改阈值；当次调用以 API 参数为准 |
YoloSetModelConfig | 写入句柄默认值，减少重复传参；字段名 Confidence、IouThreshold、MaxDetections、TopK、Classes 等与上表对应 |
YoloSetModelConfigByKey | 单键写入，等价于 YoloSetModelConfig({"key": value}) |
| 注意 | 未调用过 YoloSetModelConfig 时，仅 API 显式参数生效；Detect 的 classes 仅 API 有，Config 里是 Classes / ClassesFilter |
推荐起步值
| 场景 | confidence | iou | 其他 |
|---|---|---|---|
| 游戏/UI 单目标 | 0.5~0.6 | 0.45 | maxDetections=10，classes 限定目标名 |
| 通用 COCO 检测 | 0.25~0.5 | 0.45~0.7 | maxDetections=100 |
| 密集小目标 | 0.2~0.35 | 0.5~0.65 | 适当提高 maxDetections |
| 图像分类 | — | — | topK=1 或 3 |
| 姿态 / 分割 | 0.4~0.5 | 0.45~0.6 | 与 Detect 类似 |
最终以验证集或实机画面为准；可先固定 iou=0.45，只扫 confidence。
相关文档
- 推理结果 JSON 说明
- YOLO 模块总览
- YOLO 索引 — 全部推理 API 链接