开始使用 Windows AI 构建应用 APIs
了解 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 框架的选项卡）。
WinUI
WPF
WinForms
.NET MAUI
在 Visual Studio 中，通过选择 “空白应用打包”（桌面版中的 WinUI 3）模板创建新的 WinUI 项目。
在 解决方案资源管理器中，右键单击项目节点，选择 “属性>应用程序>常规”，并确保目标框架设置为 .NET 8.0，目标 OS 设置为 10.0.22621 或更高版本。
编辑 Package.appxmanifest 文件（右键单击并选择“ 查看代码”），并添加以下代码片段。
将 systemAIModels 功能添加到
节点 systemai 中“IgnorableNamespaces”的
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
需要在TargetDeviceFamily节点中的
将以下内容添加到 .waproj、.csproj 或.vcxproj文件。 此步骤是必需的，以确保 Visual Studio 不会替代测试的最大版本。
右键单击项目节点，然后选择“ 管理 NuGet 包...”。
在 NuGet 包管理器中，选中 “包括预发行版 ”复选框，然后选择 Windows 应用 SDK 版本 1.8.250410001-experimental1。 单击“ 安装 ”或 “更新”。
确保生成配置设置为 ARM64。
生成并运行应用。
如果应用成功启动，则继续添加第一个 AI API。 否则，请参阅 故障排除。
在 Visual Studio 中，通过选择 WPF 应用程序模板创建新的 WPF 项目 。
在 解决方案资源管理器中，右键单击项目节点，然后选择 “编辑项目文件 ”以作为 XML 打开。 将内部
编辑 Package.appxmanifest 文件（右键单击并选择“ 查看代码”），并添加以下代码片段。
将 systemAIModels 功能添加到
节点 systemai 中“IgnorableNamespaces”的
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
需要在TargetDeviceFamily节点中的
将以下内容添加到 .waproj、.csproj 或.vcxproj文件。 此步骤是必需的，以确保 Visual Studio 不会替代测试的最大版本。
在 解决方案资源管理器中，右键单击 “依赖项 ”节点，然后选择“ 管理 Nuget 包...”。
在 NuGet 包管理器中，选中 “包括预发行版 ”复选框，然后选择 Windows 应用 SDK 版本 1.8.250410001-experimental1。 单击“ 安装 ”或 “更新”。
生成并运行应用。
如果应用成功启动，则继续添加第一个 AI API。 否则，请参阅 故障排除。
有关详细信息，请参阅 为 Windows 应用 SDK 支持配置 WPF 项目。
在 Visual Studio 中，通过选择 Windows 窗体应用 模板创建新的 WinForms 项目。
在 解决方案资源管理器中，右键单击项目节点 >“编辑项目文件 ”以作为 XML 打开。 将内部
编辑 Package.appxmanifest 文件（右键单击并选择“ 查看代码”），并添加以下代码片段。
将 systemAIModels 功能添加到
节点 systemai 中“IgnorableNamespaces”的
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
需要在TargetDeviceFamily节点中的
将以下内容添加到 .waproj、.csproj 或.vcxproj文件。 此步骤是必需的，以确保 Visual Studio 不会替代测试的最大版本。
在 解决方案资源管理器中，右键单击 “依赖项 ”节点 >“管理 Nuget 包...”。
在 NuGet 包管理器>浏览中，选中 “包括预发行版”，然后选择 Windows 应用 SDK 版本 1.8.250410001-experimental1。 单击“ 安装 ”或 “更新”。
生成并运行应用。
如果应用成功启动，则继续添加第一个 AI API。 否则，请参阅 故障排除。
有关详细信息，请参阅 为 Windows 应用 SDK 支持配置 WinForms 项目。
按照 生成第一个 .NET MAUI 应用的说明创建 MAUI 项目。
在 解决方案资源管理器中，右键单击项目节点 >“编辑项目文件 ”以作为 XML 打开。
在项目文件的底部，添加以下行以引用正确的 Microsoft.WindowsAppSDK 包版本（为 Windows 平台编译时）：
注释
单击项目节点并选择 “管理 NuGet 包...” 选项可用于添加所需的包，如果你的应用也在为其他平台（如 Android 和 iOS）构建，则仍需要编辑项目文件，以条件仅 Windows 版本的包引用。
将以下内容添加到 .waproj、.csproj 或.vcxproj文件。 此步骤是必需的，以确保 Visual Studio 不会替代测试的最大版本。
在 解决方案资源管理器中，右键单击项目节点，选择 “属性”，并确保目标 Windows 框架设置为 10.0.22621 或更高版本。
编辑 Package.appxmanifest 文件（右键单击并选择“ 查看代码”），并添加以下代码片段。
将 systemAIModels 功能添加到
节点 systemai 中“IgnorableNamespaces”的
xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"
需要在TargetDeviceFamily节点中的
生成并运行应用。
如果应用成功启动，则继续添加第一个 AI API。 否则，请参阅 故障排除。
添加第一个 AI API
使用 Windows AI APIs实现功能时，应用应首先检查支持该功能的 AI 模型的可用性。
以下代码片段演示如何检查模型可用性并生成响应。
WinUI
WPF
WinForms
.NET MAUI
在 MainWindow.xaml 中，添加 TextBlock 以显示 LanguageModel 响应。
在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 响应。
在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 APIs 教程中进一步探索 API。
详细了解可用的 Windows AI APIs
Phi Silica API 演练
文本识别的操作指南 API
图像处理 API 演练
故障排除
如果遇到任何错误，通常是由于硬件或缺少所需的模型。
GetReadyState 方法检查用户设备上是否提供了 AI 功能所需的模型。 在对模型的任何调用之前，必须调用此方法。
如果模型在用户的设备上不可用，则可以调用 Method EnsureReadyAsync 来安装所需的模型。 模型安装在后台运行，用户可以在 Windows 设置>Windows 更新 设置页上检查安装进度。
EnsureReadyAsync 方法具有可显示加载 UI 的状态选项。 如果用户的硬件不受支持，则 EnsureReadyAsync 将失败并出现错误。
有关更多帮助，请参阅 Windows AI API 故障排除和常见问题解答 。
另请参阅
在 Windows 上开发负责任的生成 AI 应用和功能
有关 AI 映像功能的 API 参考
Windows 应用 SDK
Windows 应用 SDK 的最新发行说明
AI 开发画廊
Windows AI API 示例
【問題】自從大更新後~好多MOD都不能用! @幻獸帕魯 哈啦板
7个有效提高工作能力的方法，助力提升效率