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

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

依賴

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

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

確認你的裝置符合你打算使用的Windows AI APIs 的硬體需求。大多數APIs需要帶有 NPU 的Copilot+ PC（我們推薦 Copilot+ PCs 開發者指南中列出的裝置）。部分 APIs 也支援在非 Copilot+ 裝置上以 GPU 或 CPU 執行——詳情請參閱支援的硬體表。
在 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 應用程式 SDK。

確認你的裝置符合你打算使用的Windows AI APIs 的硬體需求。大多數APIs需要帶有 NPU 的Copilot+ PC（我們推薦 Copilot+ PCs 開發者指南中列出的裝置）。部分 APIs 系統也支援 GPU 或 CPU 執行——詳情請參閱支援硬體表。
安裝 Windows 11 Insider Preview 版本 26120.3073（開發通道與 Beta 通道）或更新版本（若要檢查您的作業系統版本，請從 Windows 搜尋執行 winver）。
- 若要在 GPU 上使用 Phi Silica：請使用 Windows Insider Experimental Channel 建置版 26300.8553 或更新版本。
在設定>系統>供開發人員使用>中啟用開發人員模式。這對於在 GPU 上執行的 Phi Silica 是必要的。
使用特定的工作負載和元件安裝 Visual Studio ，以使用 WinUI 和 Windows 應用程式 SDK 進行開發。如需詳細資訊，請參閱必要的工作負載和元件。
若要在 GPU 上使用 Phi Silica，請使用 Windows 應用程式 SDK 版本 2.2.2-experimental9（2026 年 6 月實驗版） 或更新版本。

建置新的應用程式

下列步驟說明如何建置使用 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"
```
- 在TargetDeviceFamily節點的<Dependencies>元素中，測試的最大版本必須至少達到 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 應用程式 SDK 1.8.250410001-experimental1]。按兩下 [安裝 ] 或 [ 更新]。
確保你的建置設定設定為適合你裝置的架構（例如 ARM64 或 x64）。
建置並執行您的應用程式。
如果應用程式成功啟動，請繼續新增您的第一個 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"
```
- 在TargetDeviceFamily節點的<Dependencies>元素中，測試的最大版本必須至少達到 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 應用程式 SDK 1.8.250410001-experimental1]。按兩下 [安裝 ] 或 [ 更新]。
建置並執行您的應用程式。
如果應用程式成功啟動，請繼續新增您的第一個 AI API。否則，請參閱疑難解答。

如需詳細資訊，請參閱設定適用於 Windows 應用程式 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"
```
- 在TargetDeviceFamily節點的<Dependencies>元素中，測試的最大版本必須至少達到 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 應用程式 SDK 版本 1.8.250410001-experimental1。按兩下 [安裝 ] 或 [ 更新]。
建置並執行您的應用程式。
如果應用程式成功啟動，請繼續新增您的第一個 AI API。否則，請參閱疑難解答。

如需詳細資訊，請參閱設定適用於 Windows 應用程式 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 Packages... 」選項來新增所需的套件，但如果你的應用程式同時為其他平台（如 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>
```
- 節點 systemai 中 “IgnorableNamespaces” 的 <Package> 命名空間規範：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
```
- 在TargetDeviceFamily節點的<Dependencies>元素中，測試的最大版本必須至少達到 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 APIs 支援多種硬體（NPU、GPU、CPU），並非所有 API 都支援所有裝置。你的應用程式應先根據 GetReadyState 的結果採取不同處理，再執行任何操作，包括顯示取決於該功能的 UI：

`AIFeatureReadyState`	這是什麼意思?	你的應用程式應該做什麼
`Ready`	已安裝模型，裝置支援 API。	撥打 API。
`NotReady` 或 `EnsureNeeded`	裝置支援 API，但模型需要下載或準備。	顯示一個同意對話框，說明下載內容（大小、網路使用情況），然後呼叫 EnsureReadyAsync 向使用者回報進度。
`NotSupportedOnCurrentSystem`	裝置無法執行此程序 API （硬體不相容、驅動程式缺失或政策缺失）。	請勿致電 EnsureReadyAsync。隱藏或停用該功能，或退回其他實作（例如雲端 AI 服務）。

關於涵蓋三個分支（包括同意對話 UX）的端對端範例，請參見 Phi Silica → 推薦使用者體驗模式。同樣的模式也適用於每個公開 API 的 Windows AI 。

備註

對於具有APIs（例如 VSR）的，光靠 GetReadyState 本身是不夠的。 GetReadyState 它只會告訴你是否支援; API CPU 規格檢查則告訴你它是否 足夠符合你的 使用者體驗。兩者都要使用：搭配 GetReadyState 的閘可用性，以及搭配 CPU 檢查的閘品質選項。

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

另請參閱

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-06-11

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

依賴

建置新的應用程式

新增您的第一個 AI API

進階教學課程和 APIs

故障排除

執行時偵測硬體支援

另請參閱

意見反應

其他資源