notebooks/122-quantizing-model-with-accuracy-control/122-yolov8-quantization-with-accuracy-control.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Convert and Optimize YOLOv8 with OpenVINO™\n",
    "\n",
    "The YOLOv8 algorithm developed by Ultralytics is a cutting-edge, state-of-the-art (SOTA) model that is designed to be fast, accurate, and easy to use, making it an excellent choice for a wide range of object detection, image segmentation, and image classification tasks.\n",
    "More details about its realization can be found in the original model [repository](https://github.com/ultralytics/ultralytics).\n",
    "\n",
    "This tutorial demonstrates step-by-step instructions on how to run apply quantization with accuracy control to PyTorch YOLOv8.\n",
    "The advanced quantization flow allows to apply 8-bit quantization to the model with control of accuracy metric. This is achieved by keeping the most impactful operations within the model in the original precision. The flow is based on the [Basic 8-bit quantization](https://docs.openvino.ai/2023.0/basic_quantization_flow.html) and has the following differences:\n",
    "\n",
    "- Besides the calibration dataset, a validation dataset is required to compute the accuracy metric. Both datasets can refer to the same data in the simplest case.\n",
    "- Validation function, used to compute accuracy metric is required. It can be a function that is already available in the source framework or a custom function.\n",
    "- Since accuracy validation is run several times during the quantization process, quantization with accuracy control can take more time than the Basic 8-bit quantization flow.\n",
    "- The resulted model can provide smaller performance improvement than the Basic 8-bit quantization flow because some of the operations are kept in the original precision.\n",
    "\n",
    "> **NOTE**: Currently, 8-bit quantization with accuracy control in NNCF is available only for models in OpenVINO representation.\n",
    "\n",
    "The steps for the quantization with accuracy control are described below.\n",
    "\n",
    "<a id=\"0\"></a>\n",
    "The tutorial consists of the following steps:\n",
    "\n",
    "- [Prerequisites](#1)\n",
    "- [Get Pytorch model and OpenVINO IR model](#2)\n",
    "- [Define validator and data loader](#3)\n",
    "- [Prepare calibration and validation datasets](#4)\n",
    "- [Prepare validation function](#5)\n",
    "- [Run quantization with accuracy control](#6)\n",
    "- [Compare Performance of the Original and Quantized Models](#7)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"1\"></a>\n",
    "#### Prerequisites [&#8657;](#0)\n",
    "\n",
    "Install necessary packages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "%pip install -q \"openvino>=2023.1.0\"\n",
    "%pip install \"nncf>=2.6.0\"\n",
    "%pip install -q \"ultralytics==8.0.43\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"2\"></a>\n",
    "## Get Pytorch model and OpenVINO IR model [&#8657;](#0)\n",
    "\n",
    "Generally, PyTorch models represent an instance of the [`torch.nn.Module`](https://pytorch.org/docs/stable/generated/torch.nn.Module.html) class, initialized by a state dictionary with model weights.\n",
    "We will use the YOLOv8 nano model (also known as `yolov8n`) pre-trained on a COCO dataset, which is available in this [repo](https://github.com/ultralytics/ultralytics). Similar steps are also applicable to other YOLOv8 models.\n",
    "Typical steps to obtain a pre-trained model:\n",
    "\n",
    "1. Create an instance of a model class.\n",
    "2. Load a checkpoint state dict, which contains the pre-trained model weights.\n",
    "\n",
    "In this case, the creators of the model provide an API that enables converting the YOLOv8 model to ONNX and then to OpenVINO IR. Therefore, we do not need to do these steps manually."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "import os\n",
    "from pathlib import Path\n",
    "\n",
    "from ultralytics import YOLO\n",
    "from ultralytics.yolo.cfg import get_cfg\n",
    "from ultralytics.yolo.data.utils import check_det_dataset\n",
    "from ultralytics.yolo.engine.validator import BaseValidator as Validator\n",
    "from ultralytics.yolo.utils import DATASETS_DIR\n",
    "from ultralytics.yolo.utils import DEFAULT_CFG\n",
    "from ultralytics.yolo.utils import ops\n",
    "from ultralytics.yolo.utils.metrics import ConfusionMatrix\n",
    "\n",
    "ROOT = os.path.abspath('')\n",
    "\n",
    "MODEL_NAME = \"yolov8n-seg\"\n",
    "\n",
    "model = YOLO(f\"{ROOT}/{MODEL_NAME}.pt\")\n",
    "args = get_cfg(cfg=DEFAULT_CFG)\n",
    "args.data = \"coco128-seg.yaml\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "import openvino as ov\n",
    "\n",
    "\n",
    "model_path = Path(f\"{ROOT}/{MODEL_NAME}_openvino_model/{MODEL_NAME}.xml\")\n",
    "if not model_path.exists():\n",
    "    model.export(format=\"openvino\", dynamic=True, half=False)\n",
    "\n",
    "ov_model = ov.Core().read_model(model_path)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"3\"></a>\n",
    "#### Define validator and data loader [&#8657;](#0)\n",
    "The original model repository uses a `Validator` wrapper, which represents the accuracy validation pipeline. It creates dataloader and evaluation metrics and updates metrics on each data batch produced by the dataloader. Besides that, it is responsible for data preprocessing and results postprocessing. For class initialization, the configuration should be provided. We will use the default setup, but it can be replaced with some parameters overriding to test on custom data. The model has connected the `ValidatorClass` method, which creates a validator class instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "validator = model.ValidatorClass(args)\n",
    "validator.data = check_det_dataset(args.data)\n",
    "data_loader = validator.get_dataloader(f\"{DATASETS_DIR}/coco128-seg\", 1)\n",
    "\n",
    "validator.is_coco = True\n",
    "validator.class_map = ops.coco80_to_coco91_class()\n",
    "validator.names = model.model.names\n",
    "validator.metrics.names = validator.names\n",
    "validator.nc = model.model.model[-1].nc\n",
    "validator.nm = 32\n",
    "validator.process = ops.process_mask\n",
    "validator.plot_masks = []"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"4\"></a>\n",
    "#### Prepare calibration and validation datasets [&#8657;](#0)\n",
    "\n",
    "We can use one dataset as calibration and validation datasets. Name it `quantization_dataset`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "from typing import Dict\n",
    "\n",
    "import nncf\n",
    "\n",
    "\n",
    "def transform_fn(data_item: Dict):\n",
    "    input_tensor = validator.preprocess(data_item)[\"img\"].numpy()\n",
    "    return input_tensor\n",
    "\n",
    "\n",
    "quantization_dataset = nncf.Dataset(data_loader, transform_fn)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"5\"></a>\n",
    "#### Prepare validation function [&#8657;](#0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "from functools import partial\n",
    "\n",
    "import torch\n",
    "from nncf.quantization.advanced_parameters import AdvancedAccuracyRestorerParameters\n",
    "\n",
    "\n",
    "def validation_ac(\n",
    "    compiled_model: ov.CompiledModel,\n",
    "    validation_loader: torch.utils.data.DataLoader,\n",
    "    validator: Validator,\n",
    "    num_samples: int = None,\n",
    ") -> float:\n",
    "    validator.seen = 0\n",
    "    validator.jdict = []\n",
    "    validator.stats = []\n",
    "    validator.batch_i = 1\n",
    "    validator.confusion_matrix = ConfusionMatrix(nc=validator.nc)\n",
    "    num_outputs = len(compiled_model.outputs)\n",
    "\n",
    "    counter = 0\n",
    "    for batch_i, batch in enumerate(validation_loader):\n",
    "        if num_samples is not None and batch_i == num_samples:\n",
    "            break\n",
    "        batch = validator.preprocess(batch)\n",
    "        results = compiled_model(batch[\"img\"])\n",
    "        if num_outputs == 1:\n",
    "            preds = torch.from_numpy(results[compiled_model.output(0)])\n",
    "        else:\n",
    "            preds = [\n",
    "                torch.from_numpy(results[compiled_model.output(0)]),\n",
    "                torch.from_numpy(results[compiled_model.output(1)]),\n",
    "            ]\n",
    "        preds = validator.postprocess(preds)\n",
    "        validator.update_metrics(preds, batch)\n",
    "        counter += 1\n",
    "    stats = validator.get_stats()\n",
    "    if num_outputs == 1:\n",
    "        stats_metrics = stats[\"metrics/mAP50-95(B)\"]\n",
    "    else:\n",
    "        stats_metrics = stats[\"metrics/mAP50-95(M)\"]\n",
    "    print(f\"Validate: dataset length = {counter}, metric value = {stats_metrics:.3f}\")\n",
    "    \n",
    "    return stats_metrics\n",
    "\n",
    "\n",
    "validation_fn = partial(validation_ac, validator=validator)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"6\"></a>\n",
    "## Run quantization with accuracy control [&#8657;](#0)\n",
    "You should provide the calibration dataset and the validation dataset. It can be the same dataset. \n",
    "  - parameter `max_drop` defines the accuracy drop threshold. The quantization process stops when the degradation of accuracy metric on the validation dataset is less than the `max_drop`. The default value is 0.01. NNCF will stop the quantization and report an error if the `max_drop` value can’t be reached.\n",
    "  - `drop_type` defines how the accuracy drop will be calculated: ABSOLUTE (used by default) or RELATIVE.\n",
    "  - `ranking_subset_size` - size of a subset that is used to rank layers by their contribution to the accuracy drop. Default value is 300, and the more samples it has the better ranking, potentially. Here we use the value 25 to speed up the execution. \n",
    "\n",
    "> **NOTE**: Execution can take tens of minutes and requires up to 15 GB of free memory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "quantized_model = nncf.quantize_with_accuracy_control(\n",
    "    ov_model,\n",
    "    quantization_dataset,\n",
    "    quantization_dataset,\n",
    "    validation_fn=validation_fn,\n",
    "    max_drop=0.01,\n",
    "    preset=nncf.QuantizationPreset.MIXED,\n",
    "    advanced_accuracy_restorer_parameters=AdvancedAccuracyRestorerParameters(\n",
    "        ranking_subset_size=25\n",
    "    ),\n",
    ")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"7\"></a>\n",
    "## Compare Accuracy and Performance of the Original and Quantized Models [&#8657;](#0)\n",
    "Now we can compare metrics of the Original non-quantized OpenVINO IR model and Quantized OpenVINO IR model to make sure that the `max_drop` is not exceeded."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "core = ov.Core()\n",
    "quantized_compiled_model = core.compile_model(model=quantized_model, device_name='CPU')\n",
    "compiled_ov_model = core.compile_model(model=ov_model, device_name='CPU')\n",
    "\n",
    "pt_result = validation_ac(compiled_ov_model, data_loader, validator)\n",
    "quantized_result = validation_ac(quantized_compiled_model, data_loader, validator)\n",
    "\n",
    "\n",
    "print(f'[Original OpenVino]: {pt_result:.4f}')\n",
    "print(f'[Quantized OpenVino]: {quantized_result:.4f}')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And compare performance. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "# Set model directory\n",
    "MODEL_DIR = Path(\"model\")\n",
    "MODEL_DIR.mkdir(exist_ok=True)\n",
    "\n",
    "ir_model_path = MODEL_DIR / 'ir_model.xml'\n",
    "quantized_model_path = MODEL_DIR / 'quantized_model.xml'\n",
    "\n",
    "# Save models to use them in the commandline banchmark app\n",
    "ov.save_model(ov_model, ir_model_path, compress_to_fp16=False)\n",
    "ov.save_model(quantized_model, quantized_model_path, compress_to_fp16=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Inference Original model (OpenVINO IR)\n",
    "! benchmark_app -m $ir_model_path -shape \"[1,3,640,640]\" -d CPU -api async"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Inference Quantized model (OpenVINO IR)\n",
    "! benchmark_app -m $quantized_model_path -shape \"[1,3,640,640]\" -d CPU -api async"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}