# 설치 및 환경 확인

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

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

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

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

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

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

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

Python 인자 예시:

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

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

## 설치 확인

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

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

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

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

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

- `compile`: 원본 모델에서 MXQ까지 한 번에 생성
- `parse`: 원본 모델에서 MBLT 생성
- `quantize`: MBLT에서 MXQ 생성
- `dump-config`: 기본값 또는 프리셋 기반 설정 파일 생성

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

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

```bash
python -m qbcompiler presets
```

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

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