# 참조

이 장은 현재 qbcompiler의 명령줄, Python API, 설정 스키마, 지원 입력, 관련 용어에 대한 참조입니다. 기준은 현재 qbcompiler 구현입니다.

## CLI 참조

CLI는 다음 형식으로 실행합니다.

```bash
python -m qbcompiler <command> [options]
```

현재 명령은 `compile`, `parse`, `quantize`, `dump-config`입니다.

| 명령 | 목적 | 주요 옵션 |
| --- | --- | --- |
| `compile` | 모델을 `.mxq`까지 한 번에 컴파일합니다. 내부적으로 임시 `.mblt`를 만든 뒤 quantize합니다. | `--model`, `--output`, `--backend`, `--device`, `--target-device`, `--cpu-offload` / `--no-cpu-offload`, `--config-preset`, `--compile-config`, `--calib-data-path`, `--use-random-calib` / `--no-use-random-calib` |
| `parse` | 입력 모델을 `.mblt` 중간 표현(IR)으로 변환합니다. | `--model`, `--output`, `--backend`, `--device`, `--target-device`, `--cpu-offload` / `--no-cpu-offload`, `--config-preset`, `--compile-config` |
| `quantize` | 실행 가능한 `.mblt` 파일을 `.mxq`로 변환합니다. | `--mblt`, `--output`, `--calib-data-path`, `--use-random-calib` / `--no-use-random-calib`, `--config-preset`, `--compile-config`, `--device` |
| `dump-config` | 기본값 또는 프리셋 기반 `CompileConfig` 템플릿을 작성합니다. | `--output`, `--preset` |

`--backend` 기본값은 `onnx`입니다. `--calib-data-path`는 여러 번 지정할 수 있습니다. `--compile-config`는 JSON, YAML, YML 파일을 받으며, 전용 CLI 플래그가 없는 고급 설정을 전달하는 확장 지점입니다. `dump-config`는 출력 파일 확장자에 따라 JSON 또는 YAML을 선택합니다.

하위 프로세스 연동에서는 JSONL 프로토콜을 명시적으로 활성화할 수 있습니다. `QBCOMPILER_JSONL=1`, `true`, `yes`, `on` 중 하나를 설정하면 stdout으로 구조화된 `status`, `progress`, `result`, `log`, `error` 메시지가 출력됩니다. 이 환경 변수가 없으면 일반 로그는 stderr로 출력됩니다.

## Python API 참조

공개 API는 `qbcompiler` 패키지에서 import합니다.

| API | 목적 |
| --- | --- |
| `mxq_compile(...)` | 주 Python 진입점입니다. 모델 또는 실행 가능한 `.mblt`를 `.mxq`로 컴파일합니다. |
| `mblt_compile(...)` | `.mxq`를 만들지 않고 모델을 `.mblt`로 내보냅니다. |
| `list_presets()` | 프리셋 메타데이터 사전 목록을 반환합니다. |
| `dump_default_config(output_path, preset=None)` | `CompileConfig` 템플릿을 JSON/YAML로 저장합니다. |
| `get_body_subgraph(mblt_path, output_path)` | NPU에서 실행 가능한 가장 큰 서브그래프만 포함하는 본문 전용 `.mblt`를 저장합니다. |
| `run_mblt_model(...)` | 디버그/검사용 흐름에서 `.mblt` 추론을 실행합니다. |

기본 `mxq_compile` 사용 예:

```python
from qbcompiler import mxq_compile

mxq_compile(
    model="model.onnx",
    target_device="aries-rb",
    calib_data_path="calib",
    save_path="model.mxq",
    backend="onnx",
    device="gpu",
    config_preset="classification",
    compile_config=None,
)
```

주요 인자는 `model`, `target_device`, `calib_data_path`, `save_path`, `backend`, `feed_dict`, `dynamic_axes`, `in_dformats`, `yolo_decode_include`, `exclude_first_subgraph`, `device`, `inference_scheme`, `use_random_calib`, `cpu_offload`, `optimize_option`, `buffer_mode`, `input_shape_dict`, `force_npu_input_reposition`, `force_npu_output_reposition`, `image_channels`, `split_blocks`, `split_parts`, `config_preset`, `compile_config`, 그리고 `calibration_config`, `bit_config`, `llm_config`, `hessian_quant_config`, `mod_config`, `equivalent_transformation_config`, `search_weight_scale_config`, `uint8_input_config`, `preprocessing_config`, `save_sample_config` 같은 하위 설정 객체입니다.

설정 해석 우선순위 (높은 쪽이 우선): 명시적 인자 → 하위 설정 객체 → `compile_config` 파일 → `config_preset` → 기본값. 자세한 내용과 사용 예시는 [컴파일 설정 — 설정 해석 우선순위](compile_configuration.md#config-resolution-priority)를 참고합니다.

<a id="compileconfig-schema"></a>

## CompileConfig 스키마

`CompileConfig`는 별칭을 지원하는 Pydantic model이며 `extra="forbid"`입니다. JSON/YAML 파일에서는 별칭 이름을 사용합니다. 전체 템플릿은 다음 명령으로 생성할 수 있습니다.

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

최상위 필드:

| Alias | Python field | 기본값 | 의미 |
| --- | --- | --- | --- |
| `modelPaths` | `model_paths` | `[]` | 모델 경로 목록입니다. 보통 API/CLI 인자로 전달합니다. |
| `calibDataPaths` | `calib_data_path` | `[]` | 캘리브레이션 데이터셋 경로 목록입니다. |
| `savePaths` | `save_paths` | `["./tmp.mxq"]` | MXQ 출력 경로 목록입니다. |
| `useRandomCalib` | `use_random_calib` | `false` | 무작위 캘리브레이션 데이터를 생성합니다. |
| `saveMsgpackName` | `save_msgpack_name` | `null` | 선택적 msgpack 출력 이름입니다. |
| `inferenceScheme` | `inference_scheme` | `single` | 생성되는 MXQ에 컴파일 시점에 적용할 NPU 코어 할당 방식입니다. [inferenceScheme](#inferencescheme)을 참고합니다. |
| `cpuOffload` | `cpu_offload` | `false` | 지원되지 않는 연산 범위의 CPU 오프로딩을 활성화합니다. |
| `forceNpuInputReposition` | `force_npu_input_reposition` | `false` | 입력 reposition op를 NPU에서 실행하도록 강제합니다. |
| `forceNpuOutputReposition` | `force_npu_output_reposition` | `false` | 출력 reposition op를 NPU에서 실행하도록 강제합니다. |
| `optimizeOption` | `optimize_option` | `1` | 컴파일러 최적화 선택자입니다. |
| `bufferMode` | `buffer_mode` | `1` | 버퍼 직렬화 모드입니다. |
| `inputShapeDict` | `input_shape_dict` | `{}` | 지원 모델의 다중 형상 컴파일 명세입니다. |
| `device` | `device` | `gpu` | 컴파일 계산 장치입니다. `gpu` 또는 `cpu`입니다. |
| `dtype` | `dtype` | `float` | 계산 데이터 타입 메타데이터입니다. |
| `debug` | `debug` | `false` | 디버그 모드를 활성화합니다. |
| `trace` | `trace` | `false` | 추적 모드를 활성화합니다. |
| `imageChannels` | `image_channels` | `0` | 이미지 채널 수입니다. `0`은 자동 감지입니다. |
| `configVersion` | `config_version` | `1.0.0` | 설정 스키마 버전입니다. |
| `splitBlocks` | `split_blocks` | `[]` | LLM 다중 MXQ 분할 지점의 block index 목록입니다. |
| `splitParts` | `split_parts` | `0` | LLM transformer block을 N개 부분으로 나눕니다. |

중첩 섹션:

| Alias | Type | 목적 |
| --- | --- | --- |
| `uint8Input` | `Uint8InputConfig` | 모델 입력을 uint8로 취급합니다. 입력 이름별 지정도 가능합니다. |
| `preprocessing` | `PreprocessingConfig` | 크기 변경, letterbox, 자르기, 정규화, 형식 변환 같은 입력 전처리 파이프라인입니다. |
| `resourceManagement` | `ResourceManagementConfig` | 가중치 데이터 타입, GPU 캘리브레이션 정책, 가중치 메모리 방식입니다. |
| `calibration` | `CalibrationConfig` | 양자화 방식, 출력 양자화, 캘리브레이션 모드, clipping/statistics, 레이어별 재정의입니다. |
| `bit` | `BitConfig` | 양자화 정밀도 설정입니다. |
| `hessianQuant` | `HessianQuantConfig` | HessianQuant 최적화 설정입니다. |
| `mod` | `ModConfig` | MOD 학습/최적화 설정입니다. |
| `llm` | `LlmConfig` | LLM 시퀀스/캐시/런타임/디버그 설정입니다. `runtime.batchSize`가 `1`보다 크면 `inferenceScheme`은 `single`로 고정되며, Batch LLM 런타임 API는 `BatchParam` 메타데이터를 사용합니다. {external+runtime:doc}`qb Runtime 릴리즈 노트 <kr/release_note>`를 참고합니다. |
| `moe` | `MoeConfig` | Sparse MoE 캘리브레이션 전문가 선택 설정입니다. |
| `equivalentTransformation` | `EquivalentTransformationConfig` | SmoothQuant 계열, rotation, FFN 동등 변환 설정입니다. |
| `searchWeightScale` | `SearchWeightScaleConfig` | 가중치 스케일 탐색 설정입니다. |
| `loadScale` | `LoadScaleConfig` | 외부 스케일 항목 로드 설정입니다. |
| `runtimeOptions` | `RuntimeOptions` | 내부 런타임 메타데이터입니다. |
| `saveSample` | `SaveSampleConfig` | 검사/디버깅용 샘플 데이터 저장 설정입니다. |

`CompileConfig.from_file()`은 `.json`, `.yaml`, `.yml`을 받습니다. 호환성을 위해 `quantization.calibration`, `quantization.bit`, `advancedQuantization.hessianQuant`, `advancedQuantization.mod`, `advancedQuantization.EquivalentTransformation`, `advancedQuantization.searchWeightScale`, `advancedQuantization.loadScale` 같은 그룹화된 키도 평탄화합니다.

### inferenceScheme

`inferenceScheme`은 qb Runtime이 MXQ를 추론에 사용할 때 NPU core 연산을 어떤 방식으로 할당할지 선택합니다. 컴파일된 MXQ는 선택한 core 할당 방식에 맞게 준비되므로, 특정 모드만으로 만든 MXQ를 런타임에서 임의의 다른 모드로 바꿔 실행할 수는 없습니다.

사용 가능한 값은 `single`, `multi`, `global4`, `global8`, `all`입니다. `single`은 독립적인 Local Core 실행, `multi`는 cluster 단위 4-batch 모드, `global4`/`global8`은 4개 또는 8개 Local Core가 한 입력을 함께 처리하는 모드입니다. `all`은 선택한 모델과 target device가 지원하는 모든 코어 모드에서 사용할 수 있도록 MXQ를 준비합니다. 지원 여부는 모델, target device, 컴파일러 버전에 따라 달라질 수 있습니다. REGULUS는 NPU 코어가 1개이므로 REGULUS용으로 컴파일한 MXQ에서는 `single` 모드만 사용할 수 있습니다. `global`은 레거시/호환성 값이므로 새 설정에서는 `global4` 또는 `global8`을 사용합니다.

`llm.attributes.runtime.batchSize`가 `1`보다 크면 LLM/KV 캐시 transformer 컴파일에서는 `inferenceScheme`이 자동으로 `single`로 고정됩니다. 비전 배치 추론과 LLM 배치 추론은 같은 코어 모드 규칙을 사용하지 않습니다.

각 모드의 의미는 {external+aries:doc}`ARIES Core 모드 <core-mode>`를, 런타임에서 core/cluster를 선택하는 방법은 {external+aries:doc}`ARIES ModelConfig 구성 <modelconfig>`을 참고합니다.

## RuntimeOptions

`RuntimeOptions`의 현재 필드는 하나입니다.

| Field | 기본값 | 의미 |
| --- | --- | --- |
| `version` | `0.0.0` | 컴파일러/런타임 버전 메타데이터입니다. |

이 섹션은 일반 사용자 튜닝 인터페이스라기보다 런타임 메타데이터입니다. 사용자가 동작을 조정할 때는 `compile`, `calibration`, `preprocessing`, `LLM`, `optimization` 섹션을 우선 사용합니다.

(preset-list)=

## 프리셋 목록

| 프리셋 | 기반 프리셋 | 동작 |
| --- | --- | --- |
| `classification` | 없음 | 이미지 분류 기본값입니다. `calibration.mode=1`, `calibration.output=0`. |
| `detection` | 없음 | 객체 탐지 기본값입니다. `calibration.mode=1`, `calibration.output=1`. |
| `classification_torchvision` | `classification` | uint8 입력과 Torchvision 표준 전처리를 활성화합니다. 256x256 크기 변경, 224x224 가운데 자르기, ImageNet 평균/표준편차 정규화, `imageChannels=3`. |
| `yolo_640` | `detection` | uint8 입력과 640x640 letterbox 전처리를 활성화합니다. pad value는 114이고 `imageChannels=3`입니다. |
| `yolo_1280` | `detection` | uint8 입력과 1280x1280 letterbox 전처리를 활성화합니다. pad value는 114이고 `imageChannels=3`입니다. |
| `llm` | 없음 | LLM 설정을 활성화합니다. `maxSequenceLength=4096`, `maxCacheLength=4096`, `calibration.mode=0`, `calibration.output=0`. |
| `llm_fast` | `llm` | HessianQuant를 비활성화하고 선택된 동등 변환을 활성화하며, LLM 캘리브레이션에서 전체 시퀀스 길이를 사용합니다. |
| `vision_transformer` | 없음 | transformer 지향 캘리브레이션/bit 설정입니다. |
| `multimodal` | 없음 | LLM 처리를 활성화하고 `calibration.method=3`을 사용합니다. |

## 지원 프레임워크

컴파일 지원 프레임워크는 다음과 같습니다.

| 백엔드 | 입력 |
| --- | --- |
| `onnx` | ONNX model path입니다. 기본 경로이며 `validate_model`이 지원하는 backend입니다. |
| `tf` | TensorFlow SavedModel 또는 지원 TensorFlow/Keras model path입니다. |
| `tflite` | TensorFlow Lite model path입니다. |
| `torchscript` | TorchScript module/model입니다. |
| `torch` | PyTorch model 또는 HuggingFace/transformers model path/object 흐름입니다. HuggingFace LLM은 별도 `hf` backend가 아니라 이 backend path를 사용합니다. |

## 지원 target device

CLI와 Python API에는 다음 target device 문자열을 사용합니다.

| target device | 설명 |
| --- | --- |
| `regulus-ra` | REGULUS RA target입니다. |
| `aries-rb` | ARIES RB target입니다. |
| `regulus-rb` | REGULUS RB target입니다. |

Validator는 위 공개 문자열을 받습니다. 내부 enum 이름은 underscore를 쓰지만, 사용자가 입력하는 값은 hyphen을 사용합니다.

## 지원 연산자

qbcompiler는 현재 매뉴얼에 안정적인 정적 지원 연산자 표를 노출하지 않습니다. 연산자 지원 여부는 특정 모델, backend, 형상, target device에 대해 파서와 target-device 할당 로직이 판단합니다.

사용 가능한 확인 경로:

- ONNX가 아닌 backend는 모델을 parse/compile한 뒤 `.mblt`와 CPU 오프로딩 작업 흐름으로 지원되지 않는 연산 범위를 확인합니다.
- 모델에 지원되지 않는 연산 범위가 있으면 런타임 흐름이 지원하는 범위에서 `cpuOffload` / `cpu_offload`로 CPU 실행 분할을 사용할 수 있습니다.

## 용어집

| 용어 | 의미 |
| --- | --- |
| `MXQ` | 양자화/컴파일 결과로 생성되는 Mobilint 실행 패키지이며 Mobilint NPU에서 실행됩니다. |
| `MBLT` | 파싱과 MXQ 생성 사이에 사용하는 Mobilint 중간 모델 형식입니다. |
| `parse` | 원본 모델을 `.mblt`로 변환하는 단계입니다. |
| `quantize` | 실행 가능한 `.mblt`를 캘리브레이션/설정 값에 따라 `.mxq`로 변환하는 단계입니다. |
| `compile` | parse와 quantize를 포함하는 전체 컴파일 흐름입니다. |
| `backend` | `onnx`, `torch`, `tflite` 같은 원본 모델 프레임워크 식별자입니다. |
| `target_device` | `aries-rb` 같은 Mobilint NPU target device 문자열입니다. |
| NPU 칩 | ARIES, REGULUS 같은 Mobilint NPU 제품 이름입니다. |
| target device | `aries-rb`, `regulus-ra`, `regulus-rb` 같은 컴파일 대상이며 target device 문자열로 사용합니다. |
| `calibration data` | 양자화 스케일/통계를 계산하는 대표 입력 텐서입니다. |
| `CPU 오프로딩` | 지원되지 않는 그래프 그룹은 CPU에서 실행하고 지원되는 본문 서브그래프는 NPU에서 실행하도록 분할하는 방식입니다. |
| `본문 서브그래프(body subgraph)` | 분할된 `.mblt`에서 추출한, NPU에서 실행 가능한 가장 큰 지원 서브그래프입니다. |
| `preset` | 주요 모델 계열을 위한 내장 부분 `CompileConfig`입니다. |

## 라이선스

이 매뉴얼에 포함된 오픈소스 라이선스 공지를 참고합니다.