examples/notebooks/YOLOX-L.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c3de48b7",
   "metadata": {},
   "source": [
    "# YOLOX-L 모델을 최적화 옵션을 적용해 컴파일하고 실행하기"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0bf4842b",
   "metadata": {},
   "source": [
    "퓨리오사 SDK는 모델을 최적으로 컴파일하고 실행하기 위한 여러 옵션을 제공합니다. 이 문서는 퓨리오사 SDK가 제공하는 옵션을 사용해서 YOLOX-L 모델을 보다 최적으로 컴파일하고 실행하는 예를 보입니다."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12bbb4fc",
   "metadata": {},
   "source": [
    "## 1. 준비"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee61ecda",
   "metadata": {},
   "source": [
    "이 문서에 포함된 예제를 실행하려면, 퓨리오사 SDK 필수 리눅스 패키지 최신 버전을 설치하고 파이썬 실행 환경을 구축해야 합니다. 리눅스 패키지를 아직 설치하지 않았거나 파이썬 실행 환경을 구성하지 않았다면, 아래 두 문서를 참고해 준비할 수 있습니다:\n",
    "\n",
    "* [드라이버, 펌웨어, 런타임 설치 가이드](https://furiosa-ai.github.io/docs/latest/ko/software/installation.html)\n",
    "* [Python 실행 환경 구성](https://furiosa-ai.github.io/docs/latest/ko/software/python-sdk.html#python)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ddfbafa3",
   "metadata": {},
   "source": [
    "필수 리눅스 패키지와 파이썬 실행 환경을 준비하고 나면, 다음 단계로 퓨리오사 SDK 파이썬 패키지와 양자화 도구 추가 패키지 최신 버전을 설치합니다.\n",
    "\n",
    "```console\n",
    "$ pip3 install --upgrade 'furiosa-sdk[quantizer]'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a118baf8",
   "metadata": {},
   "source": [
    "마지막으로, OpenCV에 대한 파이썬 바인딩인 `opencv-python-headless` 패키지가 필요합니다. 아래에서 이미지 파일을 읽어 들이고 전처리를 하기 위해 사용합니다.\n",
    "\n",
    "```console\n",
    "$ pip3 install opencv-python-headless\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "75c65682",
   "metadata": {},
   "source": [
    "### 1.1 YOLOX-L 모델"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "951ad471",
   "metadata": {},
   "source": [
    "YOLOX-L 모델 구현으로는 Megvii 사가 [공개](https://yolox.readthedocs.io/en/latest/demo/onnx_readme.html)한 ONNX 모델 [yolox_l.onnx](https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_l.onnx)을 사용합니다. 해당 모델을 다운로드해서 현재 디렉토리에 저장합니다.\n",
    "\n",
    "```console\n",
    "$ wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_l.onnx\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1020d011",
   "metadata": {},
   "source": [
    "### 1.2 데이터 집합"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "addd508a",
   "metadata": {},
   "source": [
    "양자화 패라미터를 결정하기 위한 캘리브레이션 데이터 집합과 성능을 측정하기 위한 테스트 데이터 집합으로 [COCO 데이터 집합](https://cocodataset.org)을 사용합니다. 2017년도 [검증 데이터 집합](http://images.cocodataset.org/zips/val2017.zip) (1 GB)과 [테스트 데이터 집합](http://images.cocodataset.org/zips/test2017.zip) (6 GB)을 내려 받습니다. 아래 `tree` 명령 출력과 같은 디렉토리 구조를 가지도록, 현재 디렉토리 아래에 `coco` 디렉토리를 만들고 다시 그 `coco` 디렉토리 속으로 내려 받은 데이터 집합 압축 파일들을 풀어 줍니다.\n",
    "\n",
    "```console\n",
    "$ mkdir coco\n",
    "\n",
    "$ wget http://images.cocodataset.org/zips/val2017.zip\n",
    "$ unzip -d coco val2017.zip\n",
    "\n",
    "$ wget http://images.cocodataset.org/zips/test2017.zip\n",
    "$ unzip -d coco test2017.zip\n",
    "\n",
    "$ tree coco\n",
    "coco\n",
    "├── test2017\n",
    "│   ├── 000000000001.jpg\n",
    "│   ├── 000000000016.jpg\n",
    "│   ├── 000000000019.jpg\n",
    "│   ...\n",
    "│   ├── 000000581911.jpg\n",
    "│   └── 000000581918.jpg\n",
    "└── val2017\n",
    "    ├── 000000000139.jpg\n",
    "    ├── 000000000285.jpg\n",
    "    ├── 000000000632.jpg\n",
    "    ...\n",
    "    ├── 000000581615.jpg\n",
    "    └── 000000581781.jpg\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d4e27fd",
   "metadata": {},
   "source": [
    "### 1.3 임포트"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "ae8af1c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os; os.environ[\"NPU_COMPLETION_CYCLES\"] = \"0\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "3c40a9c0",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "libfuriosa_hal.so --- v2.0, built @ 5423ba8\n",
      "libfuriosa_hal.so --- v2.0, built @ 5423ba8\n"
     ]
    }
   ],
   "source": [
    "import glob\n",
    "from itertools import islice\n",
    "import time\n",
    "\n",
    "import cv2\n",
    "import numpy as np\n",
    "import onnx\n",
    "import tqdm\n",
    "\n",
    "import furiosa.runtime.session\n",
    "from furiosa.optimizer import optimize_model\n",
    "from furiosa.quantizer import quantize, Calibrator, CalibrationMethod"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87d84e50",
   "metadata": {},
   "source": [
    "## 2. YOLOX-L 모델"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36725719",
   "metadata": {},
   "source": [
    "YOLOX-L 모델을 메모리로 읽어 들입니다."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "670e87fa",
   "metadata": {},
   "outputs": [],
   "source": [
    "model = onnx.load_model(\"yolox_l.onnx\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4523cc2",
   "metadata": {},
   "source": [
    "해당 모델은 아래 `preproc` 함수를 사용해 전처리한 이미지 데이터 집합을 사용해 훈련되어 있습니다. `preproc` 전처리 함수가 하는 일을 구체적으로 기술하면, 2번째 줄부터 13번째 줄까지는 이미지 데이터 크기를 모델 입력 크기로 변환합니다. 원본 이미지 가로세로비를 그대로 유지한 채 확대 혹은 축소하고, 여백을 값 114을 가진 픽셀들로 채웁니다. 그 다음, 15번째 줄에서 채널(C) 축을 맨 앞으로 옮깁니다. 즉, HxWxC 형태의 데이터를 CxHxW 형태의 데이터로 변환합니다. 마지막으로 16번째 줄에서 uint8 값을 float32 값으로 변환합니다. 전체적으로, 이미지를 다루는 모델 입력에 대해 자주 사용하는 전처리 유형입니다."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4aee6de5",
   "metadata": {},
   "source": [
    "https://github.com/Megvii-BaseDetection/YOLOX/blob/68408b4083f818f50aacc29881e6f97cd19fcef2/yolox/data/data_augment.py#L142-L158"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "18886593",
   "metadata": {},
   "outputs": [],
   "source": [
    "def preproc(img, input_size, swap=(2, 0, 1)):\n",
    "    if len(img.shape) == 3:  # line 2\n",
    "        padded_img = np.ones((input_size[0], input_size[1], 3), dtype=np.uint8) * 114\n",
    "    else:\n",
    "        padded_img = np.ones(input_size, dtype=np.uint8) * 114\n",
    "\n",
    "    r = min(input_size[0] / img.shape[0], input_size[1] / img.shape[1])\n",
    "    resized_img = cv2.resize(\n",
    "        img,\n",
    "        (int(img.shape[1] * r), int(img.shape[0] * r)),\n",
    "        interpolation=cv2.INTER_LINEAR,\n",
    "    ).astype(np.uint8)\n",
    "    padded_img[: int(img.shape[0] * r), : int(img.shape[1] * r)] = resized_img  # line 13\n",
    "\n",
    "    padded_img = padded_img.transpose(swap)  # line 15\n",
    "    padded_img = np.ascontiguousarray(padded_img, dtype=np.float32)  # line 16\n",
    "    return padded_img, r"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ead12227",
   "metadata": {},
   "source": [
    "## 3. 캘리브레이션과 양자화"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2081f744",
   "metadata": {},
   "source": [
    "양자화 패라미터를 결정하기 위해 사용할 캘리브레이션 데이터 집합을 준비합니다. 이 예에서는 빠른 시연을 위해 임의로 COCO 검증 데이터 집합에 속한 100개의 이미지를 사용합니다. 참고로, MLPerf 벤치마크는 500개 이미지를 캘리브레이션 데이터 집합으로 사용합니다. 훈련할 때 사용한 전처리(`preproc`)와 동일한 전처리를 사용하는 점에 주목합니다. 2번째 줄에서 `[np.newaxis, ...]` 부분은 CxHxW 모양의 데이터를 모델 입력이 요구하는 1xCxHxW 모양의 값으로 변환합니다."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "390a8129",
   "metadata": {},
   "outputs": [],
   "source": [
    "calibration_dataset = [\n",
    "    preproc(cv2.imread(image), (640, 640))[0][np.newaxis, ...]  # line 2\n",
    "    for image in islice(glob.iglob(\"coco/val2017/*.jpg\"), 100)\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21006e47",
   "metadata": {},
   "source": [
    "앞에서 준비한 YOLOX-L 모델과 캘리브레이션 데이터 집합을 이용하여 캘리브레이션과 양자화를 수행합니다. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "62d5eef9",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Calibration: 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 100/100 [02:41<00:00,  1.61s/images]\n"
     ]
    }
   ],
   "source": [
    "model = optimize_model(model)\n",
    "\n",
    "calibrator = Calibrator(model, CalibrationMethod.MIN_MAX_ASYM)\n",
    "\n",
    "for calibration_data in tqdm.tqdm(calibration_dataset, desc=\"Calibration\", unit=\"images\", mininterval=0.5):\n",
    "    calibrator.collect_data([[calibration_data]])\n",
    "\n",
    "ranges = calibrator.compute_range()\n",
    "\n",
    "model_quantized = quantize(model, ranges)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d81a28f9",
   "metadata": {},
   "source": [
    "## 4. 컴파일 최적화 옵션"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "551630b0",
   "metadata": {},
   "source": [
    "퓨리오사 SDK는 사용자가 컴파일 과정의 다양한 단계를 대상 모델에 맞게 미세 조정할 수 있도록 하는 여러 옵션을 제공합니다. 그러한 옵션 중의 하나로 이미지 관련 모델에서 자주 사용하는 형태의 전처리 코드의 일부를 퓨리오사 NPU 환경 하에서 보다 효율적으로 실행할 수 있는 코드로 변환하는 옵션이 있습니다. 이 옵션을 우리 예에 적용하기 위해, 우선 전처리 함수 `preproc`에서 축의 순서를 교환하는 15번째 줄과 정숫값을 소숫값으로 변환하는 16번째 줄을 주석 처리하여 전처리에서 제외합니다."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "d9c6c887",
   "metadata": {},
   "outputs": [],
   "source": [
    "def preproc(img, input_size, swap=(2, 0, 1)):\n",
    "    if len(img.shape) == 3:\n",
    "        padded_img = np.ones((input_size[0], input_size[1], 3), dtype=np.uint8) * 114\n",
    "    else:\n",
    "        padded_img = np.ones(input_size, dtype=np.uint8) * 114\n",
    "\n",
    "    r = min(input_size[0] / img.shape[0], input_size[1] / img.shape[1])\n",
    "    resized_img = cv2.resize(\n",
    "        img,\n",
    "        (int(img.shape[1] * r), int(img.shape[0] * r)),\n",
    "        interpolation=cv2.INTER_LINEAR,\n",
    "    ).astype(np.uint8)\n",
    "    padded_img[: int(img.shape[0] * r), : int(img.shape[1] * r)] = resized_img\n",
    "\n",
    "#     padded_img = padded_img.transpose(swap)  # line 15\n",
    "#     padded_img = np.ascontiguousarray(padded_img, dtype=np.float32)  # line 16\n",
    "    return padded_img, r"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c55c952",
   "metadata": {},
   "source": [
    "16번째 줄의 정숫값을 소숫값으로 변환하는 전처리 코드를 제외한 것과 관련하여, 아래 코드와 같이 양자화 시에 with_quantize=False의 인자를 제공함으로써\n",
    "양자화 모델이 소숫값이 아닌 정숫값 입력을 받도록 지정할 수 있습니다."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "02dd3600",
   "metadata": {},
   "outputs": [],
   "source": [
    "model_quantized = quantize(model, ranges, with_quantize=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10a5ed82",
   "metadata": {},
   "source": [
    "그런 다음, 아래 코드처럼 설정 `\"permute_input\": [[0, 2, 3, 1]]`을 지정하여, 1xHxWxC 입력을 축 순서 교환없이 곧장 받아들일 수 있도록 모델을 변환합니다. 이렇게 컴파일러에게 전처리에 대한 정보를 제공하면, 컴파일러는 위에서 주석 처리한 코드와 동일한 계산 결과를 가지면서도 전처리 다음에 오는 실제 모델 실행 코드와 더 매끄럽게 이어져 전체 실행 시간을 단축시키는 코드를 산출할 수 있습니다."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "f4593209",
   "metadata": {},
   "outputs": [],
   "source": [
    "compiler_config = {\n",
    "    \"permute_input\": \n",
    "        [\n",
    "            [0, 2, 3, 1],\n",
    "        ],\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d91f47ff",
   "metadata": {},
   "source": [
    "## 5. 추론 및 레이턴시(latency) 측정"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfa81ac1",
   "metadata": {},
   "source": [
    "양자화시킨 모델과 위에서 설명한 컴파일 설정을 사용해 세션을 만듭니다. 생성한 세션을 사용해 테스트 데이터 집합에 대해 추론을 합니다. 캘리브레이션할 때와 마찬가지로 빠른 시연을 위해 전체 40,670개 테스트 데이터 이미지 중 임의로 1000개 이미지를 사용합니다. 그리고, 1000개 이미지를 추론하는데 걸린 총 시간을 측정합니다."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "3c03f19d",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Saving the compilation log into /root/.local/state/furiosa/logs/compile-20230202172531-ls78ah.log\n",
      "Using furiosa-compiler 0.9.0-dev (rev: ada3c6888 built at 2023-02-01T23:44:29Z)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[2m2023-02-02T08:25:31.377933Z\u001b[0m \u001b[32m INFO\u001b[0m \u001b[2mnux::npu\u001b[0m\u001b[2m:\u001b[0m Npu (npu0pe0-1) is being initialized\n",
      "\u001b[2m2023-02-02T08:25:31.380454Z\u001b[0m \u001b[32m INFO\u001b[0m \u001b[2mnux\u001b[0m\u001b[2m:\u001b[0m NuxInner create with pes: [PeId(0)]\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\u001b[1m\u001b[2m[1/5]\u001b[0m 🔍   Compiling from dfg to ldfg\n",
      "Done in 236.0478s\n",
      "\u001b[1m\u001b[2m[2/5]\u001b[0m 🔍   Compiling from ldfg to cdfg\n",
      "Done in 0.008801861s\n",
      "\u001b[1m\u001b[2m[3/5]\u001b[0m 🔍   Compiling from cdfg to gir\n",
      "Done in 0.21152857s\n",
      "\u001b[1m\u001b[2m[4/5]\u001b[0m 🔍   Compiling from gir to lir\n",
      "Done in 369.44357s\n",
      "\u001b[1m\u001b[2m[5/5]\u001b[0m 🔍   Compiling from lir to enf\n",
      "Done in 0.34623876s\n",
      "✨  Finished in 606.0598s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[2m2023-02-02T08:36:00.326387Z\u001b[0m \u001b[32m INFO\u001b[0m \u001b[2mnux::npu\u001b[0m\u001b[2m:\u001b[0m NPU (npu0pe0-1) has been destroyed\n",
      "\u001b[2m2023-02-02T08:36:00.327926Z\u001b[0m \u001b[32m INFO\u001b[0m \u001b[2mnux::capi\u001b[0m\u001b[2m:\u001b[0m session has been destroyed\n"
     ]
    }
   ],
   "source": [
    "total_predictions = 0\n",
    "elapsed_time = 0\n",
    "with furiosa.runtime.session.create(model_quantized, compiler_config=compiler_config) as session:\n",
    "    for image in islice(glob.iglob(\"coco/test2017/*.jpg\"), 1000):\n",
    "        inputs = [preproc(cv2.imread(image), (640, 640))[0][np.newaxis, ...]]\n",
    "        start = time.perf_counter_ns()\n",
    "        outputs = session.run(inputs)\n",
    "        elapsed_time += time.perf_counter_ns() - start\n",
    "        total_predictions += 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55234d45",
   "metadata": {},
   "source": [
    "1000개 이미지를 추론하는데 걸린 시간으로부터 평균 레이턴시(latency)를 계산합니다. 퓨리오사 워보이(리비전 A0)와 인텔 제온 골드 6348 프로세서를 장착한 머신에서 14 ms 대의 평균 레이턴시가 측정되었습니다."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "4fade41d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Average Latency: 14.693362643999999 ms\n"
     ]
    }
   ],
   "source": [
    "latency = elapsed_time / total_predictions\n",
    "print(f\"Average Latency: {latency / 1_000_000} ms\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d74d2cff",
   "metadata": {},
   "source": [
    "(주의: 주피터 노트북 상에서 시간을 측정하면 측정 오차가 상당히 클 수 있습니다. [`nbconvert`](https://nbconvert.readthedocs.io/)를 사용해 주피터 노트북으로부터 파이썬 스크립트를 추출하고, 그 파이썬 스크립트를 실행해 시간을 측정하면 보다 안정적인 측정값을 얻을 수 있습니다.)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}