開始使用 Windows AI 建置應用程式 APIs

2025-06-27

瞭解 Windows AI API 硬體需求，以及如何設定您的裝置，以使用 Windows AI APIs成功建置應用程式。

依賴

請確定您的電腦支援 Windows AI APIs ，並已安裝所有相依性。您可以選擇自動執行此動作（建議）或手動執行。

自動化相依性安裝（建議）
手動相依性安裝

確認您的裝置是 Copilot+ 計算機（我們建議在 Copilot+ 計算機開發人員指南中列出的裝置）。
在 Windows 終端機中執行下列命令。
```
winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/learn_wcr.winget
```
這會執行執行下列工作的 WinGet 組態檔：
- 檢查最低作業系統 (OS) 版本。
- 啟用開發人員模式。
- 安裝 Visual Studio Community Edition，包含 WinUI 和其他必要的工作負載。
- 安裝 Windows App SDK。

確認您的裝置是 Copilot+ 計算機（我們建議 Copilot+ 電腦開發人員指南中列出的裝置。
安裝 Windows 11 Insider Preview 版本 26120.3073（開發通道與 Beta 通道）或更新版本（若要檢查您的作業系統版本，請從 Windows 搜尋執行 winver）。
在設定>系統>供開發人員使用>中啟用開發人員模式。
使用特定的工作負載和元件安裝 Visual Studio ，以使用 WinUI 和 Windows App SDK 進行開發。如需詳細資訊，請參閱必要的工作負載和元件。

建置新的應用程式

下列步驟說明如何建置使用 Windows AI APIs 的應用程式（選取您慣用 UI 架構的索引標籤）。

在 Visual Studio 中，選擇 空白應用程式，已封裝（WinUI 3 在桌面） 範本，以建立新的 WinUI 專案。
在 [方案總管] 中，以滑鼠右鍵按兩下項目節點，選取 [ 屬性>應用程式>一般]，並確定目標架構設定為 .NET 8.0，並將目標OS設定為 10.0.22621 或更新版本。
編輯 Package.appxmanifest 檔案（以滑鼠右鍵按兩下並選取 [ 檢視程式代碼]，然後新增下列代碼段。
- 節點 systemAIModels 的功能 <Capabilities> ：
```
<Capabilities>
   <systemai:Capability Name="systemAIModels"/>
</Capabilities>
```
- 節點 systemai 中 “IgnorableNamespaces” 的 <Package> 命名空間規範：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
```
- 在<Dependencies>節點的TargetDeviceFamily元素中，測試的最大版本必須至少達到 10.0.26226.0:
```
<TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
```

將下列內容新增至 .waproj、.csproj 或 .vcxproj 檔案。進行此步驟是為了確保 Visual Studio 不會覆寫測試的最大版本。

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

以滑鼠右鍵按兩下項目節點，然後選取 [管理 NuGet 套件...]。
在 NuGet 套件管理員中，核取 [包含發行前版本 ] 複選框，然後選取 [Windows App SDK 1.8.250410001-experimental1]。按兩下 [安裝 ] 或 [ 更新]。
請確定您的組建組態已設定為 ARM64。
建置並執行您的應用程式。
如果應用程式成功啟動，請繼續新增您的第一個 AI API。否則，請參閱疑難解答。

在 Visual Studio 中，選取 WPF 應用程式 範本來建立新的 WPF 專案。

在 [方案總管] 中，以滑鼠右鍵按兩下項目節點，然後選取 [ 編輯項目檔 ] 以開啟為 XML。將 <PropertyGroup> 內部的所有內容替換為以下內容：

<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>

編輯 Package.appxmanifest 檔案（以滑鼠右鍵按兩下並選取 [ 檢視程式代碼]，然後新增下列代碼段。
- 節點 systemAIModels 的功能 <Capabilities> ：
```
<Capabilities>
   <systemai:Capability Name="systemAIModels"/>
</Capabilities>
```
- 節點 systemai 中 “IgnorableNamespaces” 的 <Package> 命名空間規範：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
```
- <Dependencies> 節點中的 TargetDeviceFamily 元素所測試的最大版本必須至少為 10.0.26226.0：
```
<TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
```

將下列內容新增至 .waproj、.csproj 或 .vcxproj 檔案。執行此步驟是必須的，以確保 Visual Studio 不會覆寫測試的最大版本。

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

在 [方案總管] 中，以滑鼠右鍵按兩下 [ 相依性 ] 節點，然後選取 [ 管理 Nuget 套件...]。
在 NuGet 套件管理員中，核取 [包含發行前版本 ] 複選框，然後選取 [Windows App SDK 1.8.250410001-experimental1]。按兩下 [安裝 ] 或 [ 更新]。
建置並執行您的應用程式。
如果應用程式成功啟動，請繼續新增您的第一個 AI API。否則，請參閱疑難解答。

如需詳細資訊，請參閱設定適用於 Windows App SDK 支援的 WPF 專案。

在 Visual Studio 中，選取 Windows Forms 應用程式 範本來建立新的 WinForms 專案。

在[方案總管]中，右鍵按一下專案節點 >編輯項目檔 以 XML 格式開啟。將 <PropertyGroup> 內部的所有內容替換為以下內容：

<OutputType>WinExe</OutputType>
<TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
<RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
<Nullable>enable</Nullable>
<UseWindowsForms>true</UseWindowsForms>
<ImplicitUsings>enable</ImplicitUsings>
<WindowsPackageType>None</WindowsPackageType>

編輯 Package.appxmanifest 檔案（以滑鼠右鍵按兩下並選取 [ 檢視程式代碼]，然後新增下列代碼段。
- 節點 systemAIModels 的功能 <Capabilities> ：
```
<Capabilities>
   <systemai:Capability Name="systemAIModels"/>
</Capabilities>
```
- 節點 systemai 中 “IgnorableNamespaces” 的 <Package> 命名空間規範：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
```
- 節點<Dependencies>中的TargetDeviceFamily元素測試的最大版本需要至少為 10.0.26226.0。
```
<TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
```

將下列內容新增至 .waproj、.csproj 或 .vcxproj 檔案。您必須執行此步驟，以確保 Visual Studio 不會取代測試中最大版本。

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

在 [方案總管] 中，以滑鼠右鍵按兩下 [ 相依性 ] 節點 >[管理 Nuget 套件...]。
在 NuGet 套件管理員>瀏覽中，勾選 包含發行前版本，然後選取 Windows App SDK 版本 1.8.250410001-experimental1。按兩下 [安裝 ] 或 [ 更新]。
建置並執行您的應用程式。
如果應用程式成功啟動，請繼續新增您的第一個 AI API。否則，請參閱疑難解答。

如需詳細資訊，請參閱設定適用於 Windows App SDK 支援的 WinForms 專案。

遵循建置第一個 .NET MAUI 應用程式的指示，建立MAUI專案。
在[方案總管]中，右鍵按一下專案節點 >編輯項目檔 以 XML 格式開啟。
在項目檔底部，新增這幾行以參考正確的 Microsoft.WindowsAppSDK 套件版本（針對 Windows 平臺進行編譯時）：
```
<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.250410001-experimental1"/> 
</ItemGroup>
```
備註

當您按兩下項目節點並選取 [ 管理 NuGet 套件... ] 選項時，可以用來新增必要的套件，如果您的應用程式也正在建置其他平臺，例如Android和iOS，專案檔仍需要編輯，才能為僅限 Windows 組建的套件參考設定條件。

將下列內容新增至 .waproj、.csproj 或 .vcxproj 檔案。您必須執行此步驟，以確保 Visual Studio 不會覆寫已測試的最高版本。

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

在 [方案總管] 中，以滑鼠右鍵按一下專案節點，選取 [屬性]，並確定 [目標 Windows Framework] 設定為 10.0.22621 或更新版本。
編輯 Package.appxmanifest 檔案（以滑鼠右鍵按兩下並選取 [ 檢視程式代碼]，然後新增下列代碼段。
- 節點 systemAIModels 的功能 <Capabilities> ：
```
<Capabilities>
   <systemai:Capability Name="systemAIModels"/>
</Capabilities>
```
- 在節點 <Package> 中指定“IgnorableNamespaces”命名空間規範符 systemai：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
```
- 在節點 <Dependencies> 的元素 TargetDeviceFamily 中測試的最大版本必須至少為 10.0.26226.0：
```
<TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
```
建置並執行您的應用程式。
如果應用程式成功啟動，請繼續新增您的第一個 AI API。否則，請參閱疑難解答。

新增您的第一個 AI API

使用 Windows AI APIs實作功能時，您的應用程式應該先檢查支援該功能的 AI 模型可用性。

下列代碼段示範如何檢查模型可用性併產生回應。

在MainWindow.xaml中，新增 TextBlock 以顯示 LanguageModel 回應。

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

在MainWindow.xaml.cs頂端，新增下列 using Microsoft.Windows.AI 指示詞。
```
using Microsoft.Windows.AI; 
```

在 MainWindow.xaml.cs中，以下列程序代碼取代 MainWindow 類別，確認 LanguageModel 可供使用，然後提交提示要求模型以回應血糖分子公式。

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;
    }
}

建置並執行應用程式。
血糖的公式應該會出現在文本塊中。

在MainWindow.xaml中，新增 TextBlock 以顯示 LanguageModel 回應。

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

在MainWindow.xaml.cs頂端，新增下列 using Microsoft.Windows.AI 指示詞。
```
using Microsoft.Windows.AI; 
```

在MainWindow.xaml.cs中，以下列程式代碼取代 MainWindow 類別，確認 LanguageModel 可供使用，然後提交提示要求模型響應血糖分子公式。

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;
    }
}

建置並執行應用程式。
血糖的公式應該會出現在文本塊中。

在 Windows Forms 設計工具中，將標籤拖曳至頁面，並將它命名為 OutputLabel。
在Form1.cs頂端，新增下列 using Microsoft.Windows.AI 指示詞。
```
using Microsoft.Windows.AI; 
```

在Form.cs中，將 Form 類別取代為下列程式代碼，確認 LanguageModel 可供使用，然後提交提示要求模型以血糖分子公式回應。

public partial class Form1 : Window
{
    public Form1()
    {
        this.InitializeComponent();
        InitAI();
    }

    private async void InitAI()
    {
        OutputLabel.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);
        OutputLabel.Text = result.Response;
    }
}

建置並執行應用程式。
血糖的公式應該會出現在文本塊中。

如需將平臺特定程式代碼新增至 MAUI 應用程式的詳細資訊，請參閱調用平臺特定程式代碼。

在此範例中，我們使用部分類別和部分方法方法，將 Windows 程式代碼放在 Platform\Windows 資料夾中。

在 MainPage.xaml.cs中，將部分方法定義新增為 partial void ChangeLanguageModelAvailability(); ，並從 .NET MAUI 應用程式範本所建立按鈕的 OnCounterClicked 處理程式 CounterBtn 呼叫該部分方法。
在 [方案總管] 中，展開 [平臺]，以滑鼠右鍵點擊 [Windows]，選取 [新增類別...]，輸入名稱 MainPage.cs，然後按一下 [新增]。
新的MainPage.cs應該顯示在編輯器視窗中。切換回MainPage.xaml.cs以複製其命名空間行。
切換回新的 MainPage.cs，並將其命名空間行替換為 MainPage.xaml.cs 中的相應行。這是為了讓 Platform\Windows 類別成為基底 MainPage 類別的部分擴充。
若要完成 MainPage.cs 擴充功能，請將 internal 在類別宣告中替換為 partial。

將下列程式代碼新增至步驟 1 中定義的 ChangeLanguageModelAvailability 部分方法。

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}"); 
   } 
}

再次執行應用程式，按兩下 [ 按兩下我 ] 按鈕，並觀察Visual Studio偵錯輸出窗格中的輸出。

進階教學課程和 APIs

既然您已成功檢查模型可用性，請進一步探索 APIs 界面，以了解各種 Windows AI 教學課程 API。

故障排除

如果您遇到任何錯誤，通常是因為您的硬體或缺少必要的模型。

GetReadyState 方法會檢查用戶裝置上是否有 AI 功能所需的模型。您必須在進行任何模型操作之前先呼叫此方法。
如果模型無法在用戶的裝置上使用，您可以呼叫 EnsureReadyAsync 方法來安裝所需的模型。模型安裝會在背景執行，用戶可以在 Windows 設定>Windows Update 設定頁面上檢查安裝進度。
EnsureReadyAsync 方法具有可顯示載入 UI 的狀態選項。如果用戶的硬體不受支援， 則 EnsureReadyAsync 將會失敗並出現錯誤。

如需更多協助，請參閱 Windows AI API 疑難解答和常見問題。

共用方式為

開始使用 Windows AI 建置應用程式 APIs

依賴

建置新的應用程式

新增您的第一個 AI API

進階教學課程和 APIs

故障排除

另請參閱

意見反應

其他資源