Erste Schritte beim Erstellen einer App mit Windows AI APIs

Erfahren Sie mehr über die Hardwareanforderungen für Windows AI API und wie Sie Ihr Gerät so konfigurieren, dass Apps mit der Windows-KI APIserfolgreich erstellt werden.

Abhängigkeiten

Stellen Sie sicher, dass Ihr PC Windows AI APIs unterstützt und alle Abhängigkeiten installiert sind. Sie können dies automatisch (empfohlen) oder manuell ausführen.

  1. Vergewissern Sie sich, dass Ihr Gerät die Hardwareanforderungen für die Windows AI APIs erfüllt, die Sie verwenden möchten. Die meisten APIs erfordern einen Copilot+ PC mit einer NPU (wir empfehlen die im Entwicklerhandbuch für Copilot+ PCs aufgeführten Geräte). Einige APIs unterstützen auch die GPU- oder CPU-Ausführung auf Nicht-Copilot+-Geräten – Einzelheiten finden Sie in der Tabelle zur unterstützten Hardware.

  2. Führen Sie den folgenden Befehl in Windows-Terminal aus.

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

    Dadurch wird eine WinGet-Konfigurationsdatei ausgeführt, die die folgenden Aufgaben ausführt:

    • Sucht nach der Mindestversion des Betriebssystems.
    • Aktiviert den Entwicklermodus.
    • Installiert Visual Studio Community Edition mit WinUI und anderen erforderlichen Workloads.
    • Installiert das Windows App SDK.

Erstellen einer neuen App

In den folgenden Schritten wird beschrieben, wie Sie eine App erstellen, die Windows AI APIs verwendet (wählen Sie die Registerkarte für Ihr bevorzugtes Benutzeroberflächenframework aus).

  1. Erstellen Sie in Visual Studio ein neues WinUI-Projekt, indem Sie die Vorlage "Leere App" (WinUI 3 in Desktop) auswählen.

    Screenshot der neuen Project-Benutzeroberfläche von Visual Studio mit ausgewählter WinUI-Vorlage.

  2. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, wählen Sie Eigenschaften>Anwendung>Allgemein aus, und stellen Sie sicher, dass das Zielframework auf .NET 8.0 festgelegt ist, und das Zielbetriebssystem auf 10.0.22621 oder höher festgelegt ist.

    Screenshot des Visual Studio-Projekteigenschaftenbereichs

  3. Bearbeiten Sie die Datei "Package.appxmanifest" (klicken Sie mit der rechten Maustaste, und wählen Sie "Code anzeigen") aus, und fügen Sie die folgenden Codeausschnitte hinzu.

    • Die Funktion systemAIModels für den Knoten<Capabilities>:

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

    • Der systemai Namespacebezeichner für "IgnorableNamespaces" im <Package> Knoten:

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

    • Die maximale Version, die im TargetDeviceFamily-Element des <Dependencies>-Knotens getestet werden muss, ist mindestens 10.0.26226.0.

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

  4. Fügen Sie der Datei ".waproj", ".csproj" oder ".vcxproj" Folgendes hinzu. Dieser Schritt ist erforderlich, um sicherzustellen, dass Visual Studio die getestete max. Version nicht außer Kraft setzt.

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

  5. Klicken Sie mit der rechten Maustaste auf den Projektknoten, und wählen Sie "NuGet-Pakete verwalten" aus.

  6. Aktivieren Sie im NuGet-Paket-Manager das Kontrollkästchen Vorabversion einschließen , und wählen Sie Windows App SDK Version 1.8.250410001-experimental1 aus. Klicken Sie auf "Installieren " oder "Aktualisieren".

    Screenshot des Visual Studio-Nuget-Paket-Managers mit ausgewählter Option

  7. Stellen Sie sicher, dass die Buildkonfiguration auf die entsprechende Architektur für Ihr Gerät festgelegt ist (z. B. ARM64 oder x64).

    Screenshot der Visual Studio-Buildkonfiguration, die auf ARM64 festgelegt ist.

  8. Erstellen sie Ihre App, und führen Sie sie aus.

  9. Wenn die App erfolgreich gestartet wird, fahren Sie mit dem Hinzufügen Ihrer ersten KI APIfort. Andernfalls finden Sie Informationen zur Problembehandlung.

Hinzufügen Ihrer ersten KI API

Bei der Implementierung eines Features mit Windows AI APIssollte Ihre App zuerst überprüfen, ob das KI-Modell verfügbar ist, das dieses Feature unterstützt.

Der folgende Codeausschnitt zeigt, wie Sie die Modellverfügbarkeit überprüfen und eine Antwort generieren.

  1. Fügen Sie in "MainWindow.xaml" einen TextBlock hinzu, um die LanguageModel-Antwort anzuzeigen.

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

  2. Fügen Sie oben in MainWindow.xaml.cs die folgende using Microsoft.Windows.AI Direktive hinzu.

    using Microsoft.Windows.AI;

  3. Ersetzen Sie die MainWindow.xaml.cs durch den folgenden Code, der bestätigt, dass das LanguageModel verfügbar ist, und anschließend eine Eingabeaufforderung sendet, in der das Modell aufgefordert wird, mit der molekularen Formel von Glukose zu antworten.

    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. Erstellen Sie die App und führen Sie sie aus.

  5. Die Formel für Glukose sollte im Textblock angezeigt werden.

Erweiterte Tutorials und APIs

Nachdem Sie nun erfolgreich die Modellverfügbarkeit geprüft haben, können Sie die APIs in den verschiedenen Windows AI API Tutorials weiter erkunden.

Problembehandlung

Wenn Fehler auftreten, liegt dies in der Regel an Der Hardware oder dem Fehlen eines erforderlichen Modells.

  • Die GetReadyState-Methode überprüft, ob das für ein KI-Feature erforderliche Modell auf dem Gerät des Benutzers verfügbar ist. Sie müssen diese Methode vor einem Aufruf des Modells aufrufen.
  • Wenn das Modell auf dem Gerät des Benutzers nicht verfügbar ist, können Sie die Methode EnsureReadyAsync aufrufen, um das erforderliche Modell zu installieren. Die Modellinstallation läuft im Hintergrund, und der Benutzer kann den Installationsfortschritt auf der Seite Windows-Einstellungen>Windows Update überprüfen.
  • Die EnsureReadyAsync-Methode verfügt über eine Statusoption, mit der eine Ladebenutzeroberfläche angezeigt werden kann. Wenn der Benutzer nicht unterstützte Hardware hat, schlägt "EnsureReadyAsync " mit einem Fehler fehl.

Hardwareunterstützung zur Laufzeit erkennen

Windows AI APIs werden auf einer breiten Palette von Hardware (NPU, GPU, CPU) ausgeliefert, und nicht jedes API wird auf jedem Gerät unterstützt. Ihre App sollte den weiteren Ablauf vom Ergebnis von GetReadyState abhängig machen, bevor sie irgendeine Arbeit ausführt, einschließlich der Anzeige einer Benutzeroberfläche, die von der Funktion abhängt:

AIFeatureReadyState Was dies bedeutet Was Ihre App tun sollte
Ready Das Modell ist installiert und das Gerät unterstützt API. Rufen Sie API auf.
NotReady oder EnsureNeeded Das Gerät unterstützt das APIModell, muss jedoch heruntergeladen oder vorbereitet werden. Zeigen Sie ein Zustimmungsdialogfeld an, in dem der Download erläutert wird (Größe, Netzwerknutzung), und rufen Sie "EnsureReadyAsync " auf, und melden Sie dem Benutzer den Fortschritt.
NotSupportedOnCurrentSystem Das Gerät kann dies API nicht ausführen (inkompatible Hardware, fehlende Treiber oder Richtlinien). Rufen Sie "EnsureReadyAsync" nicht auf. Blenden Sie die Funktion aus oder deaktivieren Sie sie, oder weichen Sie auf eine alternative Implementierung aus (z. B. einen Cloud-KI-Dienst).

Ein End-to-End-Beispiel, das alle drei Pfade abdeckt (einschließlich der UX des Zustimmungsdialogs), finden Sie unter Phi Silica → empfohlenes UX-Muster. Das gleiche Muster gilt für jede Windows AI API, die GetReadyState verfügbar macht.

Hinweis

Für APIs, die empfohlene CPU-Spezifikationen haben (wie VSR), reicht GetReadyState allein nicht aus. GetReadyState gibt nur an, ob die API CPU-Spezifikation unterstützt wird. Die CPU-Spezifikationsüberprüfung teilt Ihnen mit, ob sie gut genug für Ihre UX ausgeführt wird. Verwenden Sie beide: Gate-Verfügbarkeit mit GetReadyState, Auswahlmöglichkeiten der Gate-Qualität mit der CPU-Prüfung.

Weitere Hilfe finden Sie unter Problembehandlung und häufig gestellte Fragen zu Windows AIAPI.

Siehe auch

  • Last updated on