OLA 文档中心

主题

2026-06-12

类别名称表说明 - NamesLabel ​

加载 YOLO 模型时，可通过 namesLabel（磁盘/内联）或 labelData + labelSize（内存）传入类别名称表。名称用于：

  • 推理结果 JSON 中的 ClassName / TopClassName 显示；
  • Detect 等任务的 classes 参数按类名过滤（如 dog|bus）；
  • YoloGetModelInfo 返回的 ClassNames 数组。

不是 NCNN 的 .param 结构文件；NCNN 结构请传 ncnnParamPath / ncnnParamData。

一、支持的传入方式 ​

方式适用接口说明
labels 文件路径YoloLoadModelEx、YoloEncryptModel传 UTF-8 路径，如 labels/coco.names
内联文本YoloLoadModelEx、YoloEncryptModel直接传字符串，无需落盘
内存字节YoloLoadModelMemoryEx、YoloEncryptModelExlabelData + labelSize 为原始文件字节

传 空字符串 或 labelSize = 0 表示不加载 names；此时结果 JSON 仅有 ClassId，classes 过滤须用数字 id。

二、文本格式（三种等价写法） ​

插件在解析前会将内容统一归一化为 UTF-8，再按下列规则拆分类别：

1. 多行：一行一类（最常见） ​

text
person
car
bus

换行支持 \n、\r\n、\r（Windows / Unix / 旧 Mac 均可）。

2. 竖线分隔：一行多类 ​

text
person|car|bus

等价于上面三行。中文示例：

text
人|车|狗|猫

3. 混合格式 ​

文件内可混合使用，例如：

text
person|car
bus
人|狗

每行若含 |，则按 | 拆分；否则整行作为一个类名。

可选：索引:名称 行（兼容部分工具导出格式） ​

源码 parse_label_line（yolo_label_utils.hpp）对含 : 的行处理如下：

输入行解析得到的类名是否加入列表
0:personperson✅
1:carcar✅
:person（冒号前无索引）person✅
0:（冒号后无名称）—❌ 跳过
person（无冒号）person✅

重要：冒号前的数字不参与 ClassId 映射。 类别 id 仍按行序（或 \| 分割后的 token 顺序）从 0 递增，与 0:、1: 前缀无关。

示例：文件内容为

text
1:car
0:person

则 ClassId=0 对应 car，ClassId=1 对应 person（不是按前缀数字排序）。

若类名本身需包含冒号（如 a:b），当前实现会误拆为取 b 作为类名，请避免在类名中使用 :。

三、支持的文件编码 ​

文件内容与内存字节均会自动识别并转为内部 UTF-8（无需调用方手动转码）：

编码典型来源支持
ASCII英文类名✅
UTF-8（无 BOM）VS Code、Linux、Python encoding=utf-8✅ 推荐
UTF-8 with BOMWindows 记事本「UTF-8」保存✅ 自动去 BOM
GBK / CP936Windows 记事本「ANSI」保存的中文✅ 中文常用
UTF-16 LE/BE（含 BOM）部分 Windows 工具✅

暂不支持或易出问题：

情况说明
UTF-16 无 BOM无法可靠识别，可能乱码
Big5、Shift-JIS 等会误按 GBK 处理，类名可能错误
类名本身含 | 且单行传入会被拆成多个类（极少见）

API 字符串参数（如 YoloLoadModelEx 的 namesLabel 内联文本）须为 UTF-8（与 COM/SDK 约定一致）。

四、各接口用法示例 ​

文件路径（多行 UTF-8） ​

csharp
long h = ola.YoloLoadModelEx(
    @"D:\models\yolo11n.onnx", "",
    @"D:\labels\coco.names",
    1, 0, -1);

内联竖线分隔（中文） ​

csharp
long h = ola.YoloLoadModelEx(
    @"D:\models\yolo11n.onnx", "",
    "人|车|狗|猫",
    1, 0, -1);

内存加载（读文件原始字节） ​

csharp
byte[] modelBytes = File.ReadAllBytes(@"D:\models\yolo11n.onnx");
byte[] labelBytes = File.ReadAllBytes(@"D:\labels\labels.txt"); // UTF-8 或 GBK 均可
long h = ola.YoloLoadModelMemoryEx(
    modelBytes, modelBytes.Length,
    0, 0,
    labelBytes, labelBytes.Length,
    1, 0, -1);

labelSize 为精确字节数，不要用 strlen + 1，避免把末尾 \0 传入。

加密打包（内联 names） ​

csharp
ola.YoloEncryptModel(
    @"D:\models\yolo11n.onnx", "",
    "person|car|bus",
    "your_password", 1, 0,
    @"D:\out\game.omd");

加密包内 names 会归一化为 UTF-8 存储；YoloLoadModel 解密后自动解析。

五、与推理过滤 classes 的关系 ​

加载 names 后，Detect 等接口的 classes 参数可使用类名（竖线分隔），须与名称表完全一致（含中文）：

csharp
// names 为 "人|车|狗"
string json = ola.YoloDetectFromFile(h, @"D:\test.jpg", "人|狗", 0.25, 0.45);

未加载 names 时，classes 只能使用 class_id 数字（如 0|2）。

详见 推理输入参数说明 中 classes 一节。

六、常见问题 ​

Q：必须用 labels 文件吗？
A：否。可直接传 "A|B|C" 或内存字节，效果与文件多行相同。

Q：中文 labels 用记事本保存可以吗？
A：可以。选「ANSI」（GBK）或「UTF-8」均可；插件会自动识别。

Q：类名顺序重要吗？
A：是。第 0 行（或 | 分割后第 1 个）对应 ClassId = 0，须与训练/export 时的类别顺序一致。

Q：与加密包的关系？
A：YoloEncryptModel 可把 names 一并打入包内；YoloLoadModel 只需密码，无需再传 labels 路径。

相关文档 ​