Windows AI ile uygulama oluşturmaya başlama APIs

Windows AI donanım gereksinimlerini ve cihazınızı Windows AI APIAPIs kullanarak başarıyla uygulama geliştirmek için nasıl yapılandıracağınızı öğrenin.

Bağımlılıklar

Bilgisayarınızın Windows AI'yi APIs desteklediğini ve tüm bağımlılıkların yüklü olduğundan emin olun. Bunu otomatik olarak (önerilen) veya el ile yapmayı seçebilirsiniz.

  1. Cihazınızın kullanmayı planladığınız Windows yapay zeka APIs için donanım gereksinimlerini karşıladığını onaylayın. Çoğu APIs NPU'ya sahip bir Copilot+ PC gerektirir (Copilot+ PCs geliştirici kılavuzunda listelenen cihazları öneririz). Bazı APIs ayrıca Copilot+ olmayan cihazlarda GPU veya CPU üzerinde çalıştırmayı da destekler; ayrıntılar için desteklenen donanım tablosuna bakın.

  2. Windows Terminali'nde aşağıdaki komutu çalıştırın.

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

    Bu, aşağıdaki görevleri gerçekleştiren bir WinGet Yapılandırma dosyası çalıştırır:

    • En düşük işletim sistemi sürümünü denetler.
    • Geliştirici Modunu etkinleştirir.
    • Visual Studio Community Edition'ı WinUI ve diğer gerekli iş yükleriyle yükler.
    • Windows Uygulama SDK'sını yükler.

Yeni uygulama oluşturma

Aşağıdaki adımlar, Windows AI APIs kullanan bir uygulamanın nasıl derlendiğini açıklar (tercih ettiğiniz UI çerçevesi için sekmeyi seçin).

  1. Visual Studio'da Boş Uygulama, Paketlenmiş (Masaüstünde WinUI 3) şablonunu seçerek yeni bir WinUI projesi oluşturun.

    WinUI şablonunun seçili olduğu Visual Studio yeni Proje kullanıcı arabiriminin ekran görüntüsü.

  2. Çözüm Gezgini'nde proje düğümüne sağ tıklayın, Özellikler>Uygulama>Genel'i seçin ve hedef çerçevenin .NET 8.0 olarak ayarlandığından ve hedef işletim sisteminin 10.0.22621 veya sonraki bir sürüme ayarlandığından emin olun.

    Visual Studio proje özellikleri bölmesinin ekran görüntüsü

  3. Package.appxmanifest dosyasını düzenleyin (sağ tıklayın ve Kodu görüntüle'yi seçin) ve aşağıdaki kod parçacıklarını ekleyin.

    • systemAIModels Düğümün <Capabilities> özelliği:

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

    • systemai ad alanı belirticisini <Package> düğümde "IgnorableNamespaces" olarak tanımlama:

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

    • Düğümün TargetDeviceFamily<Dependencies> öğesinde test edilen en yüksek sürüm en az 10.0.26226.0 olmalıdır:

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

  4. .waproj, .csproj veya .vcxproj dosyanıza aşağıdakileri ekleyin. Visual Studio'nun test edilen en yüksek sürümü geçersiz kılmadığından emin olmak için bu adım gereklidir.

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

  5. Proje düğümüne sağ tıklayın ve NuGet Paketlerini Yönet...'i seçin.

  6. NuGet Paket Yöneticisi'ndeÖn sürümü dahil et onay kutusunu işaretleyin ve Windows Uygulama SDK'sı sürüm 1.8.250410001-experimental1'i seçin. Yükle veya Güncelleştir'e tıklayın.

    Microsoft.WindowsAppSDK 1.8.250410001-experimental1 öğesinin seçili olduğu Visual Studio nuget paket yöneticisinin ekran görüntüsü.

  7. Derleme yapılandırmanızın cihazınız için uygun mimariye (örneğin , ARM64 veya x64 ) ayarlandığından emin olun.

    ARM64 olarak ayarlanmış Visual Studio derleme yapılandırmasının ekran görüntüsü.

  8. Uygulamanızı derleyin ve çalıştırın.

  9. Uygulama başarıyla başlatılırsa İlk yapay zekanızı APIekleme bölümüne geçin. Aksi takdirde sorun giderme bölümüne bakın.

İlk yapay zekanızı ekleme API

Windows AI APIskullanarak bir özellik uygularken uygulamanız önce bu özelliği destekleyen yapay zeka modelinin kullanılabilirliğini denetlemelidir.

Aşağıdaki kod parçacığında model kullanılabilirliğini denetleme ve yanıt oluşturma işlemi gösterilmektedir.

  1. MainWindow.xaml'de LanguageModel yanıtını görüntülemek için bir TextBlock ekleyin.

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

  2. MainWindow.xaml.cs en üstüne aşağıdaki using Microsoft.Windows.AI yönergeyi ekleyin.

    using Microsoft.Windows.AI;

  3. içinde MainWindow.xaml.csMainWindow sınıfını, LanguageModel'in kullanılabilir olduğunu onaylayan ve ardından modelin glikoz moleküler formülüyle yanıt vermesini isteyen bir istem gönderen aşağıdaki kodla değiştirin.

    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. Uygulamayı derleyin ve çalıştırın.

  5. Glikoz formülü metin bloğunda görünmelidir.

Gelişmiş eğitimler ve APIs

Model kullanılabilirliğini başarıyla denetlediğinize göre, çeşitli Windows AI APIs öğreticilerinde daha fazla bilgi edininAPI.

Sorun giderme

Herhangi bir hatayla karşılaşırsanız, bunun nedeni genellikle donanımınız veya gerekli bir modelin olmamasıdır.

  • GetReadyState yöntemi, bir yapay zeka özelliği için gereken modelin kullanıcının cihazında kullanılabilir olup olmadığını denetler. Modele herhangi bir çağrı yapmadan önce bu yöntemi çağırmanız gerekir.
  • Model kullanıcının cihazında kullanılamıyorsa, gerekli modeli yüklemek için EnsureReadyAsync yöntemini çağırabilirsiniz. Model yüklemesi arka planda çalışır ve kullanıcı Windows Ayarları Windows Update Ayarları> sayfasında yükleme ilerleme durumunu denetleyebilir.
  • EnsureReadyAsync yönteminin yükleme kullanıcı arabirimini gösterebilen bir durum seçeneği vardır. Kullanıcının desteklenmeyen donanımı varsa EnsureReadyAsync bir hatayla başarısız olur.

Çalışma zamanında donanım desteğini algılama

Windows AI APIs çok çeşitli donanımlarda (NPU, GPU, CPU) birlikte gelir ve her API her cihazda desteklenmez. Uygulamanızın herhangi bir iş yapmadan önce GetReadyState sonucuna dallanmalı ve özelliğe bağlı kullanıcı arabirimi gösterilmelidir:

AIFeatureReadyState Ne anlama gelir? Uygulamanızın yapması gerekenler
Ready Model yüklenmiştir ve cihaz API destekler. API öğesini çağırın.
NotReady veya EnsureNeeded Cihaz API destekliyor, ancak modelin indirilmesi veya hazırlanması gerekiyor. İndirmeyi (boyut, ağ kullanımı) açıklayan bir onay iletişim kutusu gösterin, ardından EnsureReadyAsync'i çağırın ve kullanıcıya ilerleme durumunu bildirin.
NotSupportedOnCurrentSystem Cihaz bunu API çalıştıramıyor (uyumsuz donanım, eksik sürücüler veya ilke). EnsureReadyAsync'i çağırmayın. Özelliği gizleyin veya devre dışı bırakın ya da alternatif bir uygulamaya (örneğin, bir bulut yapay zeka hizmeti) geri dönün.

Üç dalı da kapsayan uçtan uca örnek için (onay iletişim kutusu UX dahil), bkz. Phi Silika → Önerilen UX düzeni. Aynı desen, API kullanıma sunan her Windows yapay zeka için geçerlidir.

Uyarı

APIs (VSR gibi) sahip için GetReadyState tek başına yeterli değildir. GetReadyState, yalnızca API'in desteklenip desteklenmediğini söyler; CPU özellik denetimi ise UX'iniz için yeterince iyi çalışıp çalışmayacağını söyler. Her ikisini de kullanın: GetReadyState ile geçit kullanılabilirliği, CPU denetiminde geçit kalitesi seçenekleri.

Daha fazla yardım için bkz. Windows AI API sorun giderme ve SSS .

Ayrıca bakınız

  • Last updated on