설치 및 환경 확인

설치 및 환경 확인#

이 장에서는 qb Compiler를 실행하는 데 필요한 환경, Python 패키지 설치 방법, target device 문자열을 선택하는 방법, 그리고 컴파일러가 명령과 기본 설정을 제대로 인식하는지 확인하는 방법을 설명합니다.

시스템 요구사항#

컴파일에는 Linux 환경을 사용합니다. Python, CUDA, 프레임워크, 컴파일러 의존성을 맞추기 위해 Mobilint 공식 Docker 이미지를 권장합니다.

권장 기준은 다음과 같습니다.

  • Ubuntu 20.04 이상

  • Docker

  • CUDA 이미지를 사용할 경우 NVIDIA Container Toolkit

  • 더 빠른 컴파일을 위한 NVIDIA GPU, 특히 큰 비전 모델과 LLM에서 권장

NVIDIA GPU가 없는 환경에서는 CPU-only Docker 이미지도 사용할 수 있습니다. 이 경우 컴파일 시간이 더 길어질 수 있습니다.

qbcompiler 설치#

qbcompiler wheel 버전의 major/minor와 맞는 Docker 이미지 태그를 사용합니다. 예를 들어 qbcompiler-1.0.* wheel을 설치할 때는 1.0-* Docker 이미지를 사용합니다.

CUDA 이미지 예시는 다음과 같습니다.

docker pull mobilint/qbcompiler:1.0-cuda12.8.1-ubuntu22.04
docker run -it --gpus all --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.0-cuda12.8.1-ubuntu22.04 /bin/bash

모델과 데이터셋이 작업 디렉터리 밖에 있다면 명시적으로 마운트합니다.

docker run -it --gpus all --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  -v {PATH_TO_MODEL_DIR}:/models \
  -v {PATH_TO_DATASET_DIR}:/datasets \
  mobilint/qbcompiler:1.0-cuda12.8.1-ubuntu22.04 /bin/bash

CPU-only 이미지 예시는 다음과 같습니다.

docker pull mobilint/qbcompiler:1.0-cpu-ubuntu22.04
docker run -it --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.0-cpu-ubuntu22.04 /bin/bash

컨테이너 안에서 qbcompiler wheel을 설치합니다.

python -m pip install /path/to/qbcompiler-{VERSION}-py3-none-any.whl

qbcompiler 1.2부터 wheel 파일 이름에는 NPU 이름이 포함되지 않습니다. 예를 들어 1.2.0 wheel 파일 이름은 qbcompiler-1.2.0-py3-none-any.whl입니다. 1.2 이전 wheel에는 qbcompiler-1.1.2+aries2-py3-none-any.whl처럼 local version segment에 NPU 이름이 포함될 수 있으므로, 해당 릴리스에서 제공한 정확한 wheel 파일을 설치합니다.

target device 선택#

모든 MXQ는 target device에 맞게 컴파일됩니다. CLI 옵션과 Python 호출에는 정확한 target device 문자열을 사용합니다.

target device 문자열

NPU 칩

aries-rb

ARIES

regulus-ra

REGULUS

regulus-rb

REGULUS

CLI 옵션 예시:

python -m qbcompiler compile --target-device regulus-rb ...

Python 인자 예시:

target_device = "regulus-rb"

한 target device로 컴파일한 MXQ를 다른 target device에 배포하면 MXQ 로드가 실패하거나 올바르게 실행되지 않을 수 있습니다.

설치 확인#

설치 후 Python 패키지 import를 확인합니다.

python - <<'PY'
import qbcompiler
print(qbcompiler.__version__)
PY

CLI 사용 가능 여부도 확인합니다.

python -m qbcompiler --help
python -m qbcompiler compile --help

핵심 CLI 명령은 다음과 같습니다.

  • compile: 원본 모델에서 MXQ까지 한 번에 생성

  • parse: 원본 모델에서 MBLT 생성

  • quantize: MBLT에서 MXQ 생성

  • dump-config: 기본값 또는 프리셋 기반 설정 파일 생성

프리셋 및 기본 설정 확인#

내장 프리셋 목록을 확인합니다.

python -m qbcompiler presets

주요 프리셋은 다음과 같습니다.

  • classification

  • detection

  • classification_torchvision

  • yolo_640

  • yolo_1280

  • llm

  • llm_fast

  • vision_transformer

  • multimodal

수정하기 전에 설정을 dump합니다.

python -m qbcompiler dump-config --preset classification_torchvision --output compile_config.yaml

반복 가능한 빌드를 위해 이 파일을 시작점으로 사용합니다. CLI와 Python 작업 흐름을 팀 단위로 일치시키려면 설정 파일을 사용하는 방식이 가장 안전합니다.