microsoft/Aion-Instruct-Preview-Sample

microsoft/Aion-Instruct-Preview-Sample

Description: Sample app showing on-device language model inference with the Aion Instruct Preview Framework on Windows Copilot+ PCs.

Language: PowerShell

License: MIT

Stars: 1

Forks: 0

Open issues: 0

Created: 2026-05-31T20:30:31Z

Pushed: 2026-06-02T06:41:10Z

Default branch: main

Fork: no

Archived: no

README:

Aion Instruct Preview Chat

A WinUI 3 desktop chat app that runs against the AionInstructPreview on-device language model on Copilot+ PCs. Tokens stream into the bubble as they're generated; first-token latency and tokens/sec are shown under each reply.

> Preview notes > > - Platform support. This preview runs on ARM64 Copilot+ PCs (Snapdragon, QNN NPU). x64 (Intel/AMD) support is coming soon. > - Performance. The first-token latency and tokens/sec shown in the app are preliminary — not final performance. Runtime and model optimizations are underway, and these numbers will improve over time.

Quickstart

You need a [Copilot+ PC](https://learn.microsoft.com/windows/ai/npu-devices/) running Windows 11, plus a few tools:

• .NET 9 SDK — winget install --id Microsoft.DotNet.SDK.9
• Git — winget install --id Git.Git (or download the repo ZIP from the green Code button). Bootstrap.ps1 downloads the signed release straight from this repo's public GitHub releases over HTTPS.
• Developer Mode on — Settings → Privacy & security → For developers → Developer Mode → On (Bootstrap.ps1 enables it for you if it isn't already)

Then clone and run the bootstrap script:

git clone https://github.com/microsoft/Aion-Instruct-Preview-Sample
cd Aion-Instruct-Preview-Sample
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\Bootstrap.ps1

Bootstrap.ps1 downloads and installs the Aion Instruct Preview model framework, then builds and launches the chat app. First launch takes ~3-5 minutes to compile the model for your NPU; every launch after is near-instant.

> Bootstrap.ps1 downloads the signed release from this repo's public GitHub releases over plain HTTPS. For the manual steps, Visual Studio, or if you hit a snag, see [Prerequisites](#prerequisites) and [Quickstart details](#quickstart-details). > > Want to use Aion Instruct Preview in your own app instead? See [Use Aion Instruct Preview in your own app](#use-aion-instruct-preview-in-your-own-app).

---

Prerequisites

• Windows 11 on an ARM64 Copilot+ PC (Snapdragon NPU) — runs on QNN.

The SDK picks the EP automatically via WinML's ExecutionProviderCatalog — whichever NPU EP the OS reports as Certified + Ready wins. A certified NPU EP is required — there is no CPU fallback.

> x64 (Intel/AMD) support is coming soon. This preview targets ARM64/Snapdragon only.

Build-time vs run-time — these are different things. A common source of confusion (see [Troubleshooting](#troubleshooting)) is assuming a build error means a *runtime* component is missing. It usually doesn't. Keep the two lists straight:

To BUILD the sample

• .NET 9 SDK (winget install --id Microsoft.DotNet.SDK.9).
• Developer Mode enabled (Settings → Privacy & security → For developers → Developer Mode → On). dotnet run registers the build output as a loose-layout development package, which requires Developer Mode. Bootstrap.ps1 enables it for you (one UAC prompt) if it isn't already.

That's it — no Visual Studio and no registry-installed Windows SDK are required. All other build-time dependencies (Windows App SDK, SDK build tools, CsWinRT, the Windows metadata/ref pack, and the MSIX loose-layout tooling) come from NuGet and are restored automatically.

Prefer Visual Studio? Use Visual Studio 2026 (18.x) — open AionInstructPreview.Chat.sln, pick ARM64 and the AionInstructPreview.Chat (MSIX) launch profile in the Run dropdown, then press F5 to build, deploy, and debug the packaged app. (The other profile, AionInstructPreview.Chat, is the commandName: Project profile that dotnet run uses from a terminal — don't pick it for F5; it launches the bare exe without package identity and crashes with REGDB_E_CLASSNOTREG.) Your VS 2026 instance needs the components listed in [Visual Studio 2026 setup](#visual-studio-2026-setup) below. Visual Studio 2022 (17.x) is not supported for F5 of this app — its MSIX single-project launcher doesn't bind the Windows App SDK 2.0 debug page and reports *"the project doesn't know how to run the profile … command 'MsixPackage'"*. If you'd rather not deal with VS at all, dotnet run from a terminal needs only the .NET 9 SDK + Developer Mode.

To RUN the sample

• Windows App SDK 2.0 runtime (WindowsAppRuntime 2) installed:

winget install --id Microsoft.WindowsAppRuntime.2.0

(or grab the installer from .) This runtime is needed only to run, not to build.

• Windows App Runtime 1.8 — provides the WinML stack the on-device model runs on:

winget install --id Microsoft.WindowsAppRuntime.1.8

Both Windows App Runtimes are required at run time; Bootstrap.ps1 checks for them and stops with the install command if either is missing.

• .NET 9 Desktop Runtime (winget install --id Microsoft.DotNet.DesktopRuntime.9, or the windowsdesktop-runtime-9.0.x-win-.exe installer). The .NET 9 SDK above already includes this, so you only need it separately on a run-only machine that has no SDK.
• The Aion Instruct Preview framework MSIX installed for your arch — Bootstrap.ps1 handles this (see [Quickstart](#quickstart)).

For either path

• Git — winget install --id Git.Git. Used to clone the repo; you can also download the source ZIP from the green Code button instead. Bootstrap.ps1 fetches the signed release from this repo's public GitHub releases over HTTPS.

Visual Studio 2026 setup

The F5 (build + deploy + debug) path is supported on Visual Studio 2026 (18.x) only. In the Visual Studio Installer, Modify your VS 2026 instance and make sure these are installed, then relaunch VS:

• .NET desktop development workload (Microsoft.VisualStudio.Workload.ManagedDesktop) — provides the .NET SDK so the project resolves Microsoft.NET.Sdk. Without it VS reports *"The SDK 'Microsoft.NET.Sdk' specified could not be found."*
• Windows App SDK C# support individual component (Microsoft.VisualStudio.Component.WindowsAppSdkSupport.CSharp).
• **MSIX…