Skip to content

windows_getting_started.md

Latest commit

 

History

History
322 lines (265 loc) · 15.9 KB

windows_getting_started.md

File metadata and controls

322 lines (265 loc) · 15.9 KB

Voyager SDK Installation Guide for Windows

Contents

Prerequisites

  • Windows 11 (only tested version)
  • Windows Subsystem for Linux (WSL2) support
  • Administrative privileges
  • Internet connection

Level

Beginner - Follow step-by-step Windows-specific installation

IMPORTANT NOTICE

Important: Full development environment is not available natively on Windows.

  • Recommended: Use Ubuntu or Windows Subsystem for Linux (WSL) for development.
  • Windows SDK currently supports inference only (via AxRuntime API).
    For details, see Supported Features on Windows vs. Linux.

Supported Features Comparison

Feature Ubuntu (Linux) Windows (Native) Windows (WSL)
Full SDK Development ✅ ❌ ✅
Network Deployment ✅ ❌ ✅
Inference (AxRuntime) ✅ ✅ ✅

Contents

Overview

This guide provides step-by-step instructions for installing and configuring the Voyager SDK on a Windows 11 system.

Note

Only Windows 11 with Windows Subsystem for Linux (WSL) support was tested.

Before proceeding, please follow the Voyager SDK Repository on Windows guide to clone the Voyager SDK repository and set up the environment.

Step 1: Install the Axelera Windows Driver

Note

This step will be automated through Windows Update after Microsoft certification in the near future.

For evaluation purposes, follow the detailed instructions in the Windows Driver Installation Guide for manual installation of the Axelera AI driver on your Windows system.

Step 2: Install the Axelera Voyager SDK using Windows Subsystem for Linux

Note

If you're only interested in downloading pre-deployed networks instead of deploying your own, then you can skip this step and proceed directly to Step 3: Install Python.

Network deployment is supported exclusively in Linux, even when inference is performed on Windows. Windows Subsystem for Linux (WSL) is the recommended approach for deploying networks for Windows use.

Setting up the voyager-sdk repository on Windows:

a) Install Windows Subsystem for Linux (WSL):

  • Launch PowerShell as Administrator and execute: 
    wsl --install
  • Restart the computer after installation completes.
  • To install Ubuntu 22.04 (recommended), execute: 
    wsl --install -d Ubuntu-22.04
  • Follow the prompts to set up the Ubuntu username and password.

For comprehensive instructions, refer to:

Important

After completing the WSL installation, close the Administrator PowerShell window, open a regular Windows Command Prompt (not Windows PowerShell!) without administrator privileges, and launch WSL by entering:

wsl

b) Clone and Configure voyager-sdk:

  • Clone the voyager-sdk repository from https://github.com/axelera-ai-hub/voyager-sdk and checkout branch release/v1.4 in a Windows-accessible folder. For example: /mnt/c/Axelera/voyager-sdk (accessible from Windows as C:\Axelera\voyager-sdk). Complete cloning instructions are available in the Installation guide.
  • Follow the Installation guide setup instructions, selecting only the Python environment and runtime libraries during installation
  • Important: Do not select the driver installation option as it is not compatible with WSL WSL Installation Options

c) Optional: Deploy or Download Models: While in WSL, activate the Python virtual environment:

source venv/bin/activate

Two options exist for obtaining models:

  1. Deploy models using the Linux environment: 
    ./deploy.py [options]
  2. Download prebuilt models after activating the Python environment: 
    source venv/bin/activate
axdownloadmodel

Example:

axdownloadmodel resnet50-imagenet-onnx

This downloads the ResNet50 classification model for future use.

Note

Additional models can be deployed or downloaded at any time

Step 3: Install Python

Note

Perform this step in Windows natively, not in WSL.

  1. Download Python for Windows. The latest Python Stable Release version is recommended. The latest stable release tested by Axelera is 3.13.5.

Important

Install Python from the official website link above, not from the Microsoft Store

  1. During installation:
    • Enable the option to add Python to PATH
    • Select "Disable path length limit" when prompted
  2. Create a virtual environment: 
    python -m venv venv
  3. Add the Python installation path and Python\Scripts path to the Windows environment Path variable: Python Environment Variables

Step 4: Install Windows Axelera Components

Note

Perform this step in Windows natively, not in WSL.

Open a Windows regular Command Prompt (not Windows PowerShell!) without administrator privileges and navigate to the Voyager SDK installation directory. For example, if installed in C:\Axelera\voyager-sdk:

cd C:\Axelera\voyager-sdk

Create a local windows-packages directory and download the installers:

rmdir /s /q windows-packages 2>nul
mkdir windows-packages
cd windows-packages
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.5.x/axelera-win-device-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.5.x/axelera-win-runtime-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.5.x/axelera-win-syslibs-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.5.x/axelera-win-toolchain-deps-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.5.x/axelera-win-services-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-runtime-pypi/axelera-runtime/axelera_runtime-1.5.3-py3-none-any.whl
curl -L -O https://software.axelera.ai/artifactory/axelera-runtime-pypi/axelera-types/axelera_types-1.5.3-py3-none-any.whl
curl -L -O https://software.axelera.ai/artifactory/axelera-runtime-pypi/axelera-llm/axelera_llm-1.5.3-py3-none-any.whl
cd ..

Installing the Executable Installers

Important

Before installing the executable installers, uninstall any previous versions of Axelera packages if they exist. After installing all executable installers, close all Command Prompt and Windows PowerShell windows. Open a new Command Prompt window (without administrator privileges) to continue with the remaining steps.

Using Windows Explorer, navigate to C:\Axelera\voyager-sdk\windows-packages and install each executable installer sequentially.

After installation, verify the packages were installed correctly:

  1. Open Windows Settings and navigate to "Apps & features" (or "Add or remove programs")

Add Remove Programs

  1. Verify that the following packages are listed:

First Four Packages

Last Package

The exact version numbers may vary depending on what version you're installing, but you must see the following packages listed: Axelera Cross Compiled Libraries Package, Axelera Device Package, Axelera Runtime, Axelera Services, and RISC-V Toolchain and Dependencies for Axelera.

Important

After installing all executable installers, restart your Command Prompt window (without administrator privileges) to continue with the remaining steps.

Installing the Python Packages

Create a new Python virtual environment for Windows use:

python -m venv venv-win
venv-win\Scripts\activate.bat

Install the Python packages:

pip install windows-packages\axelera_runtime-1.5.0-py3-none-any.whl
pip install windows-packages\axelera_types-1.5.0-py3-none-any.whl
pip install windows-packages\axelera_llm-1.5.0-py3-none-any.whl

Step 5: Running Examples [Optional]

Note

If you haven't gone through the previous WSL step and need to download a pre-deployed network to do the next steps please run now:

cd `C:\Axelera\voyager-sdk`
axdownloadmodel resnet50-imagenet-onnx

The pre-built model will be downloaded under C:\Axelera\voyager-sdk\build

Execute inference using either of these methods:

  1. Using Python API: Download an image to C:\Axelera\voyager-sdk\examples\axruntime\images and run:

    cd examples\axruntime
python -m axruntime_example -v --aipu-cores 1 --labels imagenet-labels.txt ..\..\build\resnet50-imagenet-onnx\resnet50-imagenet-onnx\1\model.json images

    Where images is the directory containing the input images

  2. Using the axrunmodel utility to measure performance:

    axrunmodel C:\Axelera\voyager-sdk\build\resnet50-imagenet-onnx\resnet50-imagenet-onnx\1\model.json

    This command will execute the model multiple times and display runtime statistics.

Important

Remember to re-activate the Python virtual environment each time you open a new Command Prompt window. From your installation directory (e.g., C:\Axelera\voyager-sdk), run:

venv-win\Scripts\activate.bat

You'll know the virtual environment is active when you see (venv-win) at the beginning of your command prompt.

Step 6: Running LLM Models

It's possible to run a set of precompiled LLM models on Windows. For the list of available models, please refer to the LLM Models section of the Voyager Model Zoo, or simply run:

axllm --help-network

For example, to run the llama-3-2-1b-1024-4core-static model in single prompt mode, execute:

axllm llama-3-2-1b-1024-4core-static --prompt "Give me a joke"

To chat interactively with the model in your terminal, run:

axllm llama-3-2-1b-1024-4core-static

Many other options are available as described in the LLM Inference Guide.

Important

Remember to re-activate the Python virtual environment each time you open a new Command Prompt window. From your installation directory (e.g., C:\Axelera\voyager-sdk), run:

venv-win\Scripts\activate.bat

You'll know the virtual environment is active when you see (venv-win) at the beginning of your command prompt.

Notes on Using Windows PowerShell

After completing all the installation steps above, you can use Windows PowerShell instead of Windows Command Prompt for running examples and working with the SDK. The main difference is in how you activate the Python virtual environment:

.\venv-win\Scripts\Activate.ps1

Once activated, you can run all the same commands as described in the Running Examples section above.

Note

While PowerShell can be used for running examples and working with the SDK after installation, it's important to note that the initial setup steps (particularly Step 4) should still be performed using Windows Command Prompt as specified in the instructions above.

If you encounter issues activating the Python virtual environment in PowerShell, you may need to adjust the PowerShell execution policy. You can check your current policy with:

Get-ExecutionPolicy

If needed, you can set a more permissive policy using one of these commands (run PowerShell as Administrator):

Set-ExecutionPolicy RemoteSigned
Set-ExecutionPolicy Unrestricted

After adjusting the execution policy, try activating the environment again using .\venv-win\Scripts\Activate.ps1.

Next Steps

Related Documentation

Windows Guides:

Linux Alternative:

Next Steps:

References:

Further support