홈 > EulerNPU > CLI 레퍼런스

EulerNPU CLI 레퍼런스

eulerwa 제품군 공통 CLI 컨벤션을 따릅니다. 모든 메시지는 i18n 대상입니다 (ko 기본, en/zh/ja/es 지원). 단일 실행 파일 eulernpu 하나로 모든 서브커맨드를 실행합니다.

Entry Point

단일 실행 파일: eulernpu

모든 기능은 서브커맨드입니다: eulernpu <command> [args...]

하이픈으로 결합된 명령 (eulernpu-info, eulernpu-compile 등)은 지원하지 않습니다.

eulernpu [--lang ko|en|zh|ja|es] [OPTIONS] COMMAND [ARGS]...

Global Options

--lang ko|en|zh|ja|es

출력 언어를 지정합니다. 도움말 텍스트, 로그 메시지, 오류 요약, 성공 출력 모두에 적용됩니다. 기본값: ko.

지원 언어:

번역 대상 밖 (항상 고정): 명령/옵션 이름, op/backend/dtype 이름, JSON 키, spec 키, validator 규칙 코드.

# 한국어 출력 (기본)
eulernpu validate examples/tiny_mlp/spec.yaml

# 영어 출력
eulernpu --lang en validate examples/tiny_mlp/spec.yaml

# 중국어 / 일본어 / 스페인어 출력
eulernpu --lang zh validate examples/tiny_mlp/spec.yaml
eulernpu --lang ja validate examples/tiny_mlp/spec.yaml
eulernpu --lang es validate examples/tiny_mlp/spec.yaml

eulernpu --version

버전을 출력합니다.

Common Option Conventions (eulerwa style)

Option Description Used In
--lang 출력 언어 (ko/en/zh/ja/es) all commands (root)
--spec <yaml> YAML spec 파일 경로 compile, calibrate
--artifact <path> 컴파일된 .npuart 아티팩트 경로 run, sim, profile, sweep, explain, quantize, generate, benchmark, replay, compress-cache
--backend <name> 실행 백엔드 (cpu_ref, npu_sim, zynq_ps, zynq_pl_stub) run, sim, profile, benchmark, replay
--target <backend> 컴파일 대상 백엔드 compile, calibrate, board smoke
--output / -o 출력 파일 또는 디렉터리 compile, calibrate, quantize, compress-cache
--json-output 구조화된 JSON 출력 validate

모든 옵션은 kebab-case 규칙을 따릅니다 (예: --json-output, --dump-graph, --all-boards).

Top-Level Commands

eulernpu info

NPU capability 정보를 출력합니다.

eulernpu info
eulernpu info --dtypes
eulernpu info --ops

eulernpu validate

Spec YAML 파일을 스키마와 semantic 규칙에 대해 검증합니다.

# 기본 검증
eulernpu validate examples/tiny_mlp/spec.yaml

# JSON 출력
eulernpu validate examples/tiny_mlp/spec.yaml --json-output

eulernpu compile

Spec YAML을 실행 가능한 아티팩트(.npuart)로 컴파일합니다.

eulernpu compile --spec examples/tiny_mlp/spec.yaml --target cpu_ref

# 그래프 + 메모리 플랜 dump
eulernpu compile --spec examples/tiny_mlp/spec.yaml --target npu_sim \
    --dump-graph --dump-plan -o build/

eulernpu run

컴파일된 아티팩트를 백엔드에서 실행합니다.

# 골든 비교와 함께 실행
eulernpu run --artifact build/tiny_mlp.npuart --backend cpu_ref \
    --golden examples/tiny_mlp/golden.npz

eulernpu sim

아티팩트를 npu_sim에서 실행하고, 선택적으로 트레이스를 출력합니다.

npu_sim은 모든 D-그룹 Conv/Vision op (conv1d/2d, depthwise, pointwise, pooling, global pool, upsample)을 트레이싱하고 op별 NPU 클럭 사이클 추정치를 리포트합니다: estimated_cycles, estimated_latency_ms (spec의 board.clock_mhz 기준), 컴퓨트 op의 경우 estimated_macs. 트레이스 JSON과 요약에는 total_estimated_cycles / total_estimated_latency_ms가 포함됩니다.

eulernpu sim --artifact build/tiny_mlp.npuart --backend npu_sim \
    --trace trace.json

eulernpu profile

실행 프로파일: 지연시간, 피크 메모리, op별 사이클/지연/MAC 상세 분해 (npu_sim), clock_mhz 기준 총 추정 사이클과 지연.

eulernpu profile --artifact build/tiny_mlp.npuart

# 5개 보드 교차 비교
eulernpu profile --artifact build/tiny_mlp.npuart --all-boards

eulernpu sweep

(보드 × systolic 크기) 설계 공간을 스윕하고 Pareto-optimal 구성을 표시합니다 (F6). BOARD_PROFILES의 각 보드 (5개, ADAS급 xczu7ev / xck26 포함)와 각 systolic 크기에 대해 spec의 matmul_engine을 재구성하고 npu_sim 트레이스로 지연 / LUT% / DSP% / 전력을 생성합니다. (지연, 전력, DSP%) 세 축 모두에서 다른 실현 가능한 지점에 지배당하지 않는 점이 Pareto-optimal입니다.

eulernpu sweep --artifact build/tiny_mlp.npuart \
    --systolic 8,16,32 --output-format table

eulernpu board smoke

Zynq 보드 스모크 테스트 (zynq_ps 또는 zynq_pl_stub).

# 에뮬레이션 모드 (실제 보드 불필요)
eulernpu board smoke --target zynq_ps --emulated
eulernpu board smoke --target zynq_pl_stub --emulated

eulernpu explain

아티팩트를 사람이 읽기 쉬운 형태로 설명합니다.

eulernpu explain --artifact build/tiny_mlp.npuart

eulernpu calibrate

데이터셋으로부터 양자화 파라미터를 캘리브레이션합니다. 통계 JSON을 출력합니다.

eulernpu calibrate --spec examples/tiny_mlp/spec.yaml \
    --dataset data/calib.npz --target cpu_ref \
    --method percentile -o calibration.json

eulernpu quantize

컴파일된 아티팩트를 INT8 양자화합니다. 캘리브레이션 데이터셋(.npz 파일 또는 .npz 디렉터리)으로부터 activation 범위를 캘리브레이션하고, weight 행렬을 int8로 양자화(dequantize 노드 삽입)하며, 그래프의 입력 activation을 fake-quantize (quantize→dequantize 삽입)합니다. 결과 아티팩트의 weight 버퍼는 약 4× 작아집니다.

--no-activations는 weight-only 양자화입니다.

calibrate가 stats JSON만 내는 것과 달리, quantize는 실행 가능한 INT8 아티팩트를 생성합니다.

eulernpu quantize --artifact build/industrial_kws.npuart \
    --calib-data data/calib \
    --out build/industrial_kws_int8.npuart \
    --report build/quant_report.json

eulernpu generate

LM-decoder 아티팩트에서 토큰을 자기회귀적으로 생성합니다 (project2 §5.2). 디코더를 토큰 단위로 (커지는 prefix에 대한 recompute) 구동하며, greedy 또는 seeded top-k로 샘플링합니다. --prompt-ids는 콤마 구분 토큰 ID이며, --input은 추가 조건 입력 (예: VLM의 visual_kv) 을 공급합니다. Edge VLM 파이프라인이 PipelineExecutor와 함께 사용합니다.

eulernpu generate --artifact build/lm.npuart \
    --prompt-ids "1,2,3" --max-new-tokens 32 \
    --sampler top_k --top-k 40 --temperature 0.8 \
    --incremental

eulernpu benchmark

추론 지연시간을 벤치마크합니다. mean, P50, P99, throughput을 리포트합니다.

eulernpu benchmark --artifact build/tiny_mlp.npuart \
    --backend npu_sim --repeat 100 --warmup 10

eulernpu replay

센서 로그 스트림에 대해 추론을 재생합니다. streaming과 batch 모드를 지원합니다.

eulernpu replay --artifact build/tiny_mlp.npuart \
    --stream data/sensor_log.npz \
    --mode streaming --backend cpu_ref

eulernpu compress-cache

캐시 압축 잠재력을 분석합니다. 텐서별 및 전체 압축 비율을 리포트합니다.

eulernpu compress-cache --artifact build/lm.npuart \
    --scheme int4 -o build/compress_report.json

eulernpu demo embodied-soc

Embodied Multimodal AI SoC 터미널 데모를 실행합니다 (5-서브시스템 파이프라인: live compile → parallel run → results → action trajectory → FPGA-readiness checklist). rich 라이브러리가 필요합니다 (pip install eulernpu[demo]). --realistic은 배포급 모델 차원을 사용합니다 (더 느림). 소스 체크아웃 전용 (데모는 projects/ 하위에 위치).

eulernpu demo embodied-soc --backend npu_sim --seed 42

Board Subcommands

보드 관련 서브커맨드는 eulernpu board <subcommand> 형태로 실행됩니다.

eulernpu board smoke

위의 Board smoke 섹션 참조. 지원 target: zynq_ps, zynq_pl_stub. --emulated 플래그로 실제 보드 없이 실행 가능.

Error Format Policy

모든 CLI 오류는 3줄 포맷 (eulerwa 표준) 을 따릅니다:

<Category>: <what>
Fix: <one line>
See: <doc path>

예시:

CalibrationError: unsupported dataset format
Fix: provide .npz file
See: docs/cli.md

대표적인 에러 카테고리:

i18n Notes

번역 적용 범위:

번역 대상 밖 (항상 고정):

Examples

# Spec 검증
eulernpu validate examples/tiny_mlp/spec.yaml

# cpu_ref로 컴파일
eulernpu compile --spec examples/tiny_mlp/spec.yaml --target cpu_ref

# 골든 비교와 함께 실행
eulernpu run --artifact build/tiny_mlp.npuart --backend cpu_ref \
    --golden examples/tiny_mlp/golden.npz

# 트레이스와 함께 시뮬레이션 (conv op + 사이클 추정)
eulernpu sim --artifact build/tiny_mlp.npuart --backend npu_sim \
    --trace trace.json

# 캘리브레이션 기반 INT8 양자화 (Project 1 industrial KWS)
eulernpu compile --spec projects/industrial_kws/spec.yaml --target cpu_ref \
    -o projects/industrial_kws/build
eulernpu quantize --artifact projects/industrial_kws/build/industrial_kws.npuart \
    --calib-data projects/industrial_kws/data/calib \
    --out projects/industrial_kws/build/industrial_kws_int8.npuart \
    --report projects/industrial_kws/build/quant_report.json
eulernpu profile --artifact projects/industrial_kws/build/industrial_kws_int8.npuart \
    --backend npu_sim

# dtype과 operator 확인
eulernpu info --dtypes
eulernpu info --ops

# 아티팩트 설명
eulernpu explain --artifact build/tiny_mlp.npuart

# FPGA 배포 (zynq_ps)
eulernpu compile --spec examples/tiny_mlp/spec.yaml --target zynq_ps
eulernpu run --artifact build/tiny_mlp.npuart --backend zynq_ps \
    --golden examples/tiny_mlp/golden.npz

# 보드 스모크 테스트 (에뮬레이션, 보드 불필요)
eulernpu board smoke --target zynq_ps --emulated
eulernpu board smoke --target zynq_pl_stub --emulated

# 언어 오버라이드
eulernpu --lang en info --dtypes