feat: Update CoreML device support and server controls
- Replace 'mps' with 'coreml' as the identifier for Apple CoreML Execution Provider across the codebase. - Remove Apple chip generation checks and ensure CoreML is available on all macOS arm64 devices. - Adjust ONNX Runtime session creation to use default CoreML configurations without forcing 'MLProgram'. - Implement support for MoGe-2 to utilize CoreML with static input shape requirements. - Enhance server panel to display restart and stop controls consistently across running states, including 'BUSY'. - Update UI tests to verify new behavior for server controls and cached model display. - Bump blendjob dependency version to 0.1.16 in packaging tests and configurations.
This commit is contained in:
68
openspec/changes/correct-coreml-device-support/design.md
Normal file
68
openspec/changes/correct-coreml-device-support/design.md
Normal file
@@ -0,0 +1,68 @@
|
||||
## Context
|
||||
|
||||
AnyImage 的 ONNX 推理把设备值 `mps` 映射到 `CoreMLExecutionProvider`,但该名称通常指 PyTorch Metal backend,与实际实现不一致。Blender 端还通过 CPU brand string 将 Apple 加速限制为 M4 及以上,而 macOS 扩展本身只发布 `macos-arm64`,支持范围已经限定为 Apple Silicon。
|
||||
|
||||
共享 Session 工厂目前为所有 CoreML 模型强制传入 `ModelFormat=MLProgram`。MoGe-2 的 ONNX 图具有动态空间尺寸、动态 `num_tokens`、控制流和大量 shape 运算,CoreML 在 MacBook M4 上会在 Session 创建阶段因执行计划构建失败;加入该配置前,同一 Provider 使用默认模型格式可以运行。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 让设备名称准确表达 CoreML Execution Provider。
|
||||
- 在全部受支持的 macOS arm64 设备上提供 CoreML。
|
||||
- 恢复 MoGe-2 在 MacBook M4 CoreML 模式下的 Session 创建与推理。
|
||||
- 保持共享 ONNX Session 工厂简单,并保留 CPU fallback。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 引入 PyTorch 或实现 PyTorch MPS backend。
|
||||
- 保证所有 CoreML 算子只在 GPU 上执行。
|
||||
- 支持 macOS x64、iOS 或新的模型格式。
|
||||
- 保留 `mps` 任务值、配置值或转发映射。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 使用 `coreml` 作为唯一 Apple 加速设备标识
|
||||
|
||||
Blender Enum、Job 参数、运行时设备清单和 Provider 选择表统一使用小写 `coreml`,界面显示 `CoreML`。旧 `mps` 标识直接删除,因为它描述的是不同的推理 API;增加别名会继续扩大协议边界并违反项目不保留兼容层的约束。
|
||||
|
||||
### 2. 按平台能力判断 CoreML,不按芯片代际判断
|
||||
|
||||
macOS 且机器架构为 `arm64` 或 `aarch64` 时提供 `coreml` 和 `cpu`,其他 Unix 平台只提供 `cpu`,Windows 维持 DirectML 与 CPU。删除 CPU brand string 正则、`sysctl` 子进程和 M4 代际测试。这样支持范围与 `macos-arm64` 扩展包以及 ONNX Runtime macOS arm64 wheel 一致。
|
||||
|
||||
保留 M4 门槛的替代方案被放弃,因为它不是 Provider 能力判断,只会让 M1–M3 在具备 CoreML 时被迫使用 CPU。
|
||||
|
||||
### 3. 默认 CoreML 配置与 MoGe-2 静态分区配置分离
|
||||
|
||||
共享 Session 工厂默认向 ONNX Runtime 传递普通的 `CoreMLExecutionProvider` 名称,不再为所有模型强制 `MLProgram`。它同时接受可选的模型级 CoreML options;只有调用方明确提供时才把 CoreML Provider 配置为 tuple。CUDA 的独立 arena 配置保持不变。
|
||||
|
||||
MoGe-2 传入 `RequireStaticInputShapes=1`,使 CoreML EP 只接管输入 shape 已静态确定的分区,动态空间尺寸、动态 `num_tokens` 和相关控制流留给 CPU fallback。BEN2、DA3 与 Upscale 不携带该选项,继续使用普通 CoreML 配置。
|
||||
|
||||
该决定取代“所有模型都使用普通 CoreML 配置”的原方案:M2 真机证明 NeuralNetwork 格式虽然能创建 MoGe-2 Session,但动态 CoreML 分区仍会在执行时失败。也不选择 `CPUAndGPU`,因为故障来自动态图兼容性,而不是 Neural Engine 选择;不选择整体强制 CPU,因为静态限制仍允许安全分区使用 CoreML。
|
||||
|
||||
### 4. macOS 界面默认 CPU,CoreML Session 保持 CPU fallback
|
||||
|
||||
macOS arm64 的设备枚举把 CPU 放在 CoreML 之前,使新安装和未保存设备选择时默认使用 CPU。CoreML 的性能取决于模型和设备,用户需要时可手动选择,不根据芯片代际自动启用。
|
||||
|
||||
显式选择 `coreml` 时仍以 `CoreMLExecutionProvider` 为首选并显式附带 `CPUExecutionProvider`;共享 Session 工厂的自动 Provider 顺序也保持不变。这样 MoGe-2 被静态限制排除的动态节点具有确定的 CPU fallback;明确选择 CPU 时则只请求 CPU Provider。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [CoreML 默认配置在未来 ONNX Runtime 版本中可能变化] → 固定 ONNX Runtime 版本,并以 Session 参数测试保证 AnyImage 不再主动强制 `MLProgram`。
|
||||
- [MoGe-2 静态分区限制可能减少 CoreML 加速比例] → 接受 CPU fallback 以换取正确性,并用真机 smoke test 验证;不把 CoreML 设备描述为纯 GPU。
|
||||
- [M1–M3 未覆盖真实设备集成测试] → 单元测试覆盖平台枚举,并在可用 Apple Silicon 设备上执行 MoGe-2 smoke test;真实失败仍可选择 CPU。
|
||||
- [旧 Blender 配置保存了 `MPS`] → 这是明确的 breaking rename;不解析旧值,用户在新版中选择 `CoreML` 或 `CPU`。
|
||||
- [CoreML 不保证纯 GPU] → 界面和文档只承诺 CoreML,不再使用 Metal/MPS 或纯 GPU 表述。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 同步替换设备协议与界面枚举中的 `mps` 为 `coreml`,删除芯片代际检测。
|
||||
2. 移除共享的强制 CoreML options,让普通模型使用默认配置,并让 MoGe-2 单独传入 `RequireStaticInputShapes=1`。
|
||||
3. 更新测试和内部文档,再运行相关单元测试。
|
||||
4. 在可用的 M2 或 M4 设备选择 CoreML,分别执行 MoGe-2、BEN2 和 Upscale smoke test;MoGe-2 必须完成 Session 创建和一次推理。
|
||||
|
||||
若真实设备验证失败,回滚本变更并使用 CPU;不重新引入 `mps` 兼容层。
|
||||
|
||||
## Open Questions
|
||||
|
||||
无。
|
||||
Reference in New Issue
Block a user