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.
Controleer of uw apparaat een Copilot+-pc is (we raden de apparaten aan die worden vermeld in de ontwikkelaarshandleiding voor Copilot+-pc's).
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).
Maak in Visual Studio een nieuw WinUI-project door de sjabloon Blank App, Packaged (WinUI 3 in Desktop) te selecteren.
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.
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" />
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>
Klik met de rechtermuisknop op het projectknooppunt en selecteer NuGet-pakketten beheren....
Schakel in NuGet Package Manager het selectievakje Prerelease opnemen in en selecteer Windows App SDK-versie 1.8.250410001-experimenteel1. Klik op Installeren of Bijwerken.
Zorg ervoor dat uw buildconfiguratie is ingesteld op ARM64.
Bouw en voer uw app uit.
Als de app succesvol wordt gestart, gaat u verder met het toevoegen van uw eerste AI API. Anders ziet u Troubleshooting.
Maak in Visual Studio een nieuw WPF-project door de WPF-toepassingssjabloon te selecteren.
Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteer Projectbestand bewerken om te openen als XML. Vervang alles binnenin <PropertyGroup> door het volgende:
<OutputType>WinExe</OutputType>
<TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
<RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
<Nullable>enable</Nullable>
<UseWPF>true</UseWPF>
<ImplicitUsings>enable</ImplicitUsings>
<WindowsPackageType>None</WindowsPackageType>
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" />
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>
Klik in Solution Explorer met de rechtermuisknop op het knooppunt Afhankelijkheden en selecteer Nuget-pakketten beheren....
Schakel in NuGet Package Manager het selectievakje Prerelease opnemen in en selecteer Windows App SDK-versie 1.8.250410001-experimenteel1. Klik op Installeren of Bijwerken.
Bouw en voer uw app uit.
Als de app succesvol wordt gestart, gaat u verder met het toevoegen van uw eerste AI API. Anders ziet u Troubleshooting.
Zie Uw WPF-project configureren voor Windows App SDK-ondersteuning voor meer informatie.
Maak een MAUI-project door de instructies te volgen bij Build your first .NET MAUI app.
Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt >Projectbestand bewerken om te openen als XML.
Voeg onderaan het projectbestand deze regels toe om te verwijzen naar de juiste versie van het Microsoft.WindowsAppSDK-pakket (bij het compileren van het Windows-platform):
<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
<PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.250410001-experimental1"/>
</ItemGroup>
Opmerking
Wanneer u op het projectknooppunt klikt en de optie NuGet-pakketten beheren selecteert, kan worden gebruikt om het vereiste pakket toe te voegen. Als uw app ook bouwt voor andere platforms, zoals Android en iOS, moet het projectbestand nog steeds worden bewerkt om de pakketverwijzing voor alleen-Windows-builds te bepalen.
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>
Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt, selecteer Eigenschappen en zorg ervoor dat het windows-doelframework is ingesteld op 10.0.22621 of hoger.
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" />
Bouw en voer uw app uit.
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.
Voeg in MainWindow.xaml een TextBlock toe om het LanguageModel-antwoord weer te geven.
<TextBlock x:Name="OutputText" HorizontalAlignment="Center" VerticalAlignment="Center" />
Voeg bovenaan MainWindow.xaml.cs de volgende using Microsoft.Windows.AI richtlijn toe.
using Microsoft.Windows.AI;
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;
}
}
Bouw en voer de app uit.
De formule voor glucose moet worden weergegeven in het tekstblok.
Voeg in MainWindow.xaml een TextBlock toe om het LanguageModel-antwoord weer te geven.
<TextBlock x:Name="OutputText" HorizontalAlignment="Center" VerticalAlignment="Center" />
Voeg bovenaan MainWindow.xaml.cs de volgende using Microsoft.Windows.AI richtlijn toe.
using Microsoft.Windows.AI;
Vervang in MainWindow.xaml.cs de Klasse MainWindow door de volgende code, die bevestigt dat languageModel beschikbaar is en vervolgens een prompt indient waarin wordt gevraagd om het model 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 for glucose.";
var result = await languageModel.GenerateResponseAsync(prompt);
OutputText.Text = result.Response;
}
}
Bouw en voer de app uit.
De formule voor glucose moet worden weergegeven in het tekstblok.
Zie Platformcode aanroepen voor meer informatie over het toevoegen van platformspecifieke code aan een TENANT-app.
In dit voorbeeld gebruiken we de benadering voor gedeeltelijke klassen en gedeeltelijke methoden om de Windows-code in de map Platform\Windows te plaatsen.
Voeg in MainPage.xaml.cs een gedeeltelijke methodedefinitie toe als partial void ChangeLanguageModelAvailability(); en roep die gedeeltelijke methode aan vanuit de OnCounterClicked-handler voor de CounterBtn knop die is gemaakt door de sjabloon .NET MAUI App.
Vouw Platforms uit in Solution Explorer, klik met de rechtermuisknop op Windows, selecteer Klasse toevoegen>..., typ de naam MainPage.cs en klik op Toevoegen.
De nieuwe MainPage.cs moet worden weergegeven in het editorvenster. Ga terug naar MainPage.xaml.cs om de naamruimteregel te kopiëren.
Ga terug naar de nieuwe MainPage.cs en vervang de naamruimteregel door de regel van MainPage.xaml.cs. Dit is om van de klasse Platform\Windows een gedeeltelijke uitbreiding van de basisklasse MainPage te maken.
Om van MainPage.cs een extensie te maken, vervangt u internal in de klassedeclaratie door partial.
Voeg de volgende code toe aan de gedeeltelijke methode ChangeLanguageModelAvailability die is gedefinieerd in stap 1.
partial void ChangeLanguageModelAvailability()
{
try
{
AIFeatureReadyState readyState = Microsoft.Windows.AI.LanguageModel.GetReadyState();
System.Diagnostics.Debug.WriteLine($"LanguageModel.GetReadyState: {readyState}");
}
catch (Exception e)
{
System.Diagnostics.Debug.WriteLine($"LanguageModel is not available: {e}");
}
}
Voer de app opnieuw uit, klik op de knop Klik op mij en bekijk de uitvoer in het uitvoervenster voor foutopsporing van Visual Studio.
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.
Zie Windows AI-probleemoplossing API en veelgestelde vragen voor meer hulp.
Zie ook