Criação de um Addon Phi Silica

Este guia mostra-te como criar um addon nativo de C# que chama a API de IA da Phi Silica na tua aplicação Electron. Phi Silica é um pequeno modelo de linguagem que corre localmente em dispositivos Windows 11 com NPUs (Unidades de Processamento Neural).

Pré-requisitos

Antes de começar este guia, certifique-se de que:

• Concluí a configuração do ambiente de desenvolvimento
• Copilot+ PC - Phi Silica requer um dispositivo com uma NPU (Unidade de Processamento Neural)

Passo 1: Criar um addon nativo de C#

Agora vem a parte entusiasmante – vamos criar um addon nativo que chama APIs do Windows! Vamos usar um template em C# que aproveita node-api-dotnet para fazer a ponte entre JavaScript e C#.

npx winapp node create-addon --template cs

Isto cria uma csAddon/ pasta com:

• addon.cs - O seu código C# que irá chamar APIs do Windows
• csAddon.csproj - ficheiro Project com referências ao Windows SDK e SDK de Aplicações Windows
• README.md - Documentação sobre como usar o addon

O comando também adiciona um build-csAddon script ao teu package.json para construir o addon e um clean-csAddon script para limpar artefactos de build:

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

O modelo inclui automaticamente referências a ambos os SDKs, para que possa começar imediatamente a chamar APIs do Windows!

Vamos verificar se tudo está configurado corretamente ao construir o adddon:

# Build the C# addon
npm run build-csAddon

Passo 2: Adicionar Capacidades de IA com a Phi Silica

Vamos adicionar uma API SDK de Aplicações Windows real – vamos usar o modelo de IA Phi Silica para resumir o texto diretamente no dispositivo.

Abra csAddon/addon.cs e adicione 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}";
            }
        }
    }
}

Passo 3: Constrói o addon C#

Agora constrói novamente o addon:

npm run build-csAddon

Isto compila o código C# usando Native AOT (compilação antecipada), que:

• Cria um .node binário (formato nativo de addon)
• Remove o código não utilizado para um tamanho de pacote menor
• Não requer tempo de execução do .NET nas máquinas alvo
• Proporciona desempenho nativo

O addon compilado estará em csAddon/dist/csAddon.node.

Passo 4: Teste a API do Windows

Agora vamos verificar se o addon funciona chamando-o a partir do processo principal. Abra src/main.js e siga estes passos:

4.1. Carregar o complemento C#

Adicione isto com as suas outras require declarações no topo do ficheiro:

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

4.2. Criar uma Função de Teste

Adicione esta função em algum lugar do seu ficheiro (depois das instruções 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. Chamar a Função

Adicione esta linha no final da createWindow()função para testar a API quando iniciar a aplicação:

callPhiSilica();

Quando abrir a aplicação, o resumo será impresso na consola. A partir daqui, podes integrar o addon na tua aplicação como quiseres – seja expondo-o através de um script de pré-carregamento ao processo de renderizador, chamá-lo a partir de handlers IPC ou usá-lo diretamente no processo principal.

Passo 5: Adicionar a Capacidade Necessária

Antes de poderes usar a API da Phi Silica, precisas de declarar a funcionalidade necessária no manifesto da tua app. Abra Package.appxmanifest e adicione a systemAIModels funcionalidade dentro da <Capabilities> secção:

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

Passo 6: Atualizar a Identidade de Depuração

Sempre que modificas Package.appxmanifest ou alteras assets referenciados no manifesto (como ícones da app), precisas de atualizar a identidade de depuração da tua app. Corrida:

npx winapp node add-electron-debug-identity

Este comando:

1. Lê o seu Package.appxmanifest para obter detalhes e funcionalidades da aplicação.
2. Regista electron.exe no seu node_modules com uma identidade temporária
3. Permite testar APIs que exigem identidade sem empacotamento MSIX completo

Agora executa a tua aplicação:

npm start

Verifica a saída da consola – deves ver o resumo da Phi Silica impresso!

Próximas Etapas

Parabéns! Criaste com sucesso um addon nativo que chama APIs de IA do Windows! 🎉

Agora está pronto para:

• Embale a sua aplicação para distribuição - Crie um pacote MSIX que possa distribuir

Ou explore outros guias:

• Criação de um Addon WinML - Aprenda a usar Windows Machine Learning
• Visão Geral do Início - Voltar ao guia principal

Recursos adicionais

• Documentação da CLI winapp - Referência completa da CLI
• Exemplo de Aplicação Electron - Exemplo completo de funcionamento
• Windows AI Addon para Electron - O Windows AI Addon para Electron é um addon nativo Node.js que fornece acesso às APIs Windows AI diretamente a partir de JavaScript.
• Galeria de Desenvolvimento de IA - Galeria de exemplos de todas as APIs de IA
• SDK de Aplicações Windows Amostras - Recolha de SDK de Aplicações Windows amostras
• node-api-dotnet - Biblioteca interop JavaScript em C# ↔