설치 및 환경 확인

설치 및 환경 확인#

이 장에서는 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.3-cuda12.8.1-ubuntu22.04
docker run -it --gpus all --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.3-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.3-cuda12.8.1-ubuntu22.04 /bin/bash

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

docker pull mobilint/qbcompiler:1.3-cpu-ubuntu22.04
docker run -it --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.3-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.3.0 wheel 파일 이름은 qbcompiler-1.3.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

regulus-rb-usb

REGULUS

regulus-rb-usb는 qbcompiler 1.3부터 사용할 수 있습니다. USB로 연결된 REGULUS 디바이스를 대상으로 하며 NPU 입출력 경계가 부동소수점이 아니므로, regulus-rb용으로 빌드한 MXQ와 regulus-rb-usb용으로 빌드한 MXQ는 서로 호환되지 않습니다.

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

qbcompiler 1.3부터는 설치 시 qbcompiler 명령도 PATH에 등록되며, 동일한 진입점을 동일한 출력 프로토콜로 실행합니다.

qbcompiler --help

1.2에는 이 명령이 없으므로 command not found가 나온다면 설치 실패가 아니라 해당 릴리스가 이 기능이 추가되기 이전 버전이라는 뜻입니다. 이 매뉴얼의 나머지 부분이 python -m qbcompiler 형태를 쓰는 이유이기도 합니다. 새 명령 자체를 소개하는 릴리즈 노트만 예외입니다. 1.3에서는 qbcompiler로 바꿔 써도 됩니다.

1.2와의 차이는 표기법만이 아닙니다. compile과 quantize 서브커맨드는 1.2.0에서 아예 동작하지 않았습니다. target device 없이 컴파일 진입점을 호출해 내부 오류로 끝났기 때문에, 이 매뉴얼의 명령 예시는 어느 표기를 쓰든 1.3이 필요합니다. parse, presets, dump-config, check는 영향이 없습니다.

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

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

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

  • quantize: MBLT에서 MXQ 생성

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

  • info: MBLT의 provenance 기록을 JSON으로 출력 (qbcompiler 1.3 이상)

프리셋 및 기본 설정 확인#

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

QBCOMPILER_JSONL=1 python -m qbcompiler presets

presets와 check는 JSONL 채널로 결과를 냅니다. 채널이 꺼져 있으면 아무것도 출력하지 않으므로, 출력을 보려면 QBCOMPILER_JSONL=1을 설정하세요. 결과가 비어 있다고 해서 설치가 실패한 것은 아닙니다.

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

  • 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 작업 흐름을 팀 단위로 일치시키려면 설정 파일을 사용하는 방식이 가장 안전합니다.