OLA 文档中心

主题

2026-06-25

ModelInfo 与 ModelConfig 说明 ​

YOLO 模块将 模型元数据 与 推理调参 拆分为两个接口，均返回 PascalCase JSON，须 FreeStringPtr 释放。

| 接口 | 用途 |

|------|------|

| YoloGetModelInfo / YoloListModels | 模型路径、输入尺寸、类别表、EP、任务类型等 |

| YoloGetModelConfig / YoloSetModelConfig / YoloSetModelConfigByKey | 置信度、NMS、TopK、只保留指定类别等 |

JSON 键使用 PascalCase（大小写不敏感）。规则见 JSON配置解析约定。

ModelInfo 主要字段 ​

| 字段 | 说明 |

|------|------|

| Success | 查询是否成功 |

| ModelHandle | 模型句柄 |

| ModelPath | 模型文件路径 |

| BinPath | NCNN 时 .bin 路径（有则输出） |

| LabelsPath | 类别名文件路径 |

| ModelType | Onnx / Ncnn / Trt |

| ModelTypeCode | 0 Engine / 1 ONNX / 2 NCNN |

| InferenceType | Detect / Classify / Segment / Pose / Obb |

| InferenceTypeCode | 0–4，与加载 API 的 inferenceType 一致 |

| InputWidth / InputHeight | 模型输入尺寸 |

| DeviceIndex | 加载时请求的设备索引（-1=CPU） |

| InferenceDevice | 展示用 CPU / GPU0… |

| ClassNameCount / ClassNames | 类别数量与名称表 |

| ExecutionProvider | 运行时 EP 名称 |

| AvailableProviders | 可用 EP 列表 |

| Active / Loaded | 运行时状态 |

推理结果 JSON 使用 TaskType；ModelInfo 使用 InferenceType（语义相同，命名区分用途）。

ModelConfig 字段（Set / Get 共用） ​

Set 时未出现的键保持不变。

| 字段 | 类型 | 说明 |

|------|------|------|

| Confidence | number | 置信度阈值 |

| ConfThreshold | number | 置信度阈值别名 |

| ScoreThreshold | number | 分数阈值 |

| Iou | number | IoU 阈值 |

| IouThreshold | number | NMS IoU 阈值 |

| NmsThreshold | number | NMS 阈值 |

| MaxDetections | int | 最大检测数 |

| TopK | int | Top-K（Classify） |

| NumClasses | int | 类别数 |

| KeypointCount | int | 关键点数 |

| ClassAwareNms | bool | 分类感知 NMS |

| MaskFormat | string | 掩码格式 |

| IncludeMasks | bool | 是否输出掩码 |

| Classes | array | 只保留列表中的类别，其余类别检测框丢弃 |

| ClassesFilter | array | Classes 别名，语义相同 |

| RegionSortMode | int | 检测结果的排列顺序，取值 0~4，见下表 |

RegionSortMode 用来控制单次推理返回的 Regions 数组里，各目标谁先谁后。

  • 可通过 YoloSetModelConfig 给当前模型单独设置。
  • 也可通过 SetConfig 的 YoloRegionSortMode 设置全局默认值。
  • 全局默认 0。

配置谁说了算（优先级） ​

情况实际使用的排序
模型从未设置过 RegionSortMode跟随全局 YoloRegionSortMode；改全局后，该模型立即用新值
模型已经设置过 RegionSortMode始终用模型上的值；之后改全局，不影响这个模型
模型显式设为 0固定用模式 0，不会再跟随全局（即使全局改成 3，仍用 0）
想让某模型重新跟全局走仅改全局不够，需清除该模型上的 RegionSortMode（或重新加载模型）

举例：模型 A 设 RegionSortMode=4（从上到下），全局仍是 0。此时把全局改成 3（从左到右）——模型 A 仍按 4 排；其他没单独设过的模型 改为按 3 排。

值说明具体怎么排
0默认（推荐）与旧版一致：按置信度从高到低，顺序与去重合并（NMS）后相同
1同分看横坐标先按置信度从高到低；置信度一样时，中心点 x 越小越靠前
2同分看纵坐标先按置信度从高到低；置信度一样时，y 越小越靠前，y 还一样再比 x
3从左到右先按中心点 x 从小到大；x 一样时，置信度高的靠前
4从上到下先按中心点 y 从小到大；y 一样再比 x；都还一样时，置信度高的靠前

坐标怎么取：优先用 Center 的中心点；没有 Center 时，用 Vertices 里最小的 x、y。

适用范围：仅 目标检测、实例分割、姿态估计、旋转框检测 四类任务的 Regions。图像分类仍按 TopK 与 Rank 排列，不受本项影响。

对识别与性能的影响 ​

识别结果：排序只改变 Regions 数组里各条记录的先后顺序，不会改变检测到的目标数量、置信度、坐标、类别等任何识别内容。换一种排序模式，识别准不准、检没检到，与模式 0 完全相同。

推理耗时：排序发生在模型推理完成之后，仅在组装对外 JSON 时对少量结果做排列。

  • 模式 0（默认）：直接沿用去重合并后的顺序，几乎无额外开销。
  • 模式 1~4：在 CPU 上对 Regions 排序，数量通常不超过 MaxDetections（默认 100），耗时一般为微秒级，相比返回 JSON 里的 LatencyMs（多为毫秒级）可忽略不计，且不计入 LatencyMs（该字段在排序之前已统计完毕）。

选用建议：按业务需要选择即可（例如脚本要「从左到右点第一个目标」用模式 3）；不必为性能担心，也不必为「会不会检更准」而纠结排序模式。

有效字段因 InferenceType 而异（未设置的键可能不出现）。与推理 API 参数对应关系见 推理输入参数说明。

未调用过 YoloSetModelConfig 时，YoloGetModelConfig 可能仅返回 {"Success":true}。

示例 ​

YoloGetModelInfo

json

{

  "Success": true,

  "ModelHandle": 1000,

  "ModelPath": "D:\\models\\yolo11n-cls.onnx",

  "ModelType": "Onnx",

  "InferenceType": "Classify",

  "InputWidth": 224,

  "InputHeight": 224,

  "DeviceIndex": -1,

  "InferenceDevice": "CPU"

}

YoloSetModelConfig / YoloGetModelConfig

json

{

  "Success": true,

  "Confidence": 0.5,

  "IouThreshold": 0.45,

  "MaxDetections": 100

}

单键设置

cpp

YoloSetModelConfigByKey(ola, h, "Confidence", "0.6");