참조

내용

참조#

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

CLI 참조#

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

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 사용 예:

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 → 기본값. 자세한 내용과 사용 예시는 컴파일 설정 — 설정 해석 우선순위를 참고합니다.

CompileConfig 스키마#

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

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을 참고합니다.
`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` 메타데이터를 사용합니다. qb Runtime 릴리즈 노트를 참고합니다.
`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 배치 추론은 같은 코어 모드 규칙을 사용하지 않습니다.

각 모드의 의미는 ARIES Core 모드를, 런타임에서 core/cluster를 선택하는 방법은 ARIES ModelConfig 구성을 참고합니다.

RuntimeOptions#

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

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

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

프리셋 목록#

프리셋	기반 프리셋	동작
`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`입니다.

라이선스#

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