Prise en main de la création d’une application avec Windows AI APIs

Découvrez la configuration matérielle requise pour Windows AI API et comment configurer votre appareil pour générer des applications avec succès à l’aide de Windows AI APIs.

Dépendances

Vérifiez que votre PC prend en charge Windows AI APIs et que toutes les dépendances sont installées. Vous pouvez choisir de le faire automatiquement (recommandé) ou manuellement.

  1. Vérifiez que votre appareil répond à la configuration matérielle requise pour l’IA APIs Windows que vous envisagez d’utiliser. La plupart APIs nécessitent une Copilot+ PC avec un NPU (nous recommandons les appareils répertoriés dans le guide du développeur Copilot+ PCs). Certains APIs prennent également en charge l’exécution du GPU ou du processeur sur des appareils non Copilot+, consultez la table matérielle prise en charge pour plus d’informations.

  2. Exécutez la commande suivante dans le terminal Windows.

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

    Cela exécute un fichier de configuration WinGet qui effectue les tâches suivantes :

    • Vérifie la version minimale du système d’exploitation.
    • Active le mode développeur.
    • Installe Visual Studio Community Edition avec WinUI et d’autres charges de travail requises.
    • Installe le Kit de développement logiciel (SDK) d’application Windows.

Créer une nouvelle application

Les étapes suivantes décrivent comment créer une application qui utilise Windows AI APIs (sélectionnez l’onglet de votre infrastructure d’interface utilisateur préférée).

  1. Dans Visual Studio, créez un projet WinUI en sélectionnant le modèle Application vide, Empaquetée (WinUI 3 dans Desktop).

    Capture d’écran de la nouvelle interface utilisateur du projet Visual Studio avec le modèle WinUI sélectionné.

  2. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet, sélectionnez Propriétés>Application>Général, et vérifiez que le framework cible est défini sur .NET 8.0, et que le système d’exploitation cible est défini sur 10.0.22621 ou une version ultérieure.

    Capture d’écran du volet propriétés du projet Visual Studio

  3. Modifiez le fichier Package.appxmanifest (cliquez avec le bouton droit et sélectionnez Afficher le code) et ajoutez les extraits de code suivants.

    • Capacité systemAIModels du <Capabilities> nœud :

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

    • Le spécificateur d’espace de noms systemai sur « IgnorableNamespaces » dans le nœud <Package> :

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

    • La version maximale testée dans l’élément TargetDeviceFamily du <Dependencies> nœud doit être au moins 10.0.26226.0 :

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

  4. Ajoutez ce qui suit à votre fichier .waproj, .csproj ou .vcxproj. Cette étape est nécessaire pour vous assurer que Visual Studio ne remplace pas la version maximale testée.

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

  5. Cliquez avec le bouton droit sur le nœud du projet, puis sélectionnez Gérer les packages NuGet....

  6. Dans le Gestionnaire de package NuGet, cochez la case Inclure la préversion , puis sélectionnez Kit de développement logiciel (SDK) d’application Windows version 1.8.250410001-experimental1. Cliquez sur Installer ou Mettre à jour.

    Capture d’écran du gestionnaire de package nuget Visual Studio avec Microsoft.WindowsAppSDK 1.8.250410001-experimental1 sélectionné.

  7. Vérifiez que votre configuration de build est définie sur l’architecture appropriée pour votre appareil (par exemple , ARM64 ou x64).

    Capture d’écran de la configuration de build Visual Studio définie sur ARM64.

  8. Générez et exécutez votre application.

  9. Si l’application démarre correctement, continuez à ajouter votre première IA API. Sinon, consultez Résolution des problèmes.

Ajouter votre première IA API

Lors de l’implémentation d’une fonctionnalité à l’aide de Windows AI APIs, votre application doit d’abord vérifier la disponibilité du modèle IA qui prend en charge cette fonctionnalité.

L’extrait de code suivant montre comment vérifier la disponibilité du modèle et générer une réponse.

  1. Dans MainWindow.xaml, ajoutez un TextBlock pour afficher la réponse LanguageModel .

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

  2. En haut de MainWindow.xaml.cs, ajoutez la directive suivante using Microsoft.Windows.AI .

    using Microsoft.Windows.AI;

  3. Dans MainWindow.xaml.cs, remplacez la classe MainWindow par le code suivant, ce qui confirme que LanguageModel est disponible, puis envoie une invite demandant au modèle de répondre avec la formule moléculaire du 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. Générez et exécutez l’application.

  5. La formule de glucose doit apparaître dans le bloc de texte.

Tutoriels avancés et APIs

Maintenant que vous avez vérifié avec succès la disponibilité du modèle, explorez APIs plus en profondeur dans les tutoriels Windows AI API.

Résolution des problèmes

Si vous rencontrez des erreurs, c’est généralement en raison de votre matériel ou de l’absence d’un modèle requis.

  • La méthode GetReadyState vérifie si le modèle requis par une fonctionnalité IA est disponible sur l’appareil de l’utilisateur. Vous devez appeler cette méthode avant tout appel au modèle.
  • Si le modèle n’est pas disponible sur l’appareil de l’utilisateur, vous pouvez appeler la méthode EnsureReadyAsync pour installer le modèle requis. L’installation du modèle s’exécute en arrière-plan, et l’utilisateur peut vérifier la progression de l’installation sur la page Paramètres>Windows Update de Windows.
  • La méthode EnsureReadyAsync a une option d’état qui peut afficher une interface utilisateur de chargement. Si l’utilisateur n’a pas de matériel pris en charge, EnsureReadyAsync échoue avec une erreur.

Détecter la prise en charge matérielle au moment de l’exécution

L’IA de Windows APIs fonctionne sur une large gamme de matériel (NPU, GPU, CPU), et tous les API ne sont pas pris en charge sur tous les appareils. Votre application doit se brancher sur le résultat de GetReadyState avant d’effectuer un travail, notamment afficher l’interface utilisateur qui dépend de la fonctionnalité :

AIFeatureReadyState Ce que cela signifie Ce que votre application doit faire
Ready Le modèle est installé et l’appareil prend en charge le API. Appelez API.
NotReady ou EnsureNeeded L’appareil prend en charge le APImodèle, mais le modèle doit être téléchargé ou préparé. Affichez une boîte de dialogue de consentement expliquant le téléchargement (taille, utilisation du réseau), puis appelez EnsureReadyAsync et signalez la progression à l’utilisateur.
NotSupportedOnCurrentSystem L’appareil ne peut pas exécuter cette API opération (matériel incompatible, pilotes manquants ou stratégie). N’appelez pas EnsureReadyAsync. Masquez ou désactivez la fonctionnalité, ou revenez à une autre implémentation (par exemple, un service IA cloud).

Pour obtenir un exemple de bout en bout couvrant les trois branches (y compris l’expérience utilisateur du dialogue de consentement), consultez Phi Silicon → modèle d’expérience utilisateur recommandé. Le même modèle s’applique à toute IA Windows API qui expose GetReadyState.

Remarque

Pour APIs qui ont des spécifications CPU recommandées (telles que VSR), GetReadyState ne suffit pas à lui seul. GetReadyState indique uniquement si la API valeur est prise en charge ; la vérification des spécifications du processeur vous indique si elle s’exécutera suffisamment pour votre expérience utilisateur. Utilisez les deux : la disponibilité de la grille avec GetReadyState, et les options de qualité de la grille avec la vérification du processeur.

Pour obtenir de l’aide supplémentaire, consultez la résolution des problèmes et faq de Windows AIAPI.

Voir aussi

  • Last updated on