wuwa_playable_character — 鸣潮可操控角色识别（ONNX）

识别《鸣潮》56 个可操控角色的轻量 ONNX 模型，内置背景负类与三重拒识闸门：不是已知角色的输入（其他作品角色、风景、截图、纯色图）会被判为 unknown。纯 CPU 即可实时推理（INT8 @448 约 100 ms/图、小模型 @384 约 11 ms/图，单线程）。

输入：单人全身立绘/插画
输出：pred（角色名）/ unknown / top5 余弦相似度
当前版本：3.7；类别清单见类别清单

模型列表

模型型号	骨干	输入尺寸	变体	体积	适用场景
`mnv4l_448`	MobileNetV4-conv-large	448×448	int8（推荐）/ fp16 / fp32	33.1 / 63.2 / 126.4 MB	精度优先
`mnv4s_384`	MobileNetV4-conv-small	384×384	fp32 / fp16	11.3 / 5.7 MB	速度/体积优先

int8（QDQ，per-channel）：CPU 部署首选，导出核对 top-1 仅下降 0.20pp。
fp16：CPU 上不提速（x86 无原生 fp16），仅省一半体积，适合 Web/GPU 场景。
每个 ONNX 必须与其同精度配套的 prototypes*.npz（56 个角色原型 + 拒识阈值 τ + p_min）成对使用，跨精度/跨版本混用会让拒识阈值失效。按文件名后缀自动配对： *_int8.onnx → prototypes_int8.npz、*_fp16.onnx → prototypes_fp16.npz、其余 → prototypes.npz。

命名规则

wuwa_playable_character_<版本>_<模型型号>_<训练图像尺寸>[_<量化级别>].onnx
例：wuwa_playable_character_3.7_mnv4s_384_fp16.onnx

字段	取值	说明
版本	`3.7` / `latest`	`versions/` 下用真实版本号；`latest/` 下固定写 `latest`，文件路径永远不变，更新时直接同名覆盖
模型型号	`mnv4l` / `mnv4s`	MobileNetV4-conv-large / MobileNetV4-conv-small
训练图像尺寸	`448` / `384`	letterbox 后的方形输入边长
量化级别	无后缀 = FP32；`fp16`；`int8`	同一模型的所有变体共用目录

目录结构与更新策略

.
├── README.md
├── requirements.txt
├── examples/
│   └── predict.py                # 最简推理示例
├── latest/                       # 最新版本（按模型型号分类，版本字段固定为 latest）
│   ├── mnv4l_448/
│   │   ├── wuwa_playable_character_latest_mnv4l_448_int8.onnx   ← 推荐（CPU）
│   │   ├── wuwa_playable_character_latest_mnv4l_448_fp16.onnx
│   │   ├── wuwa_playable_character_latest_mnv4l_448.onnx        # FP32
│   │   └── prototypes{,_int8,_fp16}.npz                      # 与模型一一配对
│   └── mnv4s_384/
│       ├── wuwa_playable_character_latest_mnv4s_384.onnx        # FP32
│       ├── wuwa_playable_character_latest_mnv4s_384_fp16.onnx
│       └── prototypes{,_fp16}.npz
└── versions/
    └── 3.7/                      # 版本存档（文件名用真实版本号）
        ├── mnv4l_448/
        └── mnv4s_384/

快速开始

pip install -r requirements.txt
python examples/predict.py your_image.jpg \
    --model latest/mnv4l_448/wuwa_playable_character_latest_mnv4l_448_int8.onnx

真实输出示例（延迟因机器而异）：

your_image.jpg: jinhsi_(wuthering_waves)  (81.7 ms, top1_cos=0.2094 head_conf=0.9160)
  0.2094  jinhsi_(wuthering_waves)
  0.0532  carlotta_(wuthering_waves)
  0.0456  suisui_(wuthering_waves)
  0.0247  baizhi_(wuthering_waves)
  0.0244  calcharo_(wuthering_waves)

加 --json 可得到结构化结果（pred / unknown / top5 / head_conf / top1_cos / tau / p_min / version）； Python 调用直接复用 examples/predict.py 中的 Predictor 类。示例脚本在 5 个已发布变体上的输出与训练仓库 src/infer.py 部署口径逐字段一致（含拒识行为）。

推理协议

预处理：

EXIF 转正；调色板转 RGBA；透明像素合成白底；统一 RGB
letterbox：长边缩放到 模型输入尺寸，保宽高比，居中，四边用「边缘像素均值色」或灰色填充成正方形
ImageNet mean/std 归一化 → float32 NCHW

模型输出（ONNX 两个输出）：

embedding：256 维，图内已完成 L2 归一化
logits：57 类（56 个角色 + _negative 背景负类）

判定（三道闸，任一命中 → unknown）：

unknown = (top1_cos < tau) or (max softmax(logits) < p_min) or (argmax(logits) == "_negative")

top1_cos：embedding 与 56 个角色原型的最大余弦；tau、p_min 存于配套 npz
非 unknown 时 pred 取分类头 logits 的 argmax；top5 展示统一用原型余弦分数
三个闸门分别拦截：陌生角色（余弦过低）/ 非插画输入（置信度过低）/ 背景负类（训练用负样本）

指标

部署验收口径（最终模型 + 配套原型库实测；已知角色分层抽样 n=580，背景负类 n=400，非角色输入 n=8）：

模型	top-1（已知角色）	正解被误拒	负类拒识率	τ	p_min
mnv4l_448 int8	0.9759	0.0000	0.8575	0.1234	0.25
mnv4l_448 fp16	0.9776	0.0000	0.8975	0.1246	0.25
mnv4l_448 fp32	0.9776	0.0000	0.9000	0.1247	0.25
mnv4s_384 fp32	0.9741	0.0034	0.8550	0.1412	0.25
mnv4s_384 fp16	0.9741	0.0034	0.8575	0.1413	0.25

单图延迟（ONNX Runtime CPU）：mnv4l_448 int8 ≈100 ms（1 线程）/ ≈35 ms（4 线程）； mnv4s_384 fp32 ≈11 ms（1 线程）/ 3.8 ms（4 线程）。

类别清单

56 个可操控角色（均带 _(wuthering_waves) 后缀），另有 1 个背景负类 _negative（只用于拒识，不会作为输出）：

aalto, aemeath, augusta, baizhi, brant, buling, calcharo, camellya, cantarella,
carlotta, cartethyia, changli, chisa, chixia, ciaccona, danjin, denia,
encore, female_rover, fleurdelys, galbrena, hiyuki, hsin, iuno, jianxin, jingran,
jinhsi, jiyan, lingyang, lucilla, lumi, lupa, luuk_herssen, lynae, male_rover,
mornye, mortefi, phoebe, phrolova, qingxiao, qiuyuan, roccia, sanhua, shorekeeper,
sigrika, suisui, suoming, taoqi, verina, xiangli_yao, yangyang, yinlin, youhu,
yuanwu, zani, zhezhi

完整精确类名以任意 prototypes*.npz 内的 class_names 为准；类名 → 中文名映射表见 class_names_zh.yaml（键为精确类名，中文名待填/随版本维护）。

已知限制

针对单人全身立绘训练：多角色同框、Q 版/chibi、极端裁剪（仅面部特写）、强风格化可能误判或被拒识
仅覆盖 3.7 版训练时的 56 个角色；新角色随后续版本加入，旧版本不会认识新角色
负类拒识率 ≈86%–90%：陌生输入大多会被拒识，但不是 100%
拒识是三道闸的并联结果，unknown=true 时不会给出角色名

许可与声明

模型权重以 CC BY-NC 4.0 提供：仅供研究与个人用途，禁止商业使用
训练数据来自公开网络插画，版权归原作者所有
《鸣潮》（Wuthering Waves）及相关角色版权归 KURO GAMES 所有；本仓库为非官方粉丝项目

Downloads last month: -; Downloads are not tracked for this model. How to track