# 컴파일 설정

[첫 컴파일](first_compile.md)에서는 모델에서 MXQ까지의 최단 경로를 보여 주었습니다. 이 장에서는 컴파일 설정으로 해당 경로를 제어하는 방법을 설명합니다.

qb Compiler에 설정을 전달하는 방법은 세 가지입니다.

- **설정 프리셋** — 모델 계열에 맞는 기본 제공 시작점
- **설정 파일** — 컴파일 설정이 담긴 JSON 또는 YAML 파일
- **Python 하위 설정 객체** — Python API에 전달하는 타입 지정 설정 객체

일반적인 모델 계열에는 프리셋을, 반복 가능한 빌드에는 설정 파일을, 스크립트 작업 흐름에는 Python 하위 설정 객체를 사용합니다.

## 설정 프리셋

프리셋은 자주 사용하는 모델 계열을 위해 미리 정의된 설정 모음입니다. 캘리브레이션, 양자화, 전처리 등 모델 계열별 기본값을 이미 포함하고 있어 모든 필드를 직접 지정할 필요가 없습니다.

설치된 패키지에서 사용할 수 있는 프리셋 목록을 확인합니다.

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

### 프리셋 사용법

CLI에서는 `--config-preset`을 전달합니다.

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

Python에서는 `config_preset`을 전달합니다.

```python
from qbcompiler import mxq_compile

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

프리셋은 시작점이지 모델 식별자가 아닙니다. 프리셋을 선택해도 올바른 모델 경로, 백엔드, target device, 입력 정보, 캘리브레이션 데이터는 별도로 제공해야 합니다. 모델 계열별 프리셋 활용법은 [비전 모델](vision.md)과 [트랜스포머 모델](transformer.md)을 참고합니다. 전체 프리셋 목록과 각 프리셋이 설정하는 값은 [참조 — 프리셋 목록](reference.md#preset-list)을 참고합니다.

## dump-config: 설정 템플릿 생성

`dump-config`는 `CompileConfig`의 모든 필드와 기본값을 JSON 또는 YAML 파일로 출력합니다. 사용 가능한 모든 필드를 확인하거나, 프리셋이 어떤 값을 변경하는지 비교할 때 유용합니다.

### 기본 템플릿 생성

```bash
python -m qbcompiler dump-config --output compile_config.json
```

### 프리셋 기반 템플릿 생성

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

출력 형식은 파일 확장자로 결정됩니다. `.yaml` 또는 `.yml`이면 YAML, 그 외에는 JSON으로 출력합니다.

### 작업 흐름: dump → 편집 → 컴파일

1. 모델 계열에 맞는 프리셋에서 템플릿을 생성합니다.
2. 파일을 열고 덮어쓸 필드만 수정합니다.
3. 수정한 파일을 `--compile-config`로 `compile` 또는 `quantize`에 전달합니다.

```bash
# 1. 생성
python -m qbcompiler dump-config --preset classification --output my_config.yaml

# 2. my_config.yaml 편집 (calibration, bit 설정 등 수정)

# 3. 편집한 config로 컴파일
python -m qbcompiler compile \
  --model resnet50.onnx \
  --backend onnx \
  --target-device regulus-rb \
  --compile-config my_config.yaml \
  --calib-data-path ./calib_resnet50 \
  --output resnet50.mxq
```

자동화에 설정 파일을 사용하기 전에, 생성한 템플릿과 기본값을 비교하여 프리셋에서 온 값과 직접 수정한 값을 확인합니다.

## 사용자 설정 파일

컴파일 설정 파일은 동일한 컴파일을 반복해야 할 때 유용합니다. 모델 내보내기 스크립트와 함께 버전 관리 시스템에 보관합니다.

### CLI에서 사용

`--compile-config`로 파일 경로를 전달합니다.

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

### Python에서 사용

`compile_config` 인자에 파일 경로를 전달합니다.

```python
from qbcompiler import mxq_compile

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

설정 파일에는 컴파일 설정만 포함합니다. 모델 경로, 캘리브레이션 데이터 경로, target device, 백엔드, 출력 경로는 일반 CLI 또는 Python 인자로 전달합니다. 같은 필드를 포함하면 JSON과 YAML은 서로 바꿔 사용할 수 있습니다. `$preset`, `$description`, `$skipValidation` 같은 메타데이터 키를 포함해서는 안 됩니다.

프리셋과 설정 파일을 함께 사용할 수 있습니다. 프리셋이 기본값을 제공하고, 설정 파일이 그 위에 특정 값을 덮어씁니다.

생성된 설정 파일을 편집할 때 `inferenceScheme`은 해당 MXQ로 사용할 수 있는 런타임 코어 모드를 결정합니다. ARIES의 코어 모드에는 `single`, `multi`, `global4`, `global8`가 존재합니다. 지원 값과 상세 코어 모드 링크는 [참조 — inferenceScheme](reference.md#inferencescheme)에서 확인할 수 있습니다.

전체 `CompileConfig` 스키마와 필드 설명은 [참조 — CompileConfig 스키마](reference.md#compileconfig-schema)를 참고합니다.

## Python 하위 설정 객체

Python API는 세부 영역마다 타입이 지정된 하위 설정 객체를 제공합니다. 재사용 가능한 컴파일 스크립트를 작성할 때 유용합니다.

```python
from qbcompiler import mxq_compile
from qbcompiler.configs import CalibrationConfig, BitConfig

mxq_compile(
    model="resnet50.onnx",
    backend="onnx",
    target_device="regulus-rb",
    calib_data_path="./calib_resnet50",
    save_path="resnet50.mxq",
    config_preset="classification",
    calibration_config=CalibrationConfig(mode=1, output=0),
    bit_config=BitConfig(
        transformer=BitConfig.Transformer(
            weight=BitConfig.Transformer.Weight(
                query=8, key=8, value=8, output=8, ffn=8, head=8,
            ),
        ),
    ),
)
```

하위 설정 객체는 프리셋 또는 설정 파일의 해당 섹션을 덮어씁니다. 프리셋의 모델 계열 기본값을 유지하면서 특정 양자화나 LLM 설정만 코드에서 조정할 수 있습니다.

사용 가능한 하위 설정 객체로는 `CalibrationConfig`, `BitConfig`, `LlmConfig`, `HessianQuantConfig`, `ModConfig`, `EquivalentTransformationConfig`, `SearchWeightScaleConfig`, `Uint8InputConfig`, `PreprocessingConfig`, `SaveSampleConfig`가 있습니다. 각 양자화 하위 설정의 역할과 튜닝 순서는 [모델 양자화 — 양자화 설정](model_quantization.md#quantization-settings)을 참고합니다.

<a id="config-해석-우선순위"></a>
<a id="config-resolution-priority"></a>

## 설정 해석 우선순위

같은 설정이 여러 위치에 있을 때 다음 우선순위로 적용됩니다 (높은 쪽이 우선).

1. CLI 또는 Python API에서 명시한 인자
2. 개별 하위 설정 객체
3. `compile_config` 파일
4. `config_preset`
5. `CompileConfig` 기본값

모델 계열에 대한 안정적인 선택은 프리셋에 두고, 프로젝트별 설정은 설정 파일에 두며, 실험용 값은 CLI 또는 Python 호출에서 덮어쓰는 방식으로 관리합니다.

최종 적용값이 확실하지 않을 때는 `dump-config`로 빌드 전에 확인합니다.