Comienza a crear una aplicación con IA de Windows APIs

Obtenga información sobre los requisitos de hardware de la inteligencia artificial API de Windows y cómo configurar el dispositivo para compilar correctamente aplicaciones mediante la IA APIsde Windows.

Dependencias

Asegúrese de que el equipo es compatible con la IA APIs de Windows y de que todas las dependencias están instaladas. Puede optar por hacerlo automáticamente (recomendado) o manualmente.

  1. Asegúrese de que su dispositivo cumpla los requisitos de hardware de la función Windows AI APIs que planea usar. La mayoría de APIs requieren un Copilot+ PC con una NPU (se recomiendan los dispositivos enumerados en la guía para desarrolladores de Copilot+ PCs). Algunos APIs también admiten la ejecución de GPU o CPU en dispositivos que no Copilot+: consulte la tabla de hardware compatible para obtener más información.

  2. Ejecute el siguiente comando en Terminal Windows.

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

    Esto ejecuta un archivo de configuración de WinGet que realiza las tareas siguientes:

    • Comprueba si hay una versión mínima del sistema operativo.
    • Habilita el modo de desarrollador.
    • Instala Visual Studio Community Edition con WinUI y otras cargas de trabajo necesarias.
    • Instala el SDK de aplicaciones de Windows.

Compilación de una nueva aplicación

En los pasos siguientes se describe cómo crear una aplicación que use la IA APIs de Windows (seleccione la pestaña del marco de interfaz de usuario que prefiera).

  1. En Visual Studio, cree un nuevo proyecto de WinUI seleccionando la plantilla Aplicación vacía, Empaquetada (WinUI 3 en escritorio).

    Captura de pantalla de la nueva interfaz de usuario del proyecto de Visual Studio con la plantilla winUI seleccionada.

  2. En el Explorador de soluciones, haga clic con el botón derecho en el nodo del proyecto, seleccione Propiedades>General de la> y asegúrese de que la plataforma de destino esté establecida en .NET 8.0 y el sistema operativo de destino esté establecido en 10.0.22621 o posterior.

    Captura de pantalla del panel de propiedades del proyecto de Visual Studio

  3. Edite el archivo Package.appxmanifest (haga clic con el botón derecho y seleccione Ver código) y agregue los siguientes fragmentos de código.

    • La funcionalidad systemAIModels para el nodo <Capabilities>:

      <Capabilities>
   <systemai:Capability Name="systemAIModels"/>
</Capabilities>

    • El especificador de espacios de nombres systemai para "IgnorableNamespaces" en el nodo <Package>:

      xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
IgnorableNamespaces="uap rescap systemai"

    • La versión máxima probada en el TargetDeviceFamily elemento del <Dependencies> nodo debe ser al menos 10.0.26226.0:

      <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />

  4. Agregue lo siguiente al archivo .waproj, .csproj o .vcxproj. Este paso es necesario para asegurarse de que Visual Studio no invalide la versión máxima probada.

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

  5. Haga clic con el botón derecho en el nodo del proyecto y seleccione Administrar paquetes NuGet....

  6. En el Administrador de paquetes NuGet, active la casilla Incluir versión preliminar y seleccione SDK de Aplicaciones para Windows versión 1.8.250410001-experimental1. Haga clic en Instalar o actualizar.

    Captura de pantalla del administrador de paquetes nuget de Visual Studio con Microsoft.WindowsAppSDK 1.8.250410001-experimental1 seleccionado.

  7. Asegúrese de que la configuración de compilación esté establecida en la arquitectura adecuada para el dispositivo (por ejemplo, ARM64 o x64).

    Captura de pantalla de la configuración de compilación de Visual Studio establecida en ARM64.

  8. Compile y ejecute la aplicación.

  9. Si la aplicación se inicia correctamente, continúe con Agregar su primera IAAPI. De lo contrario, consulte Solución de problemas.

Añade tu primera inteligencia artificial API

Al implementar una característica mediante la inteligencia artificial APIsde Windows, la aplicación debe comprobar primero la disponibilidad del modelo de IA que admite esa característica.

En el fragmento de código siguiente se muestra cómo comprobar la disponibilidad del modelo y generar una respuesta.

  1. En MainWindow.xaml, agregue un TextBlock para mostrar la respuesta languageModel .

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

  2. En la parte superior de MainWindow.xaml.cs, agregue la siguiente using Microsoft.Windows.AI directiva.

    using Microsoft.Windows.AI;

  3. En MainWindow.xaml.cs, reemplace la clase MainWindow por el código siguiente, que confirma que LanguageModel está disponible y, a continuación, envía un mensaje que solicita al modelo que responda con la fórmula molecular de glucosa.

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

  4. Compile y ejecute la aplicación.

  5. La fórmula de glucosa debe aparecer en el bloque de texto.

Tutoriales avanzados y APIs

Ahora que ha comprobado correctamente la disponibilidad del modelo, examine mejor las APIs en los distintos tutoriales de API de la IA de Windows.

Solución de problemas

Si se producen errores, suele deberse a su hardware o a la ausencia de un modelo necesario.

  • El método GetReadyState comprueba si el modelo requerido por una característica de IA está disponible en el dispositivo del usuario. Debe llamar a este método antes de cualquier llamada al modelo.
  • Si el modelo no está disponible en el dispositivo del usuario, puede llamar al método EnsureReadyAsync para instalar el modelo necesario. La instalación del modelo se ejecuta en segundo plano y el usuario puede comprobar el progreso de la instalación en la página Configuración de Windows>.
  • El método EnsureReadyAsync tiene una opción de estado que puede mostrar una interfaz de usuario de carga. Si el usuario tiene hardware no compatible, entonces EnsureReadyAsync fallará con un error.

Detección de compatibilidad de hardware en tiempo de ejecución

Windows AI APIs se suministran en una amplia gama de hardware (NPU, GPU, CPU) y no todos los API se admiten en todos los dispositivos. La aplicación debe basarse en el resultado de GetReadyState antes de realizar cualquier acción, incluida la presentación de una interfaz de usuario que dependa de la función:

AIFeatureReadyState Qué significa Qué debe hacer la aplicación
Ready El modelo está instalado y el dispositivo es compatible con API. Llame al API.
NotReady o EnsureNeeded El dispositivo admite API, pero el modelo debe descargarse o prepararse. Mostrar un cuadro de diálogo de consentimiento que explique la descarga (tamaño, uso de red) y llame a EnsureReadyAsync e informe del progreso al usuario.
NotSupportedOnCurrentSystem El dispositivo no puede ejecutarlo API (hardware incompatible, controladores que faltan o directivas). No llame a EnsureReadyAsync. Oculte o deshabilite la característica o revierte a una implementación alternativa (por ejemplo, un servicio de inteligencia artificial en la nube).

Para obtener un ejemplo completo que abarque las tres ramas (incluida la experiencia de usuario del cuadro de diálogo de consentimiento), consulte PhiLice → patrón de experiencia de usuario recomendado. El mismo patrón se aplica a cada Windows AI API que expone GetReadyState.

Nota:

Para APIs con especificaciones de CPU recomendadas (como VSR), GetReadyState por sí solo no es suficiente. GetReadyState solo indica si API se admite; la comprobación de especificaciones de CPU indica si se ejecutará lo suficiente para la experiencia de usuario. Usa ambas opciones: disponibilidad de gate con GetReadyState, opciones de calidad de gate con la comprobación de la CPU.

Consulte Solución de problemas y preguntas más frecuentes sobre la inteligencia artificial API de Windows para obtener más ayuda.

Consulte también

  • Last updated on