神经网络压缩框架 (NNCF) 提供了一系列训练后和训练时算法，用于在 OpenVINO™ 中优化神经网络的推理性能，同时将精度损失降至最低。

NNCF 设计用于支持来自 PyTorch、 TorchFX、 ONNX 和 OpenVINO™ 的模型。

NNCF 提供了 示例，展示了如何针对不同用例和模型使用压缩算法。有关使用 NNCF 示例实现的压缩效果，请参阅 NNCF 模型库页面。

该框架以 Python* 包的形式组织，可以独立构建和使用。其架构统一，便于为 PyTorch 等深度学习框架添加不同的压缩算法。

主要特性

训练后压缩算法

训练时压缩算法

• 自动且可配置的模型图转换，以获得压缩后的模型。
• 压缩方法的通用接口。
• GPU 加速层，用于更快地微调压缩模型。
• 分布式训练支持。
• 针对知名第三方仓库（如 huggingface-transformers）提供的 Git 补丁，演示了如何将 NNCF 集成到自定义训练流程中。
• 可将 PyTorch 压缩模型导出为 ONNX* 检查点、SavedModel 或 Frozen Graph 格式，以便直接与 OpenVINO™ 工具包 一起使用。

文档

本文档涵盖了 NNCF 算法和功能的详细信息，这些内容对于贡献代码至 NNCF 至关重要。

NNCF 的最新用户文档可在 此处 获取。

NNCF API 文档请见 此处。

使用方法

训练后量化

NNCF 的 PTQ 是应用 8 位量化最简单的方式。运行该算法只需您的模型和一个小规模（约 300 个样本）的校准数据集。

首选后端是 OpenVINO，但 PyTorch 和 ONNX 也受支持。

import nncf
import openvino as ov
import torch
from torchvision import datasets, transforms

# 实例化未压缩的模型
model = ov.Core().read_model("/model_path")

# 提供验证数据集的一部分，以收集压缩算法所需的统计信息
val_dataset = datasets.ImageFolder("/path", transform=transforms.Compose([transforms.ToTensor()]))
dataset_loader = torch.utils.data.DataLoader(val_dataset, batch_size=1)

# 步骤 1：初始化变换函数
def transform_fn(data_item):
    images, _ = data_item
    return images

# 步骤 2：初始化 NNCF 数据集
calibration_dataset = nncf.Dataset(dataset_loader, transform_fn)
# 步骤 3：运行量化流程
quantized_model = nncf.quantize(model, calibration_dataset)

import nncf
import torch
from torchvision import datasets, models

# 实例化未压缩的模型
model = models.mobilenet_v2()

# 提供验证数据集的一部分，以收集压缩算法所需的统计信息
val_dataset = datasets.ImageFolder("/path", transform=transforms.Compose([transforms.ToTensor()]))
dataset_loader = torch.utils.data.DataLoader(val_dataset)

# 步骤 1：初始化变换函数
def transform_fn(data_item):
    images, _ = data_item
    return images

# 步骤 2：初始化 NNCF 数据集
calibration_dataset = nncf.Dataset(dataset_loader, transform_fn)

# 步骤3：运行量化流水线
量化模型 = nncf.quantize(模型, 校准数据集)

import nncf
import torch.fx
from torchvision import datasets, models

# 实例化您的未压缩模型
模型 = models.mobilenet_v2()

# 提供验证数据集的一部分，以收集压缩算法所需的统计信息
验证数据集 = datasets.ImageFolder("/path", transform=transforms.Compose([transforms.ToTensor()]))
数据加载器 = torch.utils.data.DataLoader(验证数据集)

# 步骤1：初始化转换函数
def transform_fn(data_item):
    图像, _ = data_item
    return 图像

# 步骤2：初始化 NNCF 数据集
校准数据集 = nncf.Dataset(数据加载器, transform_fn)

# 步骤3：将模型导出为 TorchFX 格式
输入形状 = (1, 3, 224, 224)
fx_model = torch.export.export_for_training(模型, args=(ex_input,)).module()
# 或者
# fx_model = torch.export.export(模型, args=(ex_input,)).module()

# 步骤4：运行量化流水线
量化_fx_model = nncf.quantize(fx_model, 校准数据集)

import onnx
import nncf
import torch
from torchvision import datasets

# 实例化您的未压缩模型
onnx_model = onnx.load_model("/model_path")

# 提供验证数据集的一部分，以收集压缩算法所需的统计信息
验证数据集 = datasets.ImageFolder("/path", transform=transforms.Compose([transforms.ToTensor()]))
数据加载器 = torch.utils.data.DataLoader(验证数据集, batch_size=1)

# 步骤1：初始化转换函数
输入名称 = onnx_model.graph.input[0].name
def transform_fn(data_item):
    图像, _ = data_item
    return {输入名称: 图像.numpy()}

# 步骤2：初始化 NNCF 数据集
校准数据集 = nncf.Dataset(数据加载器, transform_fn)
# 步骤3：运行量化流水线
量化模型 = nncf.quantize(onnx_model, 校准数据集)

训练时量化

以下是一个准确率感知量化流水线的示例，其中可以对模型权重和压缩参数进行微调，以获得更高的准确率。

import nncf
import torch
from torchvision import datasets, models

# 实例化您的未压缩模型
模型 = models.mobilenet_v2()

# 提供验证数据集的一部分，以收集压缩算法所需的统计信息
验证数据集 = datasets.ImageFolder("/path", transform=transforms.Compose([transforms.ToTensor()]))
数据加载器 = torch.utils.data.DataLoader(验证数据集)

# 步骤1：初始化转换函数
def transform_fn(data_item):
    图像, _ = data_item
    return 图像

# 步骤2：初始化 NNCF 数据集
校准数据集 = nncf.Dataset(数据加载器, transform_fn)
# 步骤3：运行量化流水线
量化模型 = nncf.quantize(模型, 校准数据集)

# 现在可以将压缩后的模型当作普通的 torch.nn.Module 来使用，
# 以同时对压缩参数和模型权重进行微调。

# 保存量化模块和量化的模型参数
检查点 = {
    'state_dict': 模型.state_dict(),
    'nncf_config': nncf.torch.get_config(模型),
    ... # 其他需要保存的用户自定义对象
}
torch.save(检查点, 路径_to_checkpoint)

# ...

# 加载量化模块和量化的模型参数
恢复检查点 = torch.load(路径_to_checkpoint)
nncf_config = 恢复检查点['nncf_config']
state_dict = 恢复检查点['state_dict']

量化模型 = nncf.torch.load_from_config(模型, nncf_config, 示例输入)
模型.load_state_dict(state_dict)
# ... 剩下的常规 PyTorch 训练流程

演示、教程和示例

为了更快地开始使用 NNCF 驱动的模型压缩，请尝试下面提供的示例笔记本和脚本。

Jupyter* 笔记本教程和演示

现成可运行的 Jupyter* 笔记本教程和演示可用于解释并展示 NNCF 的压缩算法，以优化适用于 OpenVINO 工具包推理的模型：

笔记本教程名称	压缩算法	后端	领域
BERT量化	训练后量化	OpenVINO	NLP
MONAI分割模型量化	训练后量化	OpenVINO	分割
PyTorch模型量化	训练后量化	PyTorch	图像分类
带精度控制的YOLOv11量化	带精度控制的训练后量化	OpenVINO	语音转文本, 目标检测

一个展示OpenVINO转换与推理，以及结合NNCF压缩技术对来自不同领域模型进行优化的笔记本列表：

演示模型	压缩算法	后端	领域
YOLOv8	训练后量化	OpenVINO	目标检测, 关键点检测, 实例分割
EfficientSAM	训练后量化	OpenVINO	图像分割
Segment Anything Model	训练后量化	OpenVINO	图像分割
OneFormer	训练后量化	OpenVINO	图像分割
CLIP	训练后量化	OpenVINO	图像到文本
BLIP	训练后量化	OpenVINO	图像到文本
潜在一致性模型	训练后量化	OpenVINO	文本到图像
Distil-Whisper	训练后量化	OpenVINO	语音到文本
Whisper	训练后量化	OpenVINO	语音到文本
MMS语音识别	训练后量化	OpenVINO	语音到文本
LLM指令遵循	权重压缩	OpenVINO	自然语言处理，指令遵循
LLM聊天机器人	权重压缩	OpenVINO	自然语言处理，聊天机器人

训练后量化与权重压缩示例

展示量化/权重压缩及其相应推理速度提升的精简脚本：

量化感知训练示例

第三方仓库集成

NNCF 可以轻松集成到第三方仓库的训练/评估流程中。

已被使用的项目

• HuggingFace Optimum Intel

  NNCF 被用作 HuggingFace Optimum Intel 中著名 transformers 仓库内的压缩后端。例如，以下命令将 Llama-3.2-3B-Instruct 模型导出为 OpenVINO 格式，并采用 INT4 量化权重：

  optimum-cli export openvino -m meta-llama/Llama-3.2-3B-Instruct --weight-format int4 ./Llama-3.2-3B-Instruct-int4
  

• Ultralytics

  NNCF 已集成到 Intel OpenVINO 导出流程中，从而实现对导出模型的量化。

• ExecuTorch

  NNCF 被用作 ExecuTorch OpenVINO 集成 的主要量化框架。

• torch.compile

  NNCF 被用作 torch.compile OpenVINO 集成 的主要量化框架。

• OpenVINO Training Extensions

  NNCF 已集成到 OpenVINO Training Extensions 中，作为模型优化后端。用户可以基于现有模型模板训练、优化并导出新模型，同时使用 OpenVINO 运行这些导出的模型。

• Microsoft Olive

  NNCF 被用于对 OpenVINO IR 和 ONNX 模型进行量化，以支持 OpenVINO 集成。

安装指南

有关详细的安装说明，请参阅 安装 指南。

NNCF 可以通过 pip 以常规 PyPI 包的形式安装：

pip install nncf

NNCF 也可通过 conda 获取：

conda install -c conda-forge nncf

NNCF 的系统要求取决于所使用的后端。各后端的系统要求及对应版本矩阵可在 installation.md 中找到。

NNCF 压缩模型库

模型列表及其压缩结果可在我们的 NNCF 模型库页面 中找到。

引用

@article{kozlov2020neural,
    title =   {用于快速模型推理的神经网络压缩框架},
    author =  {科兹洛夫、拉扎列维奇、沙姆波罗夫、利亚柳什金、戈尔巴乔夫},
    journal = {arXiv 预印本 arXiv:2002.08679},
    year =    {2020}
}

贡献指南

有关向 NNCF 仓库贡献的指导原则，请参阅 CONTRIBUTING.md 文件。

有用链接

• 文档
• 示例
• 常见问题解答
• Notebooks
• HuggingFace Optimum Intel
• OpenVINO 模型优化指南
• OpenVINO Hugging Face 页面
• OpenVino 性能基准测试页面

遥测

作为 OpenVINO™ 工具包的一部分，NNCF 会收集匿名使用数据，以用于改进 OpenVINO™ 工具。您可以在安装了 NNCF 的 Python 环境中运行以下命令，随时选择退出：

opt_in_out --opt_out

更多信息请参阅 OpenVINO 遥测。

NNCF 快速上手指南

Neural Network Compression Framework (NNCF) 是一个用于优化神经网络推理的开源工具库，支持 OpenVINO、PyTorch、ONNX 和 TorchFX 后端。它提供训练后量化（PTQ）和训练时量化（QAT）等算法，旨在最小化精度损失的前提下提升模型推理速度并减小模型体积。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, Windows 或 MacOS
• Python 版本: 3.10 或更高版本
• 支持的框架:
  • OpenVINO
  • PyTorch
  • ONNX
  • TorchFX (实验性支持)
• 依赖项: 根据您使用的后端，需预先安装对应的深度学习框架（如 torch, onnx, openvino）。

安装步骤

推荐使用 pip 进行安装。国内开发者建议使用清华或阿里镜像源以加速下载。

基础安装：

pip install nncf -i https://pypi.tuna.tsinghua.edu.cn/simple

安装特定后端支持（可选）： 如果需要使用特定的后端功能，可能需要额外安装相关依赖。例如，若未安装 OpenVINO 或 PyTorch，请先安装它们：

# 安装 PyTorch (示例，具体版本请参考 pytorch.org)
pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 OpenVINO
pip install openvino -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

NNCF 最核心的功能是训练后量化 (Post-Training Quantization, PTQ)。以下展示如何使用 NNCF 将模型量化为 8-bit 整数格式。该过程仅需模型文件和少量校准数据集（约 300 个样本）。

场景一：OpenVINO 模型量化（推荐）

这是性能最优的后端组合。

import nncf
import openvino as ov
import torch
from torchvision import datasets, transforms

# 1. 加载未压缩的 OpenVINO 模型
model = ov.Core().read_model("/path/to/your/model.xml")

# 2. 准备校准数据集 (用于收集统计信息)
val_dataset = datasets.ImageFolder("/path/to/dataset", transform=transforms.Compose([transforms.ToTensor()]))
dataset_loader = torch.utils.data.DataLoader(val_dataset, batch_size=1)

# 定义数据转换函数：从 dataloader 中提取输入张量
def transform_fn(data_item):
    images, _ = data_item
    return images

# 初始化 NNCF 数据集
calibration_dataset = nncf.Dataset(dataset_loader, transform_fn)

# 3. 执行量化
quantized_model = nncf.quantize(model, calibration_dataset)

# 保存量化后的模型
ov.save_model(quantized_model, "/path/to/quantized_model.xml")

场景二：PyTorch 模型量化

直接对 PyTorch 模型进行量化，无需转换为中间格式。

import nncf
import torch
from torchvision import datasets, models, transforms

# 1. 实例化 PyTorch 模型
model = models.mobilenet_v2(pretrained=True)
model.eval() # 确保模型处于评估模式

# 2. 准备校准数据集
val_dataset = datasets.ImageFolder("/path/to/dataset", transform=transforms.Compose([transforms.ToTensor()]))
dataset_loader = torch.utils.data.DataLoader(val_dataset)

# 定义数据转换函数
def transform_fn(data_item):
    images, _ = data_item
    return images

# 初始化 NNCF 数据集
calibration_dataset = nncf.Dataset(dataset_loader, transform_fn)

# 3. 执行量化
quantized_model = nncf.quantize(model, calibration_dataset)

# 此时 quantized_model 仍是一个 torch.nn.Module，可直接用于推理或进一步微调

场景三：ONNX 模型量化

import onnx
import nncf
import torch
from torchvision import datasets, transforms

# 1. 加载 ONNX 模型
onnx_model = onnx.load_model("/path/to/your/model.onnx")

# 2. 准备校准数据集
val_dataset = datasets.ImageFolder("/path/to/dataset", transform=transforms.Compose([transforms.ToTensor()]))
dataset_loader = torch.utils.data.DataLoader(val_dataset, batch_size=1)

# 获取输入节点名称
input_name = onnx_model.graph.input[0].name

# 定义数据转换函数 (ONNX 需要字典格式的输入)
def transform_fn(data_item):
    images, _ = data_item
    return {input_name: images.numpy()}

# 初始化 NNCF 数据集
calibration_dataset = nncf.Dataset(dataset_loader, transform_fn)

# 3. 执行量化
quantized_model = nncf.quantize(onnx_model, calibration_dataset)

# 保存量化后的 ONNX 模型
onnx.save(quantized_model, "/path/to/quantized_model.onnx")

提示: 如果量化后精度下降超出预期，可以考虑使用 训练时量化 (Quantization Aware Training, QAT) 对模型进行微调，以恢复精度。详细用法请参考官方文档中的 Training-Time Compression 部分。