为什么同一个模型在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-modelscoreai-models 是苹果开源的端侧 AI 工具库提供模型导出配方、Python 基础算子和 Swift 运行时让 PyTorch 模型能在 iPhoneNeural Engine和 MacGPU上以 Core AI 格式高效推理。很多新手都会疑惑同一个 Qwen3为什么仓库里 iOS 和 macOS 各有一份完全不同的实现答案藏在 Apple 芯片的两类加速单元里。本文将用 8 个关键差异 一套仓库地图帮你彻底搞懂这两套创作规则。 一句话结论iPhone 靠 Neural Engine 省电Mac 靠 GPU 拼吞吐两者的硬件方言不同所以同一模型需要两套面向不同加速单元的 PyTorch 实现。模型权重是同一份但张量布局、算子选择、注意力写法、缓存机制全部要按硬件习惯重写——这也是 model-authoring 技能文档总结的核心经验。 三大加速单元性格完全不同先建立直觉Apple 设备上有三种算力单元各有所长。加速单元擅长关键创作约束Neural EngineiPhone / iPad / M 系列常驻场景能效比之王适合静态、常驻任务BC1S 布局、仅 fp16、全静态形状、受限算子集GPUMac 主力高吞吐、大模型、灵活负载标准 PyTorch 布局、支持 fp32 中间量、动态形状CPU小模型、低延迟、正确性校验能跑所有算子适合做基准参考一句话记忆法用户说省电、常驻、iPhone → Neural Engine说性能、大批量、macOS → GPU说对答案、调试 → CPU。 8 个关键差异一眼看懂两套实现下面是从 neural_engine_rules.md 和 gpu_rules.md 提炼的对照表这是全文最值钱的部分 #维度Neural EngineiOSGPUmacOS1张量布局BC1S(B, H×D, 1, S)像卷积特征图标准(B, S, D)2线性层nn.Conv2d(kernel_size1)卷积引擎原生加速nn.Linear且 Q/K/V 融合成一个大矩阵3Embedding形状(V, 1, D)且与主干分开导出标准nn.Embedding4注意力逐头per-head顺序计算einsum 直连硬件融合的原生 SDPA一次算完所有头5精度只认 fp16任何 fp32 字面量都会掉回 CPUfp16 权重 fp32 中间量都 OK6形状全静态每个形状组合单独编译支持动态形状7KV Cache只读函数式 I/O缓存作为输入传入、新 K/V 作为输出返回模型内部禁止写缓存有状态 bufferregister_buffermutable_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(..., dtypehidden.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/RMSNormpython/src/coreai_models/primitives/macos/GPU 基础算子融合 SDPA、有状态 KV cache、MoE 的 SwitchLinearpython/src/coreai_models/export/双平台导出流水线iOS/macOS 导出路径、压缩预设、自定义 loweringswift/Sources/Swift 运行时推理引擎、解码循环、采样、KV cache 管理models/每个模型家族的导出配方与 README对比一下同一模型的两个文件差异一目了然比如 iOS 版 primitives/ios/sdpa.py 是逐头展开的注意力而 macOS 版 primitives/macos/sdpa.py 是一次调用的融合 SDPAKV 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 # 默认 macOSGPU版 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-lengthmacOS 用动态 KV cache 可省略。第 3 步用 PSNR 门禁验证精度。重写与源模型对比应 70 dB实现正确编译后对比 ≥ 40 dBfp16 正常损失4-bit 调色板后 ≥ 35 dB压缩可接受。低于阈值就查 common_issues.md 里的对照清单。 总结为什么写两套是特性而非浪费硬件方言不同Neural Engine 用卷积引擎做矩阵乘BC1S Conv2dGPU 用标准 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），仅供参考