voyager-deploy

name	voyager-deploy
description	Compile and deploy a model pipeline for Axelera AI hardware using the Voyager SDK, especially custom or non-prebuilt models. Use when the user explicitly asks for compilation, quantization, or calibration, or wants to deploy or optimize a model for Axelera APU. For prebuilt model-zoo networks or complete runnable demos, prefer voyager-launch.
argument-hint	<model name> [options]
allowed-tools	Read, Bash, Glob, Grep, mcp__voyager__*

Deploy Model Pipeline

Compile and deploy a model pipeline for Axelera AI hardware

Use This Skill When / Not When

• Use when: the user explicitly asks to compile, quantize, or calibrate a model with deploy.py, especially custom or non-prebuilt models.
• Not when: the model is a prebuilt zoo network for a demo -- route to voyager-launch (it uses axdownloadmodel).
• Not when: they only want to run an already-deployed model -- route to voyager-run.

Instructions

Deploy the specified model/pipeline: $ARGUMENTS

{{INCLUDE common/voyager-sdk-setup.md}}

{{INCLUDE common/voyager-task-integration.md}}

Step 1: Pre-Deployment Checks

• Verify Axelera environment is activated:

  echo $AXELERA_FRAMEWORK
  

• If not set, activate with: source venv/bin/activate
• Read .voyager-runtime.json. Verify Axelera hardware only when execution.mode is execute_on_device:

  axdevice
  

  In package_for_linux mode, prepare the deployment commands and caveat rather than claiming hardware compilation or runtime validation.

Step 2: Model/Pipeline Identification

• Parse model name from arguments
• If no model specified, list available models:

  ./deploy.py --help
  

• Locate the YAML configuration in ax_models/
• Verify YAML file exists and is valid

Step 3: Deployment Mode Selection

For prebuilt Voyager SDK model-zoo networks, prefer axdownloadmodel and cached payload checks. Use deploy.py only when the user explicitly asks for compilation/deployment or when integrating a custom/non-prebuilt model.

Choose appropriate deployment mode:

• --mode PREQUANTIZED (default): Compile from a pre-quantized model
• --mode QUANTCOMPILE: Quantize and compile the model
• --mode QUANTIZE: Quantize the model (will NOT deploy pipeline)
• --mode QUANTIZE_DEBUG: Quantize with debug outputs
• --export: Export quantized/compiled model to zip (separate flag, not a mode)

Step 4: Target Configuration

• --metis {auto,none,pcie,m2}: Target Axelera device type (default: auto/detect)
• --aipu-cores <n>: Number of AIPU cores to use (1-4)

Step 5: Deployment Execution

Run deployment command:

./deploy.py <model-name> [options]

Common examples:

# Basic deployment
./deploy.py yolov5s-v7-coco

# Compile one model from the network YAML without deploying the pipeline
./deploy.py yolov8n-coco --model yolov8n-coco

# Quantize only (for debugging)
./deploy.py yolov5s-v7-coco --mode QUANTIZE

# Deploy for PCIe with 4 cores
./deploy.py yolov8m-coco --metis pcie --aipu-cores 4

# Quantize and compile in one step
./deploy.py yolov5s-v7-coco --mode QUANTCOMPILE

# Export compiled model to zip
./deploy.py yolov5s-v7-coco --export

# Deploy specific components
./deploy.py yolov5s-v7-coco --pipeline-only
./deploy.py yolov5s-v7-coco --models-only

Step 6: Calibration Process

• Deployment includes automatic quantization calibration
• Calibration uses dataset specified in YAML
• Override calibration count with --num-cal-images <n>
• Point to an existing dataset root with --data-root <path> or set the YAML dataset cal_data; do not use a non-SDK --cal-data flag
• For reproducible results, set calibration seed:

  ./deploy.py <model> --num-cal-images 200 --cal-seed 42
  

Step 7: Build Output Verification

After successful deployment, verify outputs:

• Build directory: build/<model-name>/<arch>/
• Compiled model: *.axnet, or tracker/classical payloads such as model.json plus kernels
• Pipeline configuration when generated by the SDK
• Check compilation logs for warnings

Step 8: Troubleshooting Common Issues

Environment not activated:

Error: Please set AXELERA_FRAMEWORK variable
Solution: source venv/bin/activate

Model not found:

Error: NN=<name> does not specify a valid model
Solution: Check model name with ./deploy.py --help

Calibration data missing:

Error: Calibration dataset not found
Solution: Download the dataset, set --data-root, or configure cal_data in YAML

Out of memory during compilation:

Solution: Reduce batch size or model complexity

Step 9: Post-Deployment Validation

• Test the deployed model:

  ./inference.py <model-name> <test-input> --no-display
  

• Check model accuracy:

  ./inference.py <model-name> dataset --no-display
  

Step 10: Advanced Options

# Verbose logging
./deploy.py <model> --loglevel DEBUG

# Custom output directory
./deploy.py <model> --build-root /path/to/build

# Export compiled model to zip
./deploy.py <model> --export