# 설치 및 환경 확인

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

(system-requirements)=

## 시스템 요구사항

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

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

- Ubuntu 20.04 이상
- Docker
- CUDA 이미지를 사용할 경우 NVIDIA Container Toolkit
- 더 빠른 컴파일을 위한 NVIDIA GPU, 특히 큰 비전 모델과 LLM에서 권장

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

(install-qbcompiler)=

## qbcompiler 설치

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

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

```bash
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
```

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

```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 이미지 예시는 다음과 같습니다.

```bash
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을 설치합니다.

```bash
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 파일을 설치합니다.

(select-the-target-device)=

## 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 옵션 예시:

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

Python 인자 예시:

```python
target_device = "regulus-rb"
```

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

(verify-the-installation)=

## 설치 확인

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

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

CLI 사용 가능 여부도 확인합니다. 아래 형태는 모든 릴리스에서 동작합니다.

```bash
python -m qbcompiler --help
python -m qbcompiler compile --help
```

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

```bash
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 이상)

(check-presets-and-the-default-config)=

## 프리셋 및 기본 설정 확인

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

```bash
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합니다.

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

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