Ente ML Playground：从模型探索实验到移动端 ONNX 优化产物的完整实践指南

Ente ML Playground从模型探索实验到移动端 ONNX 优化产物的完整实践指南【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente导读本文以 Ente 仓库中的 infra/ml/playground/README.md 为骨架系统讲解 Ente 端到端加密照片库的机器学习基础设施中模型探索与生产化准备这一环节playground目录承载了 MobileCLIP、YOLOv5Face、MobileFaceNet 等模型的探索性 Notebook、实验数据与可复现的模型优化脚本最终产出被 Android/iOS 移动端直接消费的 ONNX 模型产物。读完本文你将掌握如何用uv搭建并运行这套 Notebook 环境、理解每个模型在生产前经历了哪些 ONNX 图变换batch 固定、PReLU/GELU 重写、opset 升级等以及如何通过model_manifest.json校验优化产物的完整性与可复现性。目录定位探索与研究专用不是运行时组件playground 目录 在 infra/ml/README.md 中与test/明确分工playground/仅用于探索性 Notebook 与模型准备工作而test/承载 ML 索引一致性parity测试框架Python 真值、桌面/移动端 runner、比较器与 CI 入口。两个子区域使用独立的 Python 工程playground 使用自己的 pyproject.tomlparity 测试配置保持在infra/ml根目录。原文档明确了 playground 的四个组成目录/文件用途CLIP/CLIP/mobileclip 相关的 Notebook 与实验YOLOv5Face/YOLOv5Face Notebook 及相关资源含pytorch_weights/权重目录data/Notebook 使用的本地样例图片如singapore.jpg、man.jpeg、people.jpegoptimizations/可复现的模型优化脚本及其最终产物注意这个探索定位Notebook 负责把 PyTorch 模型导出为 ONNX、验证其正确性而真正进入生产的图变换逻辑收敛在optimizations/下的可复现脚本中二者解耦避免实验代码污染生产路径。环境搭建与运行 Notebook原文档给出了三步启动流程结合 pyproject.toml 可还原完整依赖背景。步骤 1安装 uvuv是项目选定的 Python 依赖/虚拟环境管理器playground 的依赖锁在uv.lock中。安装方式以 uv 官方文档为准安装后在仓库任意位置执行uv命令均可。步骤 2从仓库根目录同步工程uv sync --project infra/ml/playground该命令会按pyproject.toml创建独立虚拟环境并安装全部依赖。核心依赖清单如下版本约束取自 pyproject.toml推理与模型操作onnx1.17.0、onnxruntime1.28.0版本被精确固定、onnxsim0.4.36、onnxruntime-extensions0.12.0、onnxconverter-common1.14.0PyTorch 生态torch2.4.1、torchvision0.19.1、torchaudio2.4.1图像处理opencv-python4.10.0.84、pillow10.4.0、pillow-heif0.21.0HEIF 解码用于测试 HEIC 样例数据与可视化numpy2.1.2、pandas2.2.3、scipy1.14.1、matplotlib3.9.2、seaborn0.13.2工具类pyyaml6.0.2、requests2.32.3、tqdm4.66.5、thop0.1.1模型 FLOPs 统计内核ipykernel6.29.5同时出现在依赖与[tool.uv] dev-dependencies中工程要求 Python3.12。需要注意 infra/ml/README.md 中的平台提醒ONNX Runtime 1.28 未发布 Apple x86_64 二进制因此在 macOS 上parity 与 playground 的 Python 环境要求 Apple Silicon 且系统为 macOS 14 或更新。步骤 3选择内核运行在 VS Code 或 Jupyter 中选择内核infra/ml/playground/.venv/bin/python即可运行CLIP/与YOLOv5Face/下的 Notebook。Notebook 卫生规范原文档强调提交前务必清空 Notebook 输出Clear notebook outputs以保持 diff 可读、稳定。这一点对含大体积 base64 图片输出与长日志的模型 Notebook 尤其重要——输出一旦入库git diff将难以追踪真正的代码变更。探索阶段两个 Notebook 的模型准备实验CLIP/与YOLOv5Face/分别对应图像语义向量CLIP与人脸检测两个生产能力的模型来源。MobileCLIP图像/文本双模型导出CLIP/mobileclip_onnx.ipynb 以 Apple 的mobileclip_s2为基准引用论文 arXiv:2311.17049 与官方 ml-mobileclip 仓库实验内容拉取官方仓库与预训练权重mobileclip_s2.pt等加载模型与分词器使用data/singapore.jpg等样例图验证预处理MobileCLIP 图像输入为[1, 3, 256, 256]与文本编码77 token 上限的输出通过EncodeImageWrapper/EncodeTextWrapper分别导出图像编码器mobileclip_s2_image_float32.onnx与文本编码器mobileclip_s2_text_int64.onnxopset 18为 Resize 的抗锯齿语义、开启常量折叠、指定input/output命名对导出图做改名等调整将输入重命名为og_input为后续可容纳预处理子图的alter model预留input名并用onnx.checker.check_model校验。YOLOv5Face人脸检测模型导出YOLOv5Face/yoloface_onnx.ipynb 基于 deepcam-cn/yolov5-face论文 arXiv:2105.12931要求用户将 PyTorch.pt权重手动放入pytorch_weights/即 YOLOv5Face/pytorch_weights克隆官方仓库并复制models/、utils/源码用于导出时的算子实现以img_size[640, 640]、batch_size1、静态 shape 导出 ONNX。这两个 Notebook 共同揭示了生产模型的来源链路PyTorch 权重 → 官方实现 → 静态 ONNX 导出而进一步的生产化变换则交由optimizations/脚本完成。生产化阶段optimizations 目录的可复现优化如果说 Notebook 是探索那么 optimizations/README.md 记录的则是交付。它承载 Ente 移动端 ML 模型的生产变换生成的 CDN 产物写在models/下ONNX 文件被.gitignore有意排除而 models/model_manifest.json 记录可复现的输出元数据。重建命令从仓库根目录执行--no-sync避免在纯重建场景重复同步依赖uv run --project infra/ml/playground --no-sync python \ infra/ml/playground/optimizations/optimize_models.py \ --source-dir infra/ml/test/.cache/local_model_mirror \ --output-dir infra/ml/playground/optimizations/models脚本只执行被选中进入生产的变换下面逐一拆解。YOLObatch 固定 常量折叠将 batch 维固定为 1set_batch_one见 optimize_models.py 中set_batch_one用 ONNX Runtime 的 basic 优化器ORT_ENABLE_BASICCPUExecutionProvider对 shape 图做常量折叠。源模型yolov5s_face_640_640_dynamic.onnx需匹配固定的 SHA-25671a00870...输出为yolov5s_face_640_640_static_b1.onnx。从 manifest 看产物输入为[1, 3, 640, 640]输出[1, 25200, 16]640/8、640/16、640/32 三个尺度合计 25200 个候选框每框 16 维共 328 个节点其中 Conv 64 个、Sigmoid 67 个。MobileFaceNet面向双端可移植的 PReLU 分解这是三个模型中变换最密集的一个核心动机记录在源码注释中optimize_models.py 的rewrite_prelu_decompositionsCoreML 不支持AbsAndroid 的 WebGPU EP 不支持PRelu而两者都支持恒等改写PReLU(x, alpha) Relu(x) - alpha * Relu(x * -1)。具体变换PReLU 分解将 33 个训练好的 PReLU 激活精确改写为上述Relu/Mul/Relu/Mul/Sub五算子组合脚本断言必须恰好 33 个否则抛错避开 WebGPU 专有 kernel同时使用 CoreML MLProgram 与 WebGPU 均支持的算子使同一产物可同时被 Android 与 iOS 共享batch 固定为 1隐式 padding 显式化给 2 个未声明pads/auto_pad的 Conv 补上[0,0,0,0]CoreML 要求 ONNX 默认零填充显式化make_implicit_conv_padding_explicit移除冗余的 L2 归一化末尾的LpNormalization被替换为Identityremove_redundant_output_normalization因为 Rust 调用方已自行执行输出 L2 归一化。产物mobilefacenet_portable_static_b1.onnx输入[1, 112, 112, 3]NHWC输出 192 维人脸嵌入共 233 个节点算子表印证了重写结果66 个 Relu 33 个 Sub 66 个 Mul不含 Conv 的 Mul恰好对应分解后的正负两支。MobileCLIPopset 20 升级 GELU 折叠用onnx.version_converter将图升级到 opset 20将 54 处展开的精确 GELU 表达式x/sqrt(2) - Erf - 1 - *x - *0.5子图折叠为Gelu(approximatenone)rewrite_exact_gelu脚本断言恰好 54 处。这样在保持 FP32/精确 GELU 语义的同时把融合算子暴露给 CoreML 与 WebGPU。产物mobileclip_s2_image_gelu_opset20.onnx输入[1, 3, 256, 256]输出 512 维图像嵌入504 个节点算子表含 54 个Gelu。产物元数据与校验build_models阶段对每个源模型做 SHA-256 校验与脚本头部常量比对防止镜像被替换最终写出 model_manifest.json记录每个产物的相对路径与 SHA-256、字节数、节点数完整算子清单按算子类型计数的 Counter按名称排序输入/输出张量的名称与 shape含维度值或维度参数。该清单既是对 CDN 发布内容的机器可读校验依据也是ONNX 文件不入库策略下保证可复现性的关键元数据。产物验证两个基准测试报告optimizations/benchmark_reports/下两份报告验证了上述产物的运行时表现与平台差异可作为理解为什么需要这些优化的实证材料。移动端 ML 索引基准2026-07-2220260722_FINAL_MOBILE_ML_BENCHMARK_REPORT.md 在 Pixel 8Android 17ONNX Runtime WebGPU与 iPhone 15 ProiOS 26.5.2ONNX Runtime CoreML上以 14 张 parity 夹具图评测三模型管线iOS 持久化 CoreML 缓存收益显著三模型总加载时间从缓存关闭的 8,595.5 ms 降至暖缓存 840.8 ms降幅 90.2%10.2 倍加速冷启动prime为 4,306.4 ms稳态端到端索引中位数Pixel 8 为 12,994.3 ms928.2 ms/图iPhone 15 Pro 为 5,022.2 ms358.7 ms/图iPhone 端到端快 2.59 倍、Rust 管线内快 4.06 倍正确性移动端两机互比 14/14 通过与 Python 真值对比 13/14唯一差异是已知的IMG_8905.CR2RAW 直解码失败后平台回退 JPEG 渲染与 Python 直接解码 RAW 不同报告建议启用持久化 CoreML 缓存将 RAW 回退转换列为独立优化目标Rust 后处理已不再是瓶颈Pixel 12.7 ms / iPhone 2.3 ms。基准日志通过编译期开关ENTE_ML_BENCHMARK_LOGGING与ENTE_ML_BENCHMARK_RELEASE_TESTS1选择性启用正常构建不产生这些计时机器可读产物summary/results/logcat位于infra/ml/test/out/下。Android 调度器验证2026-07-2320260723_ANDROID_ML_SCHEDULER_VERIFICATION_REPORT.md 追踪了 07-22 报告中iPhone 远快于 Pixel的成因结论是Android 的 DVFS 与调度行为而非硬件差距ML 管线每轮 ~240 ms GPU 推理后紧跟的短 CPU 突发无法累积出足够的每线程利用率来提升频率。将全部管线工作集中到单一大核变体 DCortex-X3CPU8后预处理从 596.7 ms 降到 212.4 ms2.8 倍中位频率从 910 MHz 升到 2,363 MHz。报告据此提出生产建议用单一持久化专用线程运行 ML 管线、将 CPU 预处理与 GPU 推理流水化、采用 ADPFPerformanceHintManager、移除fast_image_resize的 rayon 特性并明确硬性绑核只是诊断手段不可直接上线。这两份报告共同说明了 playground 产物的下游验证闭环优化脚本产出的 ONNX 被移动端消费后其加载、推理与正确性均由基准与 parity 测试持续把关。与 Rust 运行时的衔接优化产物最终进入 rust/crates/ml/src/assets.rs 维护的模型目录该文件列出mobileclip_s2_image.onnx、yolov5s_face_640_640_dynamic.onnx、mobilefacenet_opset15.onnx等源模型从https://models.ente.com/拉取并按内置目录的 key 与校验和校验运行时通过selected_indexing_models(run_faces, run_clip, run_pets)按需选择模型资产。这与 playground 的工作形成清晰链路Notebook 导出 →optimize_models.py生产化 → manifest 校验 → Rust 资产目录消费 → 移动端WebGPU/CoreML推理。关于 parity 框架与真值生成可进一步阅读 infra/ml/test/README.md。小结与最佳实践分层明确playground专注探索与模型准备optimizations收敛可复现的生产变换test负责一致性与正确性把关三者各司其职可复现性优先源模型 SHA-256 强校验、固定onnxruntime1.28.0、ONNX 产物不入库而以 manifest 记录元数据共同保证脚本重跑可得相同产物跨端可移植是硬约束MobileFaceNet 的 PReLU 分解与 MobileCLIP 的 GELU 折叠本质都是为了让同一个 ONNX 文件同时满足 CoreML 与 WebGPU 的算子支持集减少双端模型维护成本基准驱动决策CoreML 持久缓存、Android 调度行为等结论均来自真实设备基准报告而非主观推测。对希望为移动端自建 ML 索引能力的开发者而言playground 目录提供了一个可复用的模板探索 Notebook 与生产脚本分离、以 manifest 固化产物元数据、用基准报告驱动优化取舍。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考