# 컴파일 기본 흐름

qb Compiler는 하나의 파이프라인을 중심으로 동작합니다.

```text
원본 모델 -> MBLT -> MXQ
```

`compile` 명령 하나로 전체 파이프라인을 실행할 수 있습니다. 더 세밀한 제어가 필요하면 `parse`와 `quantize`로 나누어 두 핵심 단계를 각각 실행하면 됩니다.

MXQ를 생성하면 target device 정보뿐 아니라 `inferenceScheme`으로 지정한 런타임 코어 모드도 함께 산출물에 반영됩니다. 이미 생성된 MXQ는 실행 시점에 다른 코어 모드로 임의로 바꿀 수 없으므로, 필요한 코어 모드가 달라지면 해당 `inferenceScheme` 값으로 MXQ를 다시 생성해야 합니다. `single`은 독립적인 Local Core 실행, `multi`는 cluster 단위 4-batch 모드, `global4`/`global8`은 4개 또는 8개 Local Core가 한 입력을 함께 처리하는 모드입니다. 지원 값과 코어 모드 링크는 [참조 — inferenceScheme](reference.md#inferencescheme)에서 확인할 수 있습니다.

## 전체 컴파일

일반적인 프로덕션 빌드에는 `compile`을 사용하세요.

```bash
python -m qbcompiler compile \
  --model model.onnx \
  --backend onnx \
  --calib-data-path calibration/resnet50 \
  --target-device regulus-rb \
  --output model.mxq
```

Python으로 전체 컴파일을 실행하는 예시입니다.

```python
from qbcompiler import mxq_compile

mxq_compile(
    model="model.onnx",
    backend="onnx",
    calib_data_path="calibration/resnet50",
    target_device="regulus-rb",
    save_path="model.mxq",
)
```

컴파일러는 원본 모델을 파싱한 뒤, 파싱된 그래프를 캘리브레이션·양자화하고, target device에 맞는 컴파일을 적용해 MXQ를 생성합니다.

## `parse`: 원본 모델을 MBLT로 변환

`parse`는 원본 프레임워크 형식을 읽어 MBLT를 생성합니다.

```bash
python -m qbcompiler parse \
  --model model.onnx \
  --backend onnx \
  --output model.mblt
```

다음과 같은 경우 이 단계를 따로 사용합니다.

- 파싱된 그래프를 Netron에서 확인할 때
- 양자화 전에 레이어 지원 여부를 확인할 때
- 입력 이름과 형상(shape)을 디버깅할 때
- 동일하게 파싱된 모델을 여러 target device나 설정 실험에 재사용할 때

MBLT는 최종 배포 산출물이 아니라, 컴파일러가 파싱한 모델 그래프와 가중치를 담은 중간 산출물입니다. 자세한 내용은 [모델 파싱](model_parsing.md)을 참고하세요.

## `quantize`: MBLT를 MXQ로 변환

`quantize`는 MBLT를 읽어 MXQ를 생성합니다.

```bash
python -m qbcompiler quantize \
  --mblt model.mblt \
  --calib-data-path calibration/resnet50 \
  --output model.mxq
```

이 매뉴얼에서 `quantize`는 MBLT-to-MXQ 전체 단계를 가리킵니다. 캘리브레이션과 양자화는 물론, MXQ 패키지를 만드는 데 필요한 target device별 작업까지 모두 포함합니다. 캘리브레이션 데이터 준비와 양자화 설정은 [모델 양자화](model_quantization.md)를 참고하세요.

다음과 같은 경우 이 단계를 사용합니다.

- MBLT 검토를 이미 마쳤을 때
- 프리셋이나 설정 파일을 비교해야 할 때
- 같은 파싱 결과를 여러 target device 문자열로 컴파일해야 할 때
- 원본 모델을 다시 파싱하지 않고 캘리브레이션이나 양자화만 디버깅할 때

## `compile` vs. `parse` + `quantize`

모델, 캘리브레이션 데이터, target device가 이미 정해져 있다면 전체 컴파일을 사용하세요. 과정이 더 짧고 자동화하기 쉬우며, 빌드 경로도 단순하게 유지됩니다.

모델 구조를 직접 확인해야 하는 작업이라면 `parse`와 `quantize`를 나누어 사용하세요. 지원되지 않는 전처리·후처리가 있는 모델, YOLO 계열 head([비전 모델 입력 처리](vision.md) 참고), [LLM](transformer.md), 혹은 `CPU head`·`NPU body`·`CPU tail` 경계([CPU 오프로딩](cpu_offloading.md) 참고)를 MXQ 생성 전에 확인해야 할 때 특히 유용합니다.

## 주요 산출물 체크리스트

컴파일을 재현할 수 있도록 다음 항목을 보관하세요.

- 원본 모델과 소스 리비전
- 캘리브레이션 샘플 디렉터리 또는 메타데이터 파일
- 컴파일 설정 파일 또는 프리셋 이름([참조 — CompileConfig 스키마](reference.md#compileconfig-schema) 참고)
- target device 문자열
- 단계별로 컴파일했다면 생성된 MBLT
- 생성된 MXQ
- 검증에 사용한 입력과 출력
- 배포 시 `CPU head`/`NPU body`/`CPU tail` 경계가 중요하다면, 추출한 `NPU body` 서브그래프 산출물