Tencent/ncnn · 上手攻略

仓库：Tencent/ncnn
链接：https://github.com/Tencent/ncnn
分类：AI / 深度学习推理框架
作者：Tom
更新：2026-07-14

这是什么

ncnn 是腾讯开源的高性能神经网络推理框架，专门针对移动端、嵌入式设备和桌面端场景优化。它的核心特点是无第三方运行时依赖（pure C++ 实现）、支持 CPU 和 Vulkan GPU 双后端，可将 PyTorch / ONNX 模型直接部署到手机、PC、浏览器或边缘设备上。

腾讯内部已大规模落地：QQ、Qzone、微信、天天 P 图等产品均在用。

最新版本（参考 releases 页面）：ncnn-20260526（2025 年中），支持平台覆盖 Linux / Windows / macOS / Android / iOS / HarmonyOS / Raspberry Pi / NVIDIA Jetson / WebAssembly 等。

解决什么问题

在服务器端跑深度学习模型很成熟，但到了手机或嵌入式设备上，TensorFlow PyTorch 的 C++ 运行时太重、推理太慢、功耗太高。ncnn 的目标就是把模型推理这件事搬到端侧，做到：

零依赖：纯 C++，不依赖任何第三方 ML 库，直接编译进你的 App
极小体积：针对 ARM CPU 优化，库文件小（Android AAR 约几 MB）
高效率：大量手写 SIMD 优化（NEON、ASIMD）、内存复用、Winograd 算法
多后端：CPU（Fp32/Fp16/Int8）、Vulkan GPU（移动端主流 GPU 加速）
跨平台：iOS、Android、macOS、Linux、Windows、WebAssembly、HarmonyOS……

快速安装

方式一：直接下载预编译包（推荐新手）

Releases 页面：https://github.com/Tencent/ncnn/releases/latest

按平台下载对应压缩包：

# Linux
wget https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-linux.zip

# Android (Vulkan)
wget https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-android-vulkan.zip

# iOS
wget https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ios.zip

# macOS
wget https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-macos.zip

解压后 include 目录即是头文件，lib 目录是静态库（.a 或 .so）。

方式二：从源码编译

Linux / macOS：

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

Android（需要 NDK）：

mkdir build-android && cd build-android
cmake .. -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI="arm64-v8a" \
  -DANDROID_PLATFORM=android-24 \
  -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

详细构建说明参考：How to Build ncnn

方式三：Python 安装（ncnn Python 绑定）

pip install ncnn

⚠️ 注意：ncnn Python 包功能相对 C++ API 有限，新版支持情况建议查看 python/ 目录最新说明。

核心用法

整体流程

PyTorch 模型 → pnnx 转换 → ncnn 模型文件（.param + .bin）→ C++ / Python 推理

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

pip install pnnx

pnnx 是新一代转换工具，推荐直接走 PyTorch → ncnn，不走 ONNX 中转（避开 ONNX 算子兼容性坑）。

Step 2：定义并导出 PyTorch 模型

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)

# 导出（生成 model.pt + model.ncnn.param + model.ncnn.bin）
pnnx.export(model, "model.pt", (x,))

输出三个文件： - model.pt — TorchScript 备份 - model.ncnn.param — 模型结构（文本） - model.ncnn.bin — 模型权重（二进制）

Step 3：C++ 推理

#include "net.h"

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

// 创建输入 Mat（HWC 格式，RGB）
ncnn::Mat in(224, 224, 3);
// 填充数据... (in.channel(i)[row * 224 + col] = value)

auto ex = net.create_extractor();
ex.input("in0", in);   // "in0" 来自 .param 文件的输入 blob 名称

ncnn::Mat out;
ex.extract("out0", out); // "out0" 来自 .param 文件的输出 blob 名称

// out.h、out.w、out.c 为输出维度
printf("output shape: %d x %d x %d\n", out.w, out.h, out.c);

Step 4：Python 推理

import numpy as np
import ncnn

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

# 创建输入（CHW 格式，float32）
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)  # 例如: (1, 4, 1, 1)

常用工具

工具	用途
`pnnx`	PyTorch / ONNX → ncnn 模型转换（推荐工具）
`ncnn2mem`	将 .param + .bin 合并加密为 .mem，方便发行
`ncnnoptimize`	对模型做图优化（融合、剪枝常量）
`pnnx` (standalone)	命令行版，无需 Python 环境
pnnx.js	浏览器端 GUI 转换（基于 WASM，不过服务器）

典型适用场景

场景	说明
手机 App 内嵌 AI	图像分类、风格迁移、人脸检测、AR 滤镜等
嵌入式 AIoT 设备	树莓派、Jetson、算力棒等边缘推理
桌面端 AI 工具	无需 Python 环境的本地 AI 推理
WebAssembly 浏览器端推理	纯前端跑模型，保护隐私
HarmonyOS / iOS 原生 App	移动端跨平台 AI 能力
游戏内 AI	游戏中实时目标检测/姿态估计

坑与注意

.param 文件 blob 名称必须匹配：输入输出 blob 名称（如 "in0"、"out0"）来自 .param 文件定义，不要猜，用打印或阅读 .param 文件确认。
输入数据格式是 HWC（高度×宽度×通道）：C++ API 里 ncnn::Mat in(w, h, c) 是 HWC 顺序，与 PyTorch 的 CHW 不同，转换时需注意数据排布。
Int8 量化需要校准数据集：只用 fp16 或 int8 加速需要额外跑量化步骤，文档参考 ncnn 量化 wiki。
pnnx 不支持所有 PyTorch 算子：复杂自定义层、动态控制流（if/loop）可能转换失败，参考 pnnx 支持算子状态表。不确定的算子建议先试 conversion。
Vulkan 后端在部分 Android 设备上不稳定：部分老旧 Mali GPU 驱动有 bug，生产环境建议提供 CPU fallback。
模型文件跨平台不能直接用：.bin 权重在不同平台（ARM vs x86）字节序不同，需在目标平台重新转换或编译 ncnn。
.param 是文本但不能手动改太多：修改后需确保与 .bin 权重严格对齐，否则会出现难以排查的静默错误。

与同类对比

框架	体积	依赖	CPU 优化	GPU	移动端支持	上手难度
ncnn	★最小	零依赖	★★★★★	Vulkan	★★★★★	中
MNN（阿里）	小	零依赖	★★★★	OpenCL/Vulkan	★★★★★	中
TFLite	中	TensorFlow Lite 运行时	★★★	GPU Delegate	★★★★	易
Core ML（Apple）	中	苹果生态	★★★★	苹果 GPU	苹果独享	易（但闭源）
ONNX Runtime	大	libonnxruntime	★★★	CUDA/ROCm	差	中
TensorRT	大	CUDA	★★★★★	NVIDIA GPU	无	难

选 ncnn 的理由：需要真正零依赖、纯移动端/嵌入式优先、腾讯生态内（与微信/QQ 团队技术栈一致）。

一句话推荐结论

移动端深度学习推理选 ncnn——零依赖、极小体积、腾讯生产验证，PyTorch → pnnx → ncnn 三步完成模型部署，是目前端侧 AI 性价比最高的开源方案之一。