Начало создания приложения с помощью ИИ Windows APIs

Узнайте о требованиях к оборудованию Windows AI API и о том, как настроить устройство для успешного создания приложений с помощью ИИ APIsWindows.

Зависимости

Убедитесь, что компьютер поддерживает Windows AI APIs и все зависимости установлены. Это можно сделать автоматически (рекомендуется) или вручную.

  1. Убедитесь, что ваше устройство соответствует аппаратным требованиям к ИИ Windows APIs, который вы планируете использовать. Большинству APIs требуется Copilot+ PC с NPU (мы рекомендуем устройства, перечисленные в руководстве разработчика Copilot+ PCs). Некоторые APIs также поддерживают выполнение на GPU или ЦП на устройствах без Copilot+ — подробности см. в таблице поддерживаемого оборудования.

  2. Выполните следующую команду в терминале Windows.

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

    В результате запускается файл конфигурации WinGet , выполняющий следующие задачи:

    • Проверяет минимальную версию ОС.
    • Включает режим разработчика.
    • Устанавливает Visual Studio Community Edition с WinUI и другими необходимыми рабочими нагрузками.
    • Устанавливает пакет SDK для приложений Windows.

Создание нового приложения

Ниже описано, как создать приложение, использующее Windows AI APIs (выберите вкладку для предпочтительной платформы пользовательского интерфейса).

  1. В Visual Studio создайте новый проект WinUI, выбрав шаблон "Пустое приложение, упакованное (WinUI 3 для настольных ПК)".

    Снимок экрана: новый пользовательский интерфейс проекта Visual Studio с выбранным шаблоном WinUI.

  2. В обозревателе решений щелкните правой кнопкой мыши узел проекта, выберите "Свойства>Приложения>Общие", и убедитесь, что целевая платформа установлена на .NET 8.0, а целевая операционная система — 10.0.22621 или более поздней версии.

    Снимок экрана: область свойств проекта Visual Studio

  3. Измените файл 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" />

  4. Добавьте следующий код в файл WAPROJ, CSPROJ или .vcxproj. Этот шаг необходим для того, чтобы Visual Studio не переопределило протестированную максимальную версию.

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

  5. Щелкните правой кнопкой мыши узел проекта и выберите пункт "Управление пакетами NuGet...".

  6. В диспетчере пакетов NuGet установите флажок "Включить предварительную версию " и выберите пакет SDK для приложений Windows версии 1.8.250410001-experimental1. Нажмите кнопку "Установить " или "Обновить".

    Снимок экрана диспетчера пакетов NuGet в Visual Studio с выбранным Microsoft.WindowsAppSDK 1.8.250410001-experimental1.

  7. Убедитесь, что конфигурация сборки настроена на соответствующую архитектуру для устройства (например, ARM64 или x64).

    Снимок экрана: конфигурация сборки Visual Studio с параметром ARM64.

  8. Создайте и запустите приложение.

  9. Если приложение запускается успешно, перейдите к добавлению первого ИИ API. В противном случае см. раздел "Устранение неполадок".

Добавьте вашего первого ИИ API

При реализации функции с помощью Windows AI APIsприложение должно сначала проверить доступность модели ИИ, поддерживающей эту функцию.

В следующем фрагменте кода показано, как проверить доступность модели и создать ответ.

  1. В MainWindow.xaml добавьте TextBlock для отображения ответа LanguageModel .

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

  2. В верхней части MainWindow.xaml.cs добавьте следующие using Microsoft.Windows.AI и using Microsoft.Windows.AI.Text директивы.

    using Microsoft.Windows.AI;
using Microsoft.Windows.AI.Text;

  3. В MainWindow.xaml.cs, замените класс MainWindow следующим кодом, который подтверждает, что LanguageModel доступен, а затем отправляет запрос модели ответить с молекулярной формулой глюкозы.

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

    private async void InitAI()
    {
        OutputText.Text = "Loading..";

        var readyState = LanguageModel.GetReadyState();
        if (readyState == AIFeatureReadyState.NotReady)
        {
            var ensureResult = await LanguageModel.EnsureReadyAsync();
            if (ensureResult.Status != AIFeatureReadyResultState.Success)
            {
                throw ensureResult.ExtendedError;
            }

            readyState = LanguageModel.GetReadyState();
        }

        if (readyState != AIFeatureReadyState.Ready)
        {
            throw new Exception($"LanguageModel is unavailable: {readyState}");
        }

        using LanguageModel languageModel = 
           await LanguageModel.CreateAsync();

        string prompt = "Provide the molecular formula of glucose.";
        var result = await languageModel.GenerateResponseAsync(prompt);
        OutputText.Text = result.Text;
    }
}

  4. Создайте и запустите приложение.

  5. Формула глюкозы должна появиться в текстовом блоке.

Продвинутые учебные материалы и APIs

Теперь, когда вы успешно проверили доступность модели, продолжите изучение APIs в различных учебных пособиях по ИИ Windows API.

Устранение неполадок

Если возникают ошибки, обычно это связано с оборудованием или отсутствием требуемой модели.

  • Метод GetReadyState проверяет, доступна ли модель, требуемая функцией ИИ, на устройстве пользователя. Этот метод необходимо вызвать перед любым вызовом модели.
  • Если модель недоступна на устройстве пользователя, можно вызвать метод EnsureReadyAsync для установки требуемой модели. Установка модели выполняется в фоновом режиме, и пользователь может проверить ход установки на странице параметров>обновления Windows.
  • Метод EnsureReadyAsync имеет параметр состояния, который может отображать пользовательский интерфейс загрузки. Если у пользователя имеется неподдерживаемое оборудование, то EnsureReadyAsync завершится с ошибкой.

Определить поддержку аппаратного обеспечения на этапе выполнения

ИИ Windows APIs доступны на широком спектре аппаратного обеспечения (NPU, GPU, CPU), и не каждый API поддерживается на каждом устройстве. Ваше приложение должно выполнять действия в зависимости от результата GetReadyState прежде чем начинать какую-либо работу, включая отображение пользовательского интерфейса, зависящего от этой возможности:

AIFeatureReadyState Что это означает Что должно сделать ваше приложение
Ready Модель установлена, и устройство поддерживает API. Вызовите API.
NotReady Устройство поддерживает APIмодель, но ее необходимо скачать или подготовить. Покажите диалоговое окно согласия с объяснением параметров загрузки (размер, использование сети), затем вызовите EnsureReadyAsync и сообщайте пользователю о ходе выполнения.
DisabledByUser Пользователь отключил необходимый компонент ИИ. Попросите пользователя включить компонент в параметрах Windows или скрыть или отключить эту функцию.
NotSupportedOnCurrentSystem Устройство не может запустить это API (несовместимое оборудование, отсутствующие драйверы или политика). Не вызывайте EnsureReadyAsync. Скрыть или отключить функцию или вернуться к альтернативной реализации (например, облачной службе ИИ).

Полный пример, охватывающий все три ветви (включая диалоговое окно согласия), см. в разделе Phi Silica → шаблон рекомендуемого пользовательского интерфейса. Этот же шаблон применяется ко всем Windows AI API, которые предоставляют метод GetReadyState.

Замечание

Для APIs, у которых есть рекомендуемые характеристики ЦП (например, VSR), GetReadyState само по себе недостаточно. GetReadyState только указывает, поддерживается ли API эта спецификация. Проверка спецификации ЦП указывает, будет ли она работать достаточно хорошо для пользовательского интерфейса. Используйте оба варианта: доступность шлюза с GetReadyState, а также параметры качества шлюза с проверкой ЦП.

См. статью об устранении неполадок и часто задаваемых вопросах по API Windows AI для получения дополнительной помощи.

См. также

  • Last updated on