开始使用 Windows AI 构建应用 APIs

2025-05-21

了解 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 版本。
- 启用开发人员模式。
- 使用 WinUI 和其他必需的工作负载安装 Visual Studio Community Edition。
- 安装 Windows 应用 SDK。

确认设备是 Copilot+ 电脑（我们建议使用 Copilot+ 电脑开发人员指南中列出的设备）。
安装 Windows 11 Insider Preview 内部版本 26120.3073（开发和 Beta 频道）或更高版本（要检查操作系统版本，请从 Windows 搜索运行 winver）。
在设置>系统>为开发人员>开发人员模式中启用开发人员模式。
使用特定的工作负载和组件安装 Visual Studio ，以便使用 WinUI 和 Windows 应用 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命名空间说明符应用于<Package>节点：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
```
右键单击项目节点，然后选择“ 管理 NuGet 包...”。
在 NuGet 包管理器中，选中 “包括预发行版 ”复选框，然后选择 Windows 应用 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命名空间说明符应用于<Package>节点：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
```
在 解决方案资源管理器中，右键单击 “依赖项 ”节点，然后选择“ 管理 Nuget 包...”。
在 NuGet 包管理器中，选中 “包括预发行版 ”复选框，然后选择 Windows 应用 SDK 版本 1.8.250410001-experimental1。单击“ 安装 ”或 “更新”。
生成并运行应用。
如果应用成功启动，则继续添加第一个 AI API。否则，请参阅故障排除。

有关详细信息，请参阅为 Windows 应用 SDK 支持配置 WPF 项目。

在 Visual Studio 中，通过选择 Windows 窗体应用 模板创建新的 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命名空间说明符应用于<Package>节点：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
```
在 解决方案资源管理器中，右键单击 “依赖项 ”节点 >“管理 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 包...” 选项可用于添加所需的包，如果你的应用也在为其他平台（如 Android 和 iOS）构建，则仍需要编辑项目文件，以条件仅 Windows 版本的包引用。
在 解决方案资源管理器中，右键单击项目节点，选择 “属性”，并确保目标 Windows 框架设置为 10.0.22621 或更高版本。
编辑 Package.appxmanifest 文件（右键单击并选择“ 查看代码”），并添加以下代码片段。
- 将 systemAIModels 功能添加到 <Capabilities> 节点：
```
<Capabilities>
   <systemai:Capability Name="systemAIModels"/>
</Capabilities>
```
- 将systemai命名空间说明符应用于<Package>节点：
```
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
```
生成并运行应用。
如果应用成功启动，则继续添加第一个 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 窗体设计器中，将标签拖到绘图页上，并将其命名为 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 应用模板创建的按钮的处理程序中通过 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

成功检查模型可用性后，请在各种 Windows AI API 教程中进一步探索APIs。

故障排除

如果遇到任何错误，通常是由于硬件或缺少所需的模型。

GetReadyState 方法检查用户设备上是否提供了 AI 功能所需的模型。在对模型的任何调用之前，必须调用此方法。
如果模型在用户的设备上不可用，则可以调用 Method EnsureReadyAsync 来安装所需的模型。模型安装在后台运行，用户可以在 Windows 设置>Windows 更新 设置页上检查安装进度。
EnsureReadyAsync 方法具有可显示加载 UI 的状态选项。如果用户的硬件不受支持，则 EnsureReadyAsync 将失败并出现错误。

有关更多帮助，请参阅 Windows AI API 故障排除和常见问题解答。

通过