Deploy a custom model

Port a custom model by inspecting the artifact safely, choosing the Voyager model surface that owns it, and proving the compiled result on the card.

Voyager exposes three model-development surfaces. They are related, but they are not interchangeable: the established YAML model zoo uses deploy.py and remains the default when it has a compatible integration; the standalone recipe catalog uses a released recipe or axzoo; and AxScript authors the device graph directly from a compatible checkpoint and source implementation. Agent Dev can inspect the input and route the work, but it still follows the selected SDK release rather than guessing a conversion path.

Deploy a custom model

Choose the owning model surface

Inspect without executing the model

Describe, compile, and validate

1. Write down the model contract

   Collect the input shape and layout, color format or tokenizer contract, normalization, output names and shapes, task, framework, license, and representative calibration data. Treat unknown dimensions and custom operators as open questions; do not fill them from a similar model.

2. Adapt the nearest released integration

   For the YAML surface, copy the nearest released model definition and change only fields supported by the artifact and selected SDK documentation. For the recipe surface, inspect and fork the nearest released recipe, then preserve its source format, preprocessing, calibration, compiler backend, and post-processing contract. The public v1.8 example below is an Alpha Pipeline Builder development route; its --benchmark result is not published YAML Model Zoo performance. Recheck the maturity label in the release you actually installed.

   Public v1.8 CV recipe

   axzoo info detection/yolov8n_coco
   axzoo fork detection/yolov8n_coco --script
   python yolov8n_coco_axrelay.py
   python yolov8n_coco_axrelay.py --benchmark input.mp4

3. Respect the AxScript boundary

   AxScript is an authored-graph path, not an ONNX importer. A bare .onnx file belongs on a compatible YAML or recipe route. AxScript starts from compatible weights or a checkpoint plus code that instantiates the reference architecture, maps its weights, derives its shapes, and authors the device graph and any required kernels. A fine-tune of an implemented architecture may only need a compatible source; a different architecture needs new authoring work. If the selected release does not expose the exact imports, decorators, builders, registration seam, and signatures, stop at labeled pseudocode—never invent compiler-ready-looking APIs.

4. Attest the AxScript environment and source surface

   The active wingman-add-model bundle includes two reusable, read-only AxScript gates. axscript_environment_probe.py checks exact SDK/runtime alignment, installed compiler metadata, required ALTO modules, support-document digests, and release attestation without importing or executing the selected interpreter. axscript_surface_inspector.py uses bounded static AST and Markdown inspection to inventory literal card tags, each card’s own lifecycle, public seams, custom operators, and front-door digests. Wingman resolves these files from its active skill bundle; they are not SDK commands or programs installed on PATH. Run both with JSON output before authoring or building. Their output is evidence, not a support verdict: a discovered operator does not prove a model, and a card marked Validated does not validate another card.

   bash

   ADD_MODEL_SKILL_DIR="<active wingman-add-model skill directory>"
   python3 "$ADD_MODEL_SKILL_DIR/scripts/axscript_environment_probe.py" --runtime-report .wingman-runtime.json --sdk-root "$AXELERA_FRAMEWORK" --json
   python3 "$ADD_MODEL_SKILL_DIR/scripts/axscript_surface_inspector.py" --sdk-root "$AXELERA_FRAMEWORK" --json

5. Build through the correct front door

   Use the front door owned by the chosen surface. Resolve exact recipe arguments with local help; do not translate an AxScript card into a deploy.py mode or assume every recipe backend accepts the same source format.

   bash

   ./deploy.py <yaml-model> --mode QUANTCOMPILE
   axzoo build <config>
   python -m model_axscript build <tag>

6. Prove the result on hardware

   A successful build proves that an artifact was created; it does not prove accuracy, runtime loadability, or task correctness. Run the selected model on visible Axelera hardware, compare it with the framework reference on representative inputs, and apply the model card’s accuracy gate. AxScript vision cards may document axzoo eval <card> --backend axscript; use it only when the selected release and card provide that contract.

   YAML pipeline

   ./inference.py <yaml-model> <input>
   ./inference.py <yaml-model> dataset

   AxScript card

   python -m model_axscript run <tag> <input>
   python -m model_axscript benchmark <tag> <input>

Use the documented compiler shape

The public v1.8 compiler reference uses CompilerConfig, compiler.quantize, and compiler.compile. The block below is syntax-checked but not executed in CI; it is an API-shape example, not model support. Model-ready .npy calibration arrays must come from the real preprocessing contract, and allow_pickle=False keeps them data-only. Start from the nearest installed recipe and reinspect active signatures before execution.

Python · syntax-only v1.8 shape

from pathlib import Path

import numpy as np
from axelera import compiler
from axelera.compiler import CompilerConfig

def calibration_samples():
    for sample_path in sorted(Path("calibration").glob("*.npy")):
        yield np.load(sample_path, allow_pickle=False)

model_name = "custom-model"
output_dir = Path("build") / model_name
config = CompilerConfig(
    output_axm_format=True,
    model_name=model_name,
    output_dir=output_dir,
)
quantized = compiler.quantize(
    model="model.onnx",
    calibration_dataset=calibration_samples(),
    config=config,
)
compiler.compile(model=quantized, config=config, output_dir=output_dir)

Keep precompiled LLM inference separate

Keep unevidenced architectures unverified

Generic LSTM, GRU, RNN, and other architecture support is unverified for the selected release until its current operator support table, active compiler or wheel, complete registered model path, and on-device validation agree. An operator name or a shape found by the inspector is not enough, and an older release’s support table cannot attest the current toolchain. Absence of evidence in one release is not a permanent unsupported verdict.

Rebuild artifacts for the selected release

For the selected v1.8.0 release, custom artifacts must be rebuilt as AxModel major 5. Prebuilt artifacts from an earlier AxModel major must be downloaded again. Always recheck the release notes and compatibility matrix before carrying this rule into another SDK version.