컴파일 기본 흐름

컴파일 기본 흐름#

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

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

전체 컴파일#

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

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

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를 생성합니다.

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

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

  • 파싱된 그래프를 Netron에서 확인할 때

  • 양자화 전에 레이어 지원 여부를 확인할 때

  • 입력 이름과 형상(shape)을 디버깅할 때

  • 동일하게 파싱된 모델을 여러 target device나 설정 실험에 재사용할 때

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

quantize: MBLT를 MXQ로 변환#

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

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

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

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

  • MBLT 검토를 이미 마쳤을 때

  • 프리셋이나 설정 파일을 비교해야 할 때

  • 같은 파싱 결과를 여러 target device 문자열로 컴파일해야 할 때

  • 원본 모델을 다시 파싱하지 않고 캘리브레이션이나 양자화만 디버깅할 때

compile vs. parse + quantize#

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

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

주요 산출물 체크리스트#

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

  • 원본 모델과 소스 리비전

  • 캘리브레이션 샘플 디렉터리 또는 메타데이터 파일

  • 컴파일 설정 파일 또는 프리셋 이름(참조 — CompileConfig 스키마 참고)

  • target device 문자열

  • 단계별로 컴파일했다면 생성된 MBLT

  • 생성된 MXQ

  • 검증에 사용한 입력과 출력

  • 배포 시 CPU head/NPU body/CPU tail 경계가 중요하다면, 추출한 NPU body 서브그래프 산출물