Creación de un complemento de Sílice phi

En esta guía se muestra cómo crear un addon nativo de C# que llama a la API de Phi Silica AI en tu aplicación Electron. PhiLice es un modelo de lenguaje pequeño que se ejecuta localmente en dispositivos Windows 11 con NPUs (unidades de procesamiento neuronal).

Prerrequisitos

Antes de iniciar esta guía, asegúrese de que tiene:

Nota:

Si no está en una Copilot+ PC, puede seguir esta guía para obtener información sobre el proceso de creación del complemento. El código controlará correctamente los dispositivos sin compatibilidad con NPU devolviendo un mensaje que indica que el modelo no está disponible.

Paso 1: Crear un complemento nativo de C#

Ahora, para la parte emocionante, vamos a crear un complemento nativo que llame a Windows API. Usaremos una plantilla de C# que aproveche node-api-dotnet para puentear JavaScript y C#.

npx winapp node create-addon --template cs

Esto crea una csAddon/ carpeta con:

  • addon.cs - El código de C# que llamará a las API de Windows
  • csAddon.csproj - Archivo de proyecto con referencias a Windows SDK y SDK de Aplicaciones para Windows
  • README.md - Documentación sobre cómo usar el complemento

El comando también agrega un build-csAddon script a package.json para compilar el complemento y un clean-csAddon script para limpiar los artefactos de compilación:

{
  "scripts": {
    "build-csAddon": "dotnet publish ./csAddon/csAddon.csproj -c Release",
    "clean-csAddon": "dotnet clean ./csAddon/csAddon.csproj"
  }
}

La plantilla incluye automáticamente referencias a ambos SDK, por lo que puede empezar a llamar inmediatamente a Windows API.

Vamos a comprobar que todo está configurado correctamente mediante la compilación del complemento:

# Build the C# addon
npm run build-csAddon

Nota:

También puede crear un complemento de C++ mediante npx winapp node create-addon (sin la --template marca). Los complementos de C++ usan node-addon-api y proporcionan acceso directo a las API de Windows con un rendimiento máximo. Consulte la guía del complemento de notificaciones de C++ para ver un tutorial o la documentación completa del comando para obtener más opciones.

Paso 2: Incorporación de funcionalidades de inteligencia artificial con PhiLice

Vamos a añadir una API real de SDK de Aplicaciones para Windows: utilizaremos el modelo de IA Phi Silica para resumir texto directamente en el dispositivo.

Abra csAddon/addon.cs y agregue este código:

using System;
using System.Threading.Tasks;
using Microsoft.JavaScript.NodeApi;
using Microsoft.Windows.AI;
using Microsoft.Windows.AI.Text;

namespace csAddon
{
    [JSExport]
    public class Addon
    {
        /// <summary>
        /// Summarizes the provided text using the Phi Silica AI model.
        /// </summary>
        /// <param name="text">The text to summarize</param>
        /// <returns>A summary of the input text</returns>
        [JSExport]
        public static async Task<string> SummarizeText(string text)
        {
            try
            {
                var readyState = LanguageModel.GetReadyState();
                if (readyState is AIFeatureReadyState.Ready or AIFeatureReadyState.NotReady)
                {
                    if (readyState == AIFeatureReadyState.NotReady)
                    {
                        await LanguageModel.EnsureReadyAsync();
                    }

                    using LanguageModel languageModel = await LanguageModel.CreateAsync();
                    TextSummarizer textSummarizer = new TextSummarizer(languageModel);

                    var result = await textSummarizer.SummarizeParagraphAsync(text);

                    return result.Text;
                }

                return "Model is not available";
            }
            catch (Exception ex)
            {
                return $"Error calling Phi Silica API: {ex.Message}";
            }
        }
    }
}

Nota:

PhiLice requiere Windows 11 con un dispositivo equipado con NPU (Copilot+ PC). Si no tiene hardware compatible, la API devolverá un mensaje que indica que el modelo no está disponible. Todavía puede completar este tutorial y empaquetar la aplicación: controlará correctamente los dispositivos sin compatibilidad con NPU.

Paso 3: Compilar el complemento de C#

Ahora vuelva a compilar el complemento:

npm run build-csAddon

Esto compila el código de C# mediante Native AOT (compilación adelantada), que:

  • Crea un .node binario (formato de complemento nativo)
  • Recorta el código sin usar para un tamaño de agrupación más pequeño
  • Requiere no .NET runtime en máquinas de destino
  • Proporciona rendimiento nativo

El complemento compilado estará en csAddon/dist/csAddon.node.

Paso 4: Probar la API de Windows

Ahora vamos a comprobar que el complemento funciona llamándolo desde el proceso principal. Abra src/main.js y siga estos pasos:

4.1. Cargar el complemento de C#

Agregue esto con las demás require instrucciones en la parte superior del archivo:

const csAddon = require('../csAddon/dist/csAddon.node');

4.2. Creación de una función de prueba

Agrega esta función en algún lugar de su archivo (después de las declaraciones require):

const callPhiSilica = async () => {
  console.log('Summarizing with Phi Silica: ')
  const result = await csAddon.Addon.summarizeText("The Windows App Development CLI is a powerful tool that bridges cross-platform development with Windows-native capabilities.");
  console.log('Summary:', result);
};

4.3. Llamada a la función

Agregue esta línea al final de la createWindow() función para probar la API cuando se inicie la aplicación:

callPhiSilica();

Al ejecutar la aplicación, el resumen se imprimirá en la consola. Desde aquí, puedes integrar el complemento en tu aplicación como prefieras: ya sea exponiéndolo a través de un script de carga previa al proceso del renderizador, llamándolo desde los controladores IPC, o usándolo directamente en el proceso principal.

Paso 5: Agregar la funcionalidad necesaria

Para poder usar PhiLice API, debe declarar la funcionalidad necesaria en el manifiesto de la aplicación. Abra Package.appxmanifest y agregue la systemAIModels funcionalidad dentro de la <Capabilities> sección:

<Capabilities>
  <rescap:Capability Name="runFullTrust" />
  <rescap:Capability Name="systemAIModels" />
</Capabilities>

Tip

Las DISTINTAS API de Windows requieren funcionalidades diferentes. Compruebe siempre la documentación de la API para ver qué funcionalidades son necesarias. Entre los comunes se incluyen microphone, webcam, locationy bluetooth.

Paso 6: Actualizar la identidad de depuración

Siempre que modifique Package.appxmanifest o cambie los recursos a los que se hace referencia en el manifiesto (como los iconos de la aplicación), debe actualizar la identidad de depuración de la aplicación. ¡Corre!

npx winapp node add-electron-debug-identity

Este comando:

  1. Lee tu Package.appxmanifest para obtener detalles y capacidades de la aplicación.
  2. Registra electron.exe en su node_modules con una identidad temporal
  3. Permite probar las API que requieren identidad sin el empaquetado completo de MSIX.

Nota:

Este comando ya está incluido en el script postinstall que hemos agregado en la guía de configuración, por lo que se ejecuta automáticamente después de npm install. Sin embargo, debe ejecutarlo manualmente cada vez que:

  • Modificar Package.appxmanifest (cambiar funcionalidades, identidades o propiedades)
  • Actualizar recursos de la aplicación (iconos, logotipos, etc.)
  • Reinstalar o actualizar dependencias

Ahora ejecute la aplicación:

npm start

Compruebe la salida de la consola: debería ver el resumen de PhiLice impreso.

⚠️ Problema conocido: Bloqueos de la aplicación o ventana en blanco (haga clic para expandir)

Hay un error conocido de Windows con aplicaciones Electron de empaquetado ligero o disperso que hace que la aplicación se bloquee al iniciar o no mostrar contenido web. El problema se ha corregido en Windows pero aún no se ha propagado a todos los dispositivos.

Consulte Configuración del entorno de desarrollo para obtener una solución alternativa.

Pasos siguientes

¡Enhorabuena! ¡Ha creado con éxito un complemento nativo que llama a las API de IA de Windows! 🎉

Ahora ya está listo para:

O explore otras guías:

Recursos adicionales

  • Last updated on