컴파일 설정

컴파일 설정#

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

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

  • 설정 프리셋 — 모델 계열에 맞는 기본 제공 시작점

  • 설정 파일 — 컴파일 설정이 담긴 JSON 또는 YAML 파일

  • Python 하위 설정 객체 — Python API에 전달하는 타입 지정 설정 객체

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

설정 프리셋#

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

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

python -m qbcompiler presets

프리셋 사용법#

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

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을 전달합니다.

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, 입력 정보, 캘리브레이션 데이터는 별도로 제공해야 합니다. 모델 계열별 프리셋 활용법은 비전 모델과 트랜스포머 모델을 참고합니다. 전체 프리셋 목록과 각 프리셋이 설정하는 값은 참조 — 프리셋 목록을 참고합니다.

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

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

기본 템플릿 생성#

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

프리셋 기반 템플릿 생성#

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에 전달합니다.

# 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로 파일 경로를 전달합니다.

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 인자에 파일 경로를 전달합니다.

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에서 확인할 수 있습니다.

전체 CompileConfig 스키마와 필드 설명은 참조 — CompileConfig 스키마를 참고합니다.

Python 하위 설정 객체#

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

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가 있습니다. 각 양자화 하위 설정의 역할과 튜닝 순서는 모델 양자화 — 양자화 설정을 참고합니다.

설정 해석 우선순위#

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

  1. CLI 또는 Python API에서 명시한 인자

  2. 개별 하위 설정 객체

  3. compile_config 파일

  4. config_preset

  5. CompileConfig 기본값

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

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