Aan de slag met het bouwen van een app met Windows AI APIs

Meer informatie over de Windows AI-hardwarevereisten API en het configureren van uw apparaat om apps te bouwen met windows AI APIs.

Afhankelijkheden

Zorg ervoor dat uw pc Windows AI APIs ondersteunt en dat alle afhankelijkheden zijn geïnstalleerd. U kunt ervoor kiezen om dit automatisch (aanbevolen) of handmatig te doen.

  1. Controleer of uw apparaat voldoet aan de hardwarevereisten voor de Windows AI-APIs die u wilt gebruiken. De meeste APIs vereisen een Copilot+ PC met een NPU (we raden de apparaten aan die worden vermeld in de ontwikkelaarshandleiding voor Copilot+ PCs). Sommige APIs bieden ook ondersteuning voor GPU- of CPU-uitvoering op niet-Copilot+ apparaten. Zie de ondersteunde hardwaretabel voor meer informatie.

  2. Voer de volgende opdracht uit in Windows Terminal.

    winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/learn_wcr.winget

    Hiermee wordt een WinGet-configuratiebestand uitgevoerd waarmee de volgende taken worden uitgevoerd:

    • Controleert op minimale versie van het besturingssysteem.
    • Hiermee schakelt u de ontwikkelaarsmodus in.
    • Installeert Visual Studio Community Edition met WinUI en andere vereiste workloads.
    • Installeert de Windows App SDK.

Een nieuwe app bouwen

In de volgende stappen wordt beschreven hoe u een app bouwt die gebruikmaakt van Windows AI APIs (selecteer het tabblad voor het UI-framework van uw voorkeur).

  1. Maak in Visual Studio een nieuw WinUI-project door de sjabloon Blank App, Packaged (WinUI 3 in Desktop) te selecteren.

    Een schermopname van de nieuwe projectgebruikersinterface van Visual Studio met de WinUI-sjabloon geselecteerd.

  2. Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt, selecteerEigenschappentoepassings>>algemeen en zorg ervoor dat het doelframework is ingesteld op .NET 8.0 en het doelbesturingssysteem is ingesteld op 10.0.22621 of hoger.

    Een schermopname van het deelvenster Eigenschappen van het Visual Studio-project

  3. Bewerk het bestand Package.appxmanifest (klik met de rechtermuisknop en selecteer Code weergeven) en voeg de volgende codefragmenten toe.

    • De systemAIModels mogelijkheid voor het <Capabilities> knooppunt:

      <Capabilities>
   <systemai:Capability Name="systemAIModels"/>
</Capabilities>

    • De systemai naamruimteaanduiding voor 'IgnorableNamespaces' in het <Package> knooppunt:

      xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"

    • De maximale versie die is getest in het TargetDeviceFamily-element van het <Dependencies>-knooppunt moet ten minste 10.0.26226.0 zijn.

      <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />

  4. Voeg het volgende toe aan het bestand .waproj, .csproj of .vcxproj. Deze stap is nodig om ervoor te zorgen dat visual studio de geteste maximale versie niet overschrijft.

    <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
<AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>

  5. Klik met de rechtermuisknop op het projectknooppunt en selecteer NuGet-pakketten beheren....

  6. Schakel in NuGet Pakketbeheer het selectievakje Prerelease opnemen in en selecteer Windows App SDK-versie 1.8.250410001-experimenteel1. Klik op Installeren of Bijwerken.

    Een schermopname van Visual Studio nuget-pakketbeheer met Microsoft.WindowsAppSDK 1.8.250410001-experimenteel1 geselecteerd.

  7. Zorg ervoor dat uw buildconfiguratie is ingesteld op de juiste architectuur voor uw apparaat (bijvoorbeeld ARM64 of x64).

    Een schermopname van de configuratie van de Visual Studio-build die is ingesteld op ARM64.

  8. Bouw en voer uw app uit.

  9. Als de app succesvol wordt gestart, gaat u verder met het toevoegen van uw eerste AI API. Anders ziet u Troubleshooting.

Uw eerste AI toevoegen API

Wanneer u een functie implementeert met Windows AI APIs, moet uw app eerst controleren op de beschikbaarheid van het AI-model dat die functie ondersteunt.

In het volgende fragment ziet u hoe u kunt controleren op beschikbaarheid van modellen en hoe u een antwoord genereert.

  1. Voeg in MainWindow.xaml een TextBlock toe om het LanguageModel-antwoord weer te geven.

    <TextBlock x:Name="OutputText" HorizontalAlignment="Center" VerticalAlignment="Center" />

  2. Voeg bovenaan MainWindow.xaml.cs de volgende using Microsoft.Windows.AI richtlijn toe.

    using Microsoft.Windows.AI;

  3. In MainWindow.xaml.cs, vervang de klasse MainWindow door de volgende code, die bevestigt dat het LanguageModel beschikbaar is en verzendt een prompt waarin het model wordt gevraagd te reageren met de moleculaire formule van glucose.

    public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();
        InitAI();
    }

    private async void InitAI()
    {
        OutputText.Text = "Loading..";

        if (LanguageModel.GetReadyState() == AIFeatureReadyState.EnsureNeeded)
        {
            var result = await LanguageModel.EnsureReadyAsync();
            if (result.Status != PackageDeploymentStatus.CompletedSuccess)
            {
                throw new Exception(result.ExtendedError().Message);
            }
        }            

        using LanguageModel languageModel = 
           await LanguageModel.CreateAsync();

        string prompt = "Provide the molecular formula of glucose.";
        var result = await languageModel.GenerateResponseAsync(prompt);
        OutputText.Text = result.Response;
    }
}

  4. Bouw en voer de app uit.

  5. De formule voor glucose moet worden weergegeven in het tekstblok.

Geavanceerde tutorials en APIs

Nu u de beschikbaarheid van modellen hebt gecontroleerd, kunt u het APIs verder verkennen met behulp van de verschillende Windows AI-zelfstudies API.

Probleemoplossingsproces

Als er fouten optreden, is dit meestal het gevolg van uw hardware of het ontbreken van een vereist model.

  • De Methode GetReadyState controleert of het model dat is vereist voor een AI-functie beschikbaar is op het apparaat van de gebruiker. U moet deze methode aanroepen voordat u het model aanroept.
  • Als het model niet beschikbaar is op het apparaat van de gebruiker, kunt u de methode EnsureReadyAsync aanroepen om het vereiste model te installeren. De installatie van het model wordt op de achtergrond uitgevoerd en de gebruiker kan de voortgang van de installatie controleren op de pagina Instellingen voor Windows>Windows Update.
  • De methode EnsureReadyAsync heeft een statusoptie waarmee een gebruikersinterface voor laden kan worden weergegeven. Als de gebruiker niet-ondersteunde hardware heeft, mislukt EnsureReadyAsync met een fout.

Hardwareondersteuning tijdens runtime detecteren

Windows AI APIs worden geleverd op een breed scala aan hardware (NPU, GPU, CPU) en niet elke API wordt op elk apparaat ondersteund. Uw app moet afgaan op de uitkomst van GetReadyState voordat u iets doet, inclusief het weergeven van UI die afhankelijk is van de functionaliteit:

AIFeatureReadyState Wat betekent het? Wat uw app moet doen
Ready Het model is geïnstalleerd en het apparaat ondersteunt het API. Bel de API.
NotReady of EnsureNeeded Het apparaat ondersteunt de API, maar het model moet worden gedownload of voorbereid. Geef een toestemmingsdialoogvenster weer waarin de download wordt uitgelegd (grootte, netwerkgebruik), en roep EnsureReadyAsync aan en rapporteert de voortgang aan de gebruiker.
NotSupportedOnCurrentSystem Het apparaat kan dit API niet uitvoeren (niet-compatibele hardware, ontbrekende stuurprogramma's of beleid). Roep EnsureReadyAsync niet aan. De functie verbergen of uitschakelen of terugvallen op een alternatieve implementatie (bijvoorbeeld een AI-service voor de cloud).

Zie Phi Silica → aanbevolen UX-patroon voor een end-to-endvoorbeeld van alle drie de scenario’s (inclusief de UX van het toestemmingsvenster). Hetzelfde patroon is van toepassing op elke Windows AI-API die GetReadyState beschikbaar maakt.

Opmerking

Voor APIs met aanbevolen CPU-specificaties (zoals VSR) is GetReadyState op zichzelf niet voldoende. GetReadyState geeft alleen aan of de API ondersteuning wordt ondersteund. De CPU-specificatiecontrole geeft aan of deze goed genoeg wordt uitgevoerd voor uw UX. Gebruik beide: poort beschikbaarheid met GetReadyState, poortkwaliteitskeuzen met de CPU-controle.

Zie Windows AI-probleemoplossing API en veelgestelde vragen voor meer hulp.

Zie ook

  • Last updated on