为什么同一个模型在iOS和macOS要实现两套？coreai-models的Neural Engine与GPU双平台创作规则
【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-models
coreai-models 是苹果开源的端侧 AI 工具库，提供模型导出配方、Python 基础算子和 Swift 运行时，让 PyTorch 模型能在 iPhone（Neural Engine）和 Mac（GPU）上以 Core AI 格式高效推理。很多新手都会疑惑：同一个 Qwen3，为什么仓库里 iOS 和 macOS 各有一份完全不同的实现？答案藏在 Apple 芯片的两类加速单元里。本文将用 8 个关键差异 + 一套仓库地图，帮你彻底搞懂这两套"创作规则"。
🧭 一句话结论
iPhone 靠 Neural Engine 省电，Mac 靠 GPU 拼吞吐，两者的"硬件方言"不同，所以同一模型需要两套面向不同加速单元的 PyTorch 实现。模型权重是同一份，但张量布局、算子选择、注意力写法、缓存机制全部要按硬件习惯重写——这也是 model-authoring 技能文档总结的核心经验。
📊 三大加速单元，性格完全不同
先建立直觉：Apple 设备上有三种算力单元，各有所长。
| 加速单元 | 擅长 | 关键创作约束 |
|---|---|---|
| Neural Engine（iPhone / iPad / M 系列常驻场景） | 能效比之王，适合静态、常驻任务 | BC1S 布局、仅 fp16、全静态形状、受限算子集 |
| GPU（Mac 主力） | 高吞吐、大模型、灵活负载 | 标准 PyTorch 布局、支持 fp32 中间量、动态形状 |
| CPU | 小模型、低延迟、正确性校验 | 能跑所有算子，适合做基准参考 |
一句话记忆法：用户说"省电、常驻、iPhone" → Neural Engine；说"性能、大批量、macOS" → GPU；说"对答案、调试" → CPU。
🔍 8 个关键差异：一眼看懂两套实现
下面是从 neural_engine_rules.md 和 gpu_rules.md 提炼的对照表，这是全文最值钱的部分 👇
| # | 维度 | Neural Engine（iOS） | GPU（macOS） |
|---|---|---|---|
| 1 | 张量布局 | BC1S：(B, H×D, 1, S)，像卷积特征图 | 标准：(B, S, D) |
| 2 | 线性层 | nn.Conv2d(kernel_size=1)，卷积引擎原生加速 | nn.Linear，且 Q/K/V 融合成一个大矩阵 |
| 3 | Embedding | 形状(V, 1, D)，且与主干分开导出 | 标准nn.Embedding |
| 4 | 注意力 | 逐头（per-head）顺序计算，einsum 直连硬件 | 融合的原生 SDPA，一次算完所有头 |
| 5 | 精度 | 只认 fp16，任何 fp32 字面量都会掉回 CPU | fp16 权重 + fp32 中间量都 OK |
| 6 | 形状 | 全静态，每个形状组合单独编译 | 支持动态形状 |
| 7 | KV Cache | "只读函数式 I/O"：缓存作为输入传入、新 K/V 作为输出返回，模型内部禁止写缓存 | 有状态 buffer：register_buffer+mutable_slice_update原地更新 |
| 8 | 压缩方案 | 4-bit 调色板（palettization），神经引擎原生支持 | INT4 权重量化 / FP8，选项更丰富 |
几个反直觉的小坑（来自 common_issues.md）：
- ⚠️因果掩码是转置的：Neural Engine 的掩码形状是
(1, key_seq, 1, query_seq)，方向与 GPU 相反，搞反了 PSNR 会掉到 15–30 dB； - ⚠️不能写
float('-inf')：Neural Engine 的 softmax 处理不了 IEEE 负无穷，要用-40000.0代替； - ⚠️Python 浮点字面量是杀手：
x * 1.0里的1.0是 fp32，整个算子会被踢出 Neural Engine，需要改用torch.ones(..., dtype=hidden.dtype)这类写法； - ⚠️缓存要存"加过 RoPE 的 K"：若缓存了未编码的 K，下一轮注意力就指向过期数据，输出直接崩到 20 dB 左右。
🗂️ 仓库地图：两套实现是怎么组织的
coreai-models 把双平台的差异沉淀成了清晰的目录结构，可以直接照着读源码：
| 路径 | 内容 |
|---|---|
| python/src/coreai_models/models/ios/ | 面向 Neural Engine 重写的模型实现（含 gemma4_text、qwen2、qwen3、olmo2 等） |
| python/src/coreai_models/models/macos/ | 面向 GPU 重写的模型实现（gemma3、qwen3、mixtral、gpt_oss 等） |
| python/src/coreai_models/primitives/ios/ | Neural Engine 基础算子：逐头 SDPA、只读 KV cache、BC1S 版 RoPE/RMSNorm |
| python/src/coreai_models/primitives/macos/ | GPU 基础算子：融合 SDPA、有状态 KV cache、MoE 的 SwitchLinear |
| python/src/coreai_models/export/ | 双平台导出流水线：iOS/macOS 导出路径、压缩预设、自定义 lowering |
| swift/Sources/ | Swift 运行时：推理引擎、解码循环、采样、KV cache 管理 |
| models/ | 每个模型家族的导出配方与 README |
对比一下同一模型的两个文件，差异一目了然：比如 iOS 版 primitives/ios/sdpa.py 是逐头展开的注意力，而 macOS 版 primitives/macos/sdpa.py 是一次调用的融合 SDPA；KV cache 上，iOS 是 primitives/ios/cache.py 的只读 I/O 模式，macOS 是 primitives/macos/cache.py 的原地更新模式。
🚀 新手上手三步走
第 1 步：先用现成配方，不要从零写。仓库已覆盖 Qwen3、Gemma、Mistral、Whisper 等主流模型：
uv run coreai.llm.export Qwen/Qwen3-0.6B # 默认 macOS（GPU）版 uv run coreai.llm.export Qwen/Qwen3-0.6B --platform iOS # Neural Engine 版具体支持矩阵和压缩选项见 models/qwen3/README.md；所有模型目录见 models/README.md。
第 2 步：如果要自己重写模型，自底向上按序实现。Norm → 线性投影 → 注意力 → MLP → 完整解码层，每写完一个算子先单独验证，再组合。iOS 导出时注意静态形状：需要显式指定--max-context-length（macOS 用动态 KV cache 可省略）。
第 3 步：用 PSNR 门禁验证精度。重写与源模型对比应 > 70 dB（实现正确），编译后对比 ≥ 40 dB（fp16 正常损失），4-bit 调色板后 ≥ 35 dB（压缩可接受）。低于阈值就查 common_issues.md 里的对照清单。
🧠 总结：为什么"写两套"是特性而非浪费
- 硬件方言不同：Neural Engine 用卷积引擎做矩阵乘（BC1S + Conv2d），GPU 用标准 PyTorch 布局 + 融合算子——硬凑一套只会两边都慢；
- 优化目标不同：iOS 为"电池 + 常驻"服务（静态形状、fp16 纯净、只读缓存），macOS 为"吞吐 + 灵活"服务（动态形状、融合 QKV、状态缓存）；
- 仓库帮你省掉了探索成本：双套 primitives + 导出配方 + 规则文档都已备好，新手直接从 skills/skills/model-authoring/SKILL.md 的速查表入手，再对照
models/ios/与models/macos/的源码，是最快的学习路径 ✅
理解了这套规则，你再看到"同一模型双实现"，就不会觉得冗余，而是会心一笑：这是端侧 AI 在两种硬件上的正确打开方式。
【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-models
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考