컴파일 설정

컴파일 설정#

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

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

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

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

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

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

설정 프리셋#

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

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

QBCOMPILER_JSONL=1 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

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

config-save-path: 빌드가 실제로 사용한 설정 기록#

dump-config는 프리셋이나 기본값에 무엇이 들어 있는지 보여줍니다. --config-save-path는 다른 질문에 답합니다. 아래 우선순위가 프리셋과 설정 파일 중 하나를 고르고 그 위에 하위 설정 객체와 명시적 인자가 적용된 뒤, 이번 빌드가 실제로 무엇을 가지고 실행되었는가입니다.

qbcompiler 1.3부터 quantize와 compile에서 사용할 수 있습니다.

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

qbcompiler.mxq_compile(
    model="resnet50.onnx",
    target_device="regulus-rb",
    calib_data_path="./calib_resnet50",
    save_path="resnet50.mxq",
    config_preset="classification",
    config_save_path="resnet50_used_config.yaml",
)

이 파일에는 이 페이지 아래 설정 해석 우선순위 절의 모든 단계가 적용되고 모든 하위 설정이 구체화된 정규화된 CompileConfig가 들어갑니다. 형식은 확장자를 따릅니다. .yaml 또는 .yml이면 YAML, 그 외에는 JSON입니다. 상위 디렉터리는 자동으로 생성됩니다.

자동화에서 유용한 이유는 두 가지입니다.

  • 컴파일이 시작되기 전에 기록되므로, 실패하거나 중단된 실행에서도 기록이 남습니다. 설정을 확인하고 싶은 상황이 바로 그때입니다.

  • 이 파일을 그대로 --compile-config / compile_config=로 넘기면 동일한 컴파일을 재현할 수 있습니다.

compile 파이프라인에서는 전체 CompileConfig를 들고 있는 quantize 단계가 파일을 씁니다. parse 단계는 device와 cpu_offload만 해석합니다. 기록할 수 없는 위치를 지정하면 내부 오류가 아니라 해당 경로를 명시한 OUTPUT_WRITE_ERROR로 실패합니다.

사용자 설정 파일#

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

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 인자에 파일 경로를 전달합니다. 이 인자는 CompileConfig 객체도 받습니다.

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은 서로 바꿔 사용할 수 있습니다. 설정 파일에는 지원되는 CompileConfig 필드만 넣을 수 있으며, $preset, $description, $skipValidation 같은 메타데이터 키를 포함해서는 안 됩니다.

프리셋과 설정 파일은 함께 쌓이는 것이 아니라 둘 중 하나를 고르는 것입니다. 둘 다 주면 프리셋이 쓰이고 파일은 무시되며, 경고도 나오지 않습니다. 프리셋 값에 자기 값을 더하고 싶다면 dump-config --preset <이름>으로 시작해 결과를 편집하세요.

생성된 설정 파일을 편집할 때 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, head=8, router=8,
                ffn=8,  # 하위 레이어별 지정: BitConfig.Transformer.Weight.Ffn(up=8, gate=8, down=8)
            ),
        ),
    ),
)

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

사용 가능한 하위 설정 객체로는 CalibrationConfig, BitConfig, LlmConfig, HessianQuantConfig, LayerBiasCorrectionConfig, ModConfig, EquivalentTransformationConfig, SearchWeightScaleConfig, Uint8InputConfig, PreprocessingConfig, SaveSampleConfig, ResourceManagementConfig가 있으며, 모두 대응하는 *_config 인자를 가집니다. LayerBiasCorrectionConfig는 qbcompiler 1.3에서 추가되었습니다. 각 양자화 하위 설정의 역할과 튜닝 순서는 모델 양자화 — 양자화 설정을 참고합니다.

설정 해석 우선순위#

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

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

  2. 개별 하위 설정 객체

  3. compile_config 파일 또는 config_preset — 주어진 쪽. 둘 다 주면 프리셋이 이기고 파일은 읽히지 않습니다

  4. CompileConfig 기본값

출발점은 프리셋이나 설정 파일 중 하나로 정하고, 실험용 값은 CLI 또는 Python 호출에서 덮어쓰는 방식으로 관리합니다.

최종 적용값이 확실하지 않을 때는 빌드에 --config-save-path를 추가하고 기록된 파일을 확인합니다.