Mulai membangun aplikasi dengan Windows AI APIs

Pelajari tentang persyaratan perangkat keras Windows AI API dan cara mengonfigurasi perangkat Anda agar berhasil membangun aplikasi menggunakan Windows AI APIs.

Dependensi

Pastikan PC Anda mendukung Windows AI APIs dan semua dependensi diinstal. Anda dapat memilih untuk melakukan ini secara otomatis (disarankan) atau secara manual.

  1. Konfirmasikan bahwa perangkat Anda memenuhi persyaratan perangkat keras untuk Windows AI APIs yang Anda rencanakan untuk digunakan. Sebagian besar APIs memerlukan Copilot+ PC dengan NPU (kami merekomendasikan perangkat yang tercantum dalam panduan pengembang Copilot+ PCs). Beberapa APIs juga mendukung eksekusi GPU atau CPU pada perangkat non-Copilot+ — lihat tabel perangkat keras yang didukung untuk detail.

  2. Jalankan perintah berikut di Terminal Windows.

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

    Ini menjalankan file Konfigurasi WinGet yang melakukan tugas berikut:

    • Memeriksa apakah versi OS memenuhi persyaratan minimum.
    • Mengaktifkan Mode Pengembang.
    • Menginstal Visual Studio Community Edition dengan WinUI dan beban kerja lain yang diperlukan.
    • Menginstal SDK Aplikasi Windows.

Membuat aplikasi baru

Langkah-langkah berikut menjelaskan cara membuat aplikasi yang menggunakan Windows AI APIs (pilih tab untuk kerangka kerja UI pilihan Anda).

  1. Di Visual Studio, buat proyek WinUI baru dengan memilih templat Aplikasi Kosong, Dipaketkan (WinUI 3 di Desktop).

    Cuplikan layar UI Proyek baru Visual Studio dengan templat WinUI dipilih.

  2. Di Penjelajah Solusi, klik kanan simpul proyek, pilih Properti>Umum Aplikasi>, dan pastikan bahwa kerangka kerja target diatur ke .NET 8.0, dan OS target diatur ke 10.0.22621 atau yang lebih baru.

    Cuplikan layar panel properti proyek Visual Studio

  3. Edit file Package.appxmanifest (klik kanan dan pilih Tampilkan kode) dan tambahkan cuplikan berikut.

    • Kemampuan systemAIModels untuk simpul <Capabilities> :

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

    • Spesifikator namespace systemai ke "IgnorableNamespaces" dalam simpul <Package> :

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

    • Versi maksimum yang diuji pada elemen TargetDeviceFamily dari simpul <Dependencies> harus setidaknya 10.0.26226.0:

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

  4. Tambahkan yang berikut ini ke file .waproj, .csproj, atau .vcxproj Anda. Langkah ini diperlukan untuk memastikan Visual Studio tidak menggantikan versi maksimum yang diuji.

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

  5. Klik kanan simpul proyek dan pilih Kelola Paket NuGet....

  6. Di Pengelola Paket NuGet, centang kotak sertakan prarilis , dan pilih SDK Aplikasi Windows versi 1.8.250410001-experimental1. Klik Instal atau Perbarui.

    Cuplikan layar manajer paket NuGet Visual Studio dengan Microsoft.WindowsAppSDK 1.8.250410001-experimental1 dipilih.

  7. Pastikan konfigurasi build Anda diatur ke arsitektur yang sesuai untuk perangkat Anda (misalnya, ARM64 atau x64).

    Cuplikan layar konfigurasi build Visual Studio disetel ke ARM64.

  8. Buat dan jalankan aplikasi Anda.

  9. Jika aplikasi berhasil diluncurkan, lanjutkan ke Tambahkan AI APIpertama Anda. Jika tidak, lihat Pemecahan Masalah.

Tambahkan AI pertama Anda API

Saat menerapkan fitur menggunakan Windows AI APIs, aplikasi Anda harus terlebih dahulu memeriksa ketersediaan model AI yang mendukung fitur tersebut.

Cuplikan berikut menunjukkan cara memeriksa ketersediaan model dan menghasilkan respons.

  1. Di MainWindow.xaml, tambahkan TextBlock untuk menampilkan respons LanguageModel .

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

  2. Di bagian atas MainWindow.xaml.cs, tambahkan arahan berikut using Microsoft.Windows.AI .

    using Microsoft.Windows.AI;

  3. Di MainWindow.xaml.cs, ganti kelas MainWindow dengan kode berikut, yang mengonfirmasi LanguageModel tersedia dan kemudian mengirimkan permintaan yang meminta model untuk merespons dengan rumus molekul glukosa.

    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. Buat dan jalankan aplikasi.

  5. Rumus untuk glukosa akan muncul di blok teks.

Tutorial tingkat lanjut dan APIs

Sekarang setelah Anda berhasil memeriksa ketersediaan model, pelajari APIs lebih dalam melalui berbagai tutorial Windows AI API.

Penyelesaian Masalah

Jika Anda mengalami kesalahan, biasanya karena perangkat keras Anda atau tidak adanya model yang diperlukan.

  • Metode GetReadyState memeriksa apakah model yang diperlukan oleh fitur AI tersedia di perangkat pengguna. Anda harus memanggil metode ini sebelum melakukan panggilan apa pun ke model.
  • Jika model tidak tersedia di perangkat pengguna, maka Anda dapat memanggil metode EnsureReadyAsync untuk menginstal model yang diperlukan. Penginstalan model berjalan di latar belakang, dan pengguna dapat memeriksa kemajuan penginstalan pada halaman Pengaturan Windows>Windows Update.
  • Metode EnsureReadyAsync memiliki opsi status yang dapat menampilkan antarmuka pengguna pemuatan. Jika pengguna memiliki perangkat keras yang tidak didukung, maka EnsureReadyAsync akan gagal dengan kesalahan.

Mendeteksi dukungan perangkat keras saat runtime

Windows AI APIs tersedia untuk berbagai jenis perangkat keras (NPU, GPU, CPU), dan tidak setiap API didukung pada setiap perangkat. Aplikasi Anda harus bercabang pada hasil GetReadyState sebelum melakukan pekerjaan apa pun, termasuk menampilkan UI yang bergantung pada fitur:

AIFeatureReadyState Apa artinya Apa yang harus dilakukan aplikasi Anda
Ready Model terinstal dan perangkat mendukung API. Panggil API.
NotReady atau EnsureNeeded Perangkat mendukung API, tetapi model perlu diunduh atau disiapkan. Tampilkan dialog persetujuan yang menjelaskan unduhan (ukuran, penggunaan jaringan), lalu panggil EnsureReadyAsync dan laporkan kemajuan kepada pengguna.
NotSupportedOnCurrentSystem Perangkat tidak dapat menjalankan ini API (perangkat keras yang tidak kompatibel, driver yang hilang, atau kebijakan). Jangan panggil EnsureReadyAsync. Sembunyikan atau nonaktifkan fitur, atau kembali ke implementasi alternatif (misalnya, layanan AI cloud).

Untuk contoh end-to-end yang mencakup ketiga cabang (termasuk UX dialog persetujuan), lihat Phi Silica → Pola UX yang direkomendasikan. Pola yang sama berlaku untuk setiap Windows AI API yang mengekspos GetReadyState.

Nota

Untuk APIs yang memiliki spesifikasi CPU yang direkomendasikan (seperti VSR), GetReadyState saja tidak cukup. GetReadyState hanya memberi tahu Anda apakah API didukung; pemeriksaan spesifikasi CPU memberi tahu Anda apakah itu akan berjalan cukup baik untuk UX Anda. Gunakan keduanya: ketersediaan gate dengan GetReadyState, opsi kualitas gate dengan pemeriksaan CPU.

Lihat Pemecahan masalah dan FAQ Windows AI API untuk bantuan selengkapnya.

Lihat juga

  • Last updated on