Forge：适用于 Metal 的神经网络工具包

:warning: :warning: :warning: 重要提示： 我已不再维护 Forge。它使用的是较旧版本的 MPSCNN API，而该 API 现已被 Apple 废弃。此外，我认为 Core ML 已经在很大程度上消除了对类似库的需求。不过，在 Metal 中实现的神经网络仍然比 Core ML 更快。如果您正在寻找适用于 iOS 和 macOS 的非常快速的 MobileNet V1、MobileNet V2 和 SSD 实现，请查看我的新源代码库。

---

Forge 是一套辅助代码集合，旨在让使用 Apple 的 MPSCNN 框架构建深度神经网络变得更加简单。

阅读博客文章

这个工具能做什么？

Forge 的主要特性：

转换函数。 MPSCNN 对所有内容都使用 MPSImage 和 MTLTexture，并且通常采用 16 位浮点数格式。但您可能更希望使用 Swift 的 [Float] 数组。Forge 提供的转换函数可以让您轻松地处理 Metal 图像和纹理。

便捷的层创建。 减少构建神经网络各层时的样板代码。Forge 的领域特定语言使定义神经网络变得极其简单，例如：

let input = Input()

let output = input
        --> Resize(width: 28, height: 28)
        --> Convolution(kernel: (5, 5), channels: 20, activation: relu, name: "conv1")
        --> MaxPooling(kernel: (2, 2), stride: (2, 2))
        --> Convolution(kernel: (5, 5), channels: 50, activation: relu, name: "conv2")
        --> MaxPooling(kernel: (2, 2), stride: (2, 2))
        --> Dense(neurons: 320, activation: relu, name: "fc1")
        --> Dense(neurons: 10, name: "fc2")
        --> Softmax()

let model = Model(input: input, output: output)

自定义层。 MPSCNN 仅支持有限数量的层，因此我们添加了一些自定义层：

• 深度可分离卷积
• 通道转置
• 反卷积（即将推出！）

预处理内核。 在数据进入神经网络之前，通常需要进行预处理。Forge 提供了几个实用的预处理内核：

• SubtractMeanColor（减去平均颜色）
• RGB2Gray（RGB 转灰度）
• RGB2BGR（RGB 转 BGR）

自定义计算内核。 许多神经网络需要自定义计算内核，因此 Forge 提供了帮助程序，使编写和启动您自己的内核变得容易。

调试工具。 当您在 Metal 中实现神经网络时，需要确保其计算结果正确。由于 Metal 编码数据的方式，直接检查 MTLTexture 对象的内容并不总是那么容易。Forge 可以在这方面提供帮助。

示例项目。 Forge 自带多个预训练的神经网络，例如 MNIST 数据集上的 LeNet-5、ImageNet 上的 Inception3 以及 MobileNets。

注意： 此库中的许多代码仍处于 实验性 阶段，并可能随时发生变化。请自行承担风险！

iOS 10 和 iOS 11 兼容性

Forge 同时支持 iOS 10 和 iOS 11。

Forge 必须使用 Xcode 9 和 iOS 11 SDK 进行编译。（有一个较旧的版本位于 xcode8 标签下，但已不再维护。）

重要变更：

DepthwiseConvolution 层权重的顺序发生了变化。以前是：

[kernelHeight][kernelWidth][channels]

现在变为：

[channels][kernelHeight][kernelWidth]

这是为了使该层与 MPS 的新型深度可分离卷积兼容。在 iOS 10 上，Forge 将使用自己的 DepthwiseConvolutionKernel；而在 iOS 11 及更高版本中，则使用 MPS 版本（MPSCNNDepthWiseConvolutionDescriptor）。

注意：Forge 目前尚未利用 iOS 11 中 MPS 的所有改进功能，例如加载批归一化参数或通过数据源加载权重的功能。这些功能将在未来的版本中加入。

运行示例！

要查看 Forge 的实际演示效果，请在 Xcode 中打开 Forge.xcworkspace，并在您的设备上运行其中一个示例应用。

您至少需要 Xcode 9 和搭载 A8 处理器（iPhone 6 或更高）且运行 iOS 10 或更高版本的设备。无法针对模拟器进行构建，因为模拟器不支持 Metal。

包含的示例包括：

MNIST

此示例实现了一个非常基础的 LeNet5 类型神经网络，该网络在 MNIST 手写数字识别数据集上进行了训练。

运行该应用，并将摄像头对准一个手写数字（Test Images 文件夹中有一些可用于此目的的图像），应用会告诉您该数字是什么，以及它对该预测的置信度。

左上角的小图显示了网络所看到的内容（这是预处理着色器的输出，该着色器试图增强黑白之间的对比度）。

该项目有两个目标：

• MNIST
• MNIST-DSL

它们执行完全相同的操作，只是第一个是用纯 MPSCNN 代码编写的，而第二个则使用 Forge DSL，因此更容易阅读。

Inception-v3

Google 著名的 Inception 网络 用于图像分类。将您的手机对准某个物体，应用会给出其前 5 名预测：

Inception 示例应用基于 Apple 的示例代码，但我们完全使用 DSL 重写了它。我们使用了他们训练好的参数。感谢 Apple！

YOLO

YOLO 是一种目标检测网络。它可以检测图像中的多个对象，甚至会告诉您它们的位置！

示例应用实现了 Tiny YOLO 网络，其精度不如完整的 YOLO9000 版本，只能检测 20 种不同的物体。

YOLO9000：更好、更快、更强 由 Joseph Redmon 和 Ali Farhadi（2016 年）提出。

MobileNets

MobileNets 示例应用是对论文 MobileNets：用于移动视觉应用的高效卷积神经网络 中网络架构的实现。

它的工作方式类似于 Inception-v3，但速度要快得多。在 iPhone 6s 上，它能够以 20 FPS 的帧率运行，同时能耗仅为中等至较高水平。

Forge 使用了来自 shicai/MobileNet-Caffe 的预训练权重。

如何将 Forge 添加到您自己的项目中

请使用 Xcode 9 或更高版本。

1. 将 Forge 文件夹复制到您的项目中。
2. 使用 文件 > 添加文件到“YourProject” > Forge.xcodeproj 将 Forge 项目添加到您自己的项目中。
3. 将 Products/Forge.framework 拖放到您的项目设置中的 嵌入式二进制文件 部分。
4. 在您的代码中 import Forge。

注意：您无法针对模拟器进行构建，只能针对“通用 iOS 设备”或具有 arm64 架构的实际设备进行构建。

如何使用 Forge

• 使用 Forge 创建模型
• 从 Keras、TensorFlow、Caffe 等导入模型

单元测试在哪里？

在设备上运行 ForgeTests 应用。

将测试放在单独的应用中的原因是，Metal 在模拟器上无法正常工作，而 Xcode 又无法在设备上运行逻辑测试。真是个两难的境地。

待办事项

Forge 目前正处于积极开发中。以下是已知问题和即将推出的功能列表。

许可证与致谢

Forge 版权归 Matthijs Hollemans 所有，版权年份为 2016–2017 年，并根据 MIT 许可证条款授权使用。

Forge 快速上手指南

⚠️ 重要提示：本项目作者已停止维护。Forge 使用的是旧版 MPSCNN API，不再受 Apple 支持。虽然 Metal 实现的神经网络速度仍快于 Core ML，但建议新项目优先考虑 Core ML 或作者推荐的 新代码库。本指南仅适用于需要维护旧项目或研究特定 Metal 实现的开发者。

Forge 是一个基于 Apple MPSCNN 框架的辅助工具集，旨在简化使用 Metal 构建深度神经网络的过程，提供便捷的层创建、数据转换及调试功能。

环境准备

在开始之前，请确保满足以下硬件和软件要求：

• 操作系统：macOS（需安装 Xcode）
• 开发工具：Xcode 9 或更高版本（必须使用 iOS 11 SDK 编译）。
  • 注：旧版 Xcode 8 对应版本位于 xcode8 标签，但已不再支持。
• 目标设备：
  • 搭载 A8 处理器 或更高版本的 iPhone/iPad（iPhone 6 及以上）。
  • 系统版本：iOS 10 或更高。
• 架构限制：仅支持 arm64 架构。不支持 iOS 模拟器（Simulator 不支持 Metal），必须使用真机或 "Generic iOS Device" 进行构建。

安装步骤

Forge 没有通过 CocoaPods 或 Carthage 分发，需手动将其源码集成到您的项目中。

1. 获取源码 克隆仓库或下载源码包，将名为 Forge 的文件夹复制到您的项目目录中。

2. 添加子项目 在 Xcode 中打开您的项目，选择菜单栏： File > Add Files to "YourProject"... 选中并添加 Forge/Forge.xcodeproj 文件。

3. 嵌入框架 点击您的主项目 Target，进入 General 设置页：

   • 找到 Embedded Binaries 部分。
   • 将 Products/Forge.framework 从左侧项目导航栏拖入该区域。
   • 确保 Copy items if needed 被勾选（如果尚未自动处理）。

4. 引入模块 在您的 Swift 代码文件顶部添加：

   import Forge
   

基本使用

Forge 的核心优势在于其领域特定语言（DSL），可以极大地减少构建神经网络时的样板代码。以下是一个构建简单卷积神经网络（类似 LeNet-5）的最小化示例：

// 1. 定义输入
let input = Input()

// 2. 使用链式调用构建网络结构
let output = input
        --> Resize(width: 28, height: 28)
        --> Convolution(kernel: (5, 5), channels: 20, activation: relu, name: "conv1")
        --> MaxPooling(kernel: (2, 2), stride: (2, 2))
        --> Convolution(kernel: (5, 5), channels: 50, activation: relu, name: "conv2")
        --> MaxPooling(kernel: (2, 2), stride: (2, 2))
        --> Dense(neurons: 320, activation: relu, name: "fc1")
        --> Dense(neurons: 10, name: "fc2")
        --> Softmax()

// 3. 创建模型对象
let model = Model(input: input, output: output)

关键功能说明

• 数据转换：Forge 提供了辅助函数，方便在 Metal 的 MPSImage/MTLTexture（通常为 16 位浮点）与您常用的 Swift [Float] 数组之间进行转换。
• 自定义层：除了 MPSCNN 原生支持的层外，Forge 还额外实现了 Depth-wise convolution（深度可分离卷积）、Transpose channels 等层。
• 预处理内核：内置了 SubtractMeanColor、RGB2Gray、RGB2BGR 等常用图像预处理算子。
• 调试支持：提供工具帮助检查 MTLTexture 内部数据，验证计算结果是否正确。

运行示例

项目包含多个预训练模型示例（如 MNIST 手写数字识别、Inception-v3 图像分类、YOLO 目标检测、MobileNets）。

1. 打开 Forge.xcworkspace。
2. 连接您的 iOS 真机。
3. 选择一个示例 Scheme（例如 MNIST-DSL）。
4. 点击运行（Build & Run）。
   • 注意：切勿选择模拟器作为运行目标，否则构建会失败。