ncnn：腾讯开源高性能移动端神经网络推理框架部署与使用指南

ncnn 是腾讯开源的高性能神经网络推理框架，专门面向移动端、嵌入式设备和桌面端的部署场景做了深度优化。所谓高性能，并不是简单地把模型跑起来，而是要在手机这种 CPU 弱、内存紧、功耗敏感的设备上，把卷积神经网络和后续的各类算子压到尽可能小的体积、尽可能短的时延里。与服务端动辄依赖 CUDA、cuDNN、TensorRT 这类重型栈不同，移动端推理要求框架自身足够精简、足够贴近硬件，ncnn 正是在这种背景下诞生并被腾讯内部大规模打磨出来的。

ncnn 最大的特点是零第三方运行时依赖——编译产物里不依赖 BLAS、NNPACK 之类的数学库，也不要求系统预装任何深度学习运行时，只靠纯 C++ 实现就能在手机、PC、浏览器和边缘设备上跑起来。这一点对移动端尤为关键，因为引入第三方库不仅会增大包体积，还会带来 ABI 兼容、裁剪、冲突等一系列麻烦。推理后端同时支持 CPU 与 Vulkan GPU 两条路径：CPU 侧针对 ARM NEON 指令集和多核调度做了专门优化，GPU 侧则借助 Vulkan 实现跨厂商的显卡加速，在支持的设备上可以进一步提升吞吐。模型工程方面，官方提供 pnnx 工具，可以把 PyTorch、ONNX 模型一键转换为 ncnn 自有格式（.ncnn.param 与 .ncnn.bin），还配套了模型优化、量化、自定义层等一系列工具链。

目前 ncnn 已经在腾讯多款主力产品中实际使用，例如 QQ、Qzone、微信、天天 P 图等，是国内移动端深度学习部署领域最有影响力的开源框架之一。它的设计哲学是把模型推理做到极致轻量：不绑定特定硬件、不依赖第三方数学库、不强制使用特定构建系统，开发者拿到的只是一组头文件、一个静态或动态库，以及一对 .param / .bin 模型文件。这种极简的工程形态让它在资源受限的设备上也能轻松落地，几乎没有接入门槛，非常适合移动端与边缘端的深度学习场景。本文基于仓库 README 逐节完整翻译整理，从项目背景、核心特性、全平台安装构建、模型转换、C++/Python API 使用、模型覆盖到常见问题做全面说明，帮助开发者完整了解它的能力、部署方式与用法，并快速完成本地部署。

一、项目官方信息

二、官方图片与架构

ncnn 的整体使用链路被官方概括为一条推荐路径：PyTorch → pnnx → ncnn。开发者先用 PyTorch 训练或加载模型，再通过 pnnx 导出为 ncnn 模型文件，最后在手机、PC、浏览器或嵌入式设备上通过 C++ API 或 Python 绑定加载并执行推理。框架内部采用显式的 blob 与 workspace 分配器设计来控制内存占用：所谓 blob 是算子之间传递的张量缓冲，workspace 则是某些算子内部需要的临时工作区，开发者可以按需申请和释放，避免像通用框架那样在启动时一次性占用大块内存。框架支持多输入、多输出、多分支的计算图，并提供 fp16 存储与计算路径、int8 量化推理、模型优化工具以及自定义层扩展机制。在社区组织上，官方维护了 Telegram 群组与 Discord 频道，国内还有多个技术交流 QQ 群，例如技术交流群 637093648、MLIR 相关的 Pocky 群 677104663、以及 pnnx 新人群 818998520，遇到问题可以直接在这些渠道讨论。此外，官方还通过 Codecov 持续展示测试覆盖率，通过 GitHub Actions 在每个平台上做 CI 构建，保证主干版本始终处于可编译、可发布的状态。封面沿用本文既有官方仓库图，不再改动。

三、环境要求

根据 README 的说明，使用 ncnn 时需满足以下条件：

• 首选预编译包：官方在每个 Release 中都提供了覆盖全平台的预编译库，优先下载使用，可省去本地编译的麻烦。预编译包既提供静态库也提供动态库（shared），方便按链接方式选择。
• CPU 后端：纯 CPU 推理无需任何额外依赖，自动利用 ARM NEON 指令集与多核调度，这也是 ncnn 在所有移动端设备上的默认路径。
• Vulkan GPU 后端：需要目标平台支持 Vulkan 驱动，Release 包中同时提供带 Vulkan 与纯 CPU（cpuonly）两个变体；没有 Vulkan 驱动时应选择 cpuonly 包。
• 源码编译：需要 CMake 与 C++ 编译器；Linux 下常用 cmake -DCMAKE_BUILD_TYPE=Release -DNCNN_VULKAN=ON -DNCNN_BUILD_EXAMPLES=ON .. 进行配置，打开 Vulkan 与示例开关。
• 模型转换（pnnx）：需要在 PyTorch 环境中执行 pip3 install pnnx；pnnx 内部会完成算子映射、图优化与算子融合，把 PyTorch 计算图翻译为 ncnn 可执行的格式。pnnx 同时支持直接接收 ONNX 文件，命令行用法为 pnnx model.onnx，可省去先导出 TorchScript 的中间步骤。
• 目标平台矩阵：预编译包覆盖 Android、HarmonyOS、iOS（含 Simulator）、macOS、Mac Catalyst、watchOS、tvOS、visionOS、Ubuntu 22.04 / 24.04 / 26.04、Windows（VS2015 / 2017 / 2019 / 2022 / 2026）、WebAssembly 与 WebAssembly64、Linux arm / aarch64 / mips / mips64 / ppc64 / riscv64 / loongarch64，以及树莓派 3/4、NVIDIA Jetson、POWER、全志 D1、龙芯 2K1000、QNX、海思平台等嵌入式目标。其中 Android 还支持 Termux 环境下的构建，HarmonyOS 提供交叉编译方式，Windows 同时支持 Visual Studio 与 MinGW-w64 两条工具链。

四、部署步骤

1. 安装 pnnx（模型转换工具）

官方推荐的入门路径是在 PyTorch 环境中安装 pnnx：

pip3 install pnnx

2. 把 PyTorch 模型导出为 ncnn 模型

下面这段示例定义了一个包含卷积、ReLU、全局均值池化和全连接的小模型，并通过 pnnx 直接导出：

import torch
import torch.nn as nn
import pnnx

class Model(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv = nn.Conv2d(3, 8, 1)
        self.relu = nn.ReLU()
        self.fc = nn.Linear(8, 4)

    def forward(self, x):
        x = self.conv(x)
        x = self.relu(x)
        x = x.mean((2, 3))
        return self.fc(x)

model = Model().eval()

x = torch.rand(1, 3, 224, 224)
pnnx.export(model, "model.pt", (x,))

执行后会在当前目录生成 model.ncnn.param 与 model.ncnn.bin 两个文件，分别描述网络结构与权重数据。.param 是文本格式，可以直接打开查看每一层的类型与参数；.bin 是二进制权重文件。

3. 从 Release 下载预编译库

进入 Release 页面，按目标平台选择对应压缩包即可。Android 平台可下载 ncnn-*-android-vulkan.zip（含 Vulkan）或 ncnn-*-android.zip（纯 CPU），同时还有静态库与 shared 动态库两个变体；HarmonyOS 提供交叉编译产物；iOS 平台提供 ncnn-*-ios-vulkan.zip 以及 Simulator 版本，Apple 全平台还可直接下载合并好的 ncnn-*-apple-vulkan.zip（xcframework）。桌面端方面，macOS、Mac Catalyst、watchOS、tvOS、visionOS 各自都有独立包，Ubuntu 22.04/24.04/26.04 与 Windows VS2015 至 VS2026 也都有对应压缩包。此外 WebAssembly 与 WebAssembly64 两个包适合把模型跑在浏览器里，Linux arm、aarch64、mips、mips64、ppc64、riscv64、loongarch64 等架构则由 CI 持续构建。完整源码包可下载 ncnn-*-full-source.zip。

4. 源码编译（可选）

当预编译包不匹配目标平台时，按官方 how to build 指南操作，通用 Linux 编译命令如下：

git clone --recursive https://github.com/Tencent/ncnn.git
cd ncnn
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DNCNN_VULKAN=ON -DNCNN_BUILD_EXAMPLES=ON ..
cmake --build . -j$(nproc)

注意必须加 --recursive 拉取子模块；如果不需要 GPU 加速，可以把 -DNCNN_VULKAN=ON 改为 OFF；想编译示例工程就保留 -DNCNN_BUILD_EXAMPLES=ON。官方 Wiki 还分别给出了 Linux、Windows、macOS、树莓派 3/4、POWER、Android、NVIDIA Jetson、iOS、WebAssembly、全志 D1、龙芯 2K1000 等目标的具体编译步骤，包括交叉编译工具链选择、依赖安装、Xcode / Android Studio 工程集成等细节。

五、使用方法

1. C++ API 加载并推理

#include "net.h"

ncnn::Net net;
net.load_param("model.ncnn.param");
net.load_model("model.ncnn.bin");

ncnn::Mat in(224, 224, 3);

auto ex = net.create_extractor();
ex.input("in0", in);

ncnn::Mat out;
ex.extract("out0", out);

这段代码展示了最核心的三步：先用 load_param 与 load_model 加载网络结构和权重，再创建一个提取器（extractor），通过 input 喂入名为 in0 的输入张量，最后用 extract 取出名为 out0 的输出张量。输入输出的节点名由 pnnx 导出时决定，通常是 in0、out0 这样的命名。

2. Python 绑定推理

import numpy as np
import ncnn

net = ncnn.Net()
net.load_param("model.ncnn.param")
net.load_model("model.ncnn.bin")

x = np.zeros((3, 224, 224), np.float32)
mat = ncnn.Mat(x)

ex = net.create_extractor()
ex.input("in0", mat)

ret, out = ex.extract("out0")
print(np.array(out).shape)

Python 绑定的用法与 C++ 几乎一一对应，区别在于输入直接接受 NumPy 数组，并通过 ncnn.Mat 包装成 ncnn 内部张量，输出也可以用 np.array(out) 转回 NumPy 数组。这种设计让 Python 端的开发体验非常接近直接在 PyTorch 里调试，适合在 PC 上先跑通模型正确性，再把 .param 与 .bin 部署到移动端。

3. 模型转换路径一览

转换完成后，可以用在线模型可视化工具 Netron 打开 .param、.onnx、.pnnx.param 文件检查计算图结构，确认算子是否正确映射。需要注意的是，pnnx 导出时会把模型权重一起固化到 .bin 文件中，.param 里只记录层类型、参数形状与连接关系；如果后续要做量化或模型优化，应使用 ncnnoptimize 工具在指定 flag 下重新生成一对新的 .param 与 .bin，而不是直接手改 .param 文件。对于历史遗留的 Caffe、MXNet、Darknet 模型，官方仍保留了兼容转换器，方便在维护老项目时继续使用 ncnn 推理。

六、核心特性与模型覆盖

README 列出的核心特性包括：无第三方运行时依赖、不要求 BLAS 或 NNPACK；纯 C++ 实现并提供 C API 与 Python 绑定；针对移动端与嵌入式 CPU 做 NEON 优化与多核调度；在支持的平台上提供 Vulkan GPU 加速；采用显式 blob / workspace 分配器设计以实现低内存占用；支持多输入、多输出、多分支的计算图；通过 pnnx 完成 PyTorch / ONNX 转换，并保留对老模型格式的兼容转换器；支持 fp16 存储与计算路径、int8 量化推理、模型优化以及自定义层；支持对 .param 与 .bin 模型的直接内存引用加载，适合把模型文件直接编进 App 资源。

在模型覆盖方面，ncnn 对经典移动端 CNN 负载支持非常扎实。分类主干网络覆盖 VGG、AlexNet、GoogleNet、Inception、ResNet、DenseNet、SENet、SqueezeNet、MobileNet、ShuffleNet、MNasNet，这些是图像分类和特征提取最常用的骨干结构。检测与人脸方向覆盖 SSD、Faster R-CNN、R-FCN、MTCNN、RetinaFace、SCRFD、YOLOv2、YOLOv3、YOLOv4、YOLOv5、YOLOv7、YOLOv8、YOLOX、NanoDet，基本涵盖了从早期两阶段检测到单阶段实时检测的主流方案。分割、姿态与 OCR 方向覆盖 FCN、PSPNet、UNet、YOLACT、SimplePose 以及 PP-OCR 示例，可用于语义分割、实例分割、关键点检测和文字识别。音频、生成式与语言类负载则由社区项目和示例覆盖。算子级别的支持状态可查阅 PyTorch 算子支持表、ONNX 算子支持表 以及 算子参数权重表。

官方还收录了一批示例工程，例如图像生成方向的 zimage-ncnn-vulkan，用 ncnn + Vulkan 在本地跑 Z-Image 生成；大模型 / 向量 / 视觉语言方向的 ncnn_llm，演示 LLM、embedding 与多模态模型的推理；Android 分类示例 ncnn-android-squeezenet；Android 风格迁移示例 ncnn-android-styletransfer；Android 检测示例 ncnn-android-mobilenetssd、ncnn-android-yolov5、ncnn-android-yolov7、ncnn-android-scrfd；人脸识别示例 mtcnn_ncnn；Qt 与 Android 集成的加密库示例；上色示例 ncnn-colorization-siggraph17；Fortran 绑定 ncnn-fortran；以及嵌入式实时语音识别示例 sherpa。这些示例覆盖了从分类、检测、人脸、风格迁移到语音识别、图像生成的完整链路，可以直接作为业务接入的参考模板。

需要补充说明的是，README 同时指出 ncnn 如今的应用范围早已超出单纯的 CNN 部署：借助社区项目和算子支持，音频、生成式、语言模型类负载也能在支持的算子上跑起来。在发布与集成方面，官方每个 Release 都会通过 GitHub Actions 持续构建全平台产物，并在仓库主页用一张大表展示每个平台的构建状态，开发者可以一眼确认目标平台是否有现成包可用。

七、常见问题（FAQ）

• 如何从零上手？ 官方推荐路径是 PyTorch → pnnx → ncnn，配合 pnnx 文档与 C++ 示例走一遍导出与推理流程。
• 结果不对怎么办？ 查阅 FAQ-ncnn-produce-wrong-result。
• 运行时报错怎么办？ 查阅 FAQ-ncnn-throw-error。
• Vulkan 相关问题？ 见 FAQ-ncnn-vulkan。
• 想自定义算子？ 参考自定义层分步指南与 plugin 工具。
• 底层算子 API？ 见 low-level operation API。
• 模型文件格式说明？ 见 param and model file spec。
• 老教程？ 官方保留了 use ncnn with AlexNet 及其中文版，适合新手理解整套流程。
• 结构化问答？ 官方整理了 deepwiki 可供 AI 问答。
• 如何参与贡献？ 欢迎在 GitHub 上提交 Issue 或 Pull Request，代码规范与构建说明见仓库根目录与 Wiki；贡献者名单会自动汇总到仓库的 contributors 页面，官方也会对优秀贡献者给予致谢。
• 如何查看支持哪些算子？ 除了前面提到的 PyTorch 与 ONNX 算子支持表，Wiki 上还维护了一份算子参数权重表，列出每个算子的输入输出形状与权重格式，便于开发者排查转换问题。

八、跳转链接

• 项目主页：https://github.com/Tencent/ncnn
• 最新 Release：https://github.com/Tencent/ncnn/releases/latest
• 构建指南：how to build ncnn library
• PyTorch/ONNX 转换：use ncnn with PyTorch or ONNX
• Python API：python 目录
• 示例工程：examples 目录
• 社区：Telegram、Discord