Skapa ett Phi Silica-tillägg

Den här guiden visar hur du skapar ett C#-inbyggt tillägg som anropar Phi Silica AI API i din Electron-app. Phi Silica är en liten språkmodell som körs lokalt på Windows 11 enheter med NPU:er (neurala bearbetningsenheter).

Förutsättningar

Kontrollera att du har gjort så här innan du startar den här guiden:

  • Installationen av utvecklingsmiljön har slutförts
  • Copilot+ PC – Phi Silica kräver en enhet med en NPU (neural bearbetningsenhet)

Anmärkning

Om du inte har en Copilot+ PC kan du fortfarande följa den här guiden för att lära dig hur du skapar tillägg. Koden hanterar enheter utan NPU-stöd genom att returnera ett meddelande som anger att modellen inte är tillgänglig.

Steg 1: Skapa ett internt C#-tillägg

Nu till den spännande delen – nu ska vi skapa ett internt tillägg som anropar Windows API:er! Vi använder en C#-mall som använder node-api-dotnet för att överbrygga JavaScript och C#.

npx winapp node create-addon --template cs

Då skapas en csAddon/ mapp med:

  • addon.cs – Din C#-kod som anropar Windows-API:er
  • csAddon.csproj – Project fil med referenser till Windows SDK och Windows App SDK
  • README.md – Dokumentation om hur du använder tillägget

Kommandot lägger också till ett build-csAddon skript i din package.json för byggande av tillägget och ett clean-csAddon skript för rensning av byggartefakter.

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

Mallen innehåller automatiskt referenser till båda SDK:erna, så att du omedelbart kan börja anropa Windows API:er!

Nu ska vi kontrollera att allt har konfigurerats korrekt genom att skapa tillägget:

# Build the C# addon
npm run build-csAddon

Anmärkning

Du kan också skapa ett C++-tillägg med ( npx winapp node create-addon utan --template flaggan). C++-tillägg använder node-addon-api och ger direkt åtkomst till Windows API:er med maximal prestanda. Se guiden C++-meddelandetillägg för en genomgång eller den fullständiga kommandodokumentationen för fler alternativ.

Steg 2: Lägga till AI-funktioner med Phi Silica

Nu ska vi lägga till ett verkligt Windows App SDK API – vi använder ai-modellen Phi Silica för att sammanfatta text direkt på enheten.

Öppna csAddon/addon.cs och lägg till den här koden:

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

Anmärkning

Phi Silica kräver Windows 11 med en NPU-utrustad enhet (Copilot+ PC). Om du inte har kompatibel maskinvara returnerar API:et ett meddelande som anger att modellen inte är tillgänglig. Du kan fortfarande slutföra den här självstudien och paketera appen – den hanterar enheter utan NPU-stöd på ett smidigt sätt.

Steg 3: Skapa C#-tillägget

Skapa nu tillägget igen:

npm run build-csAddon

Detta kompilerar din C#-kod med Native AOT (förkompilering), som:

  • Skapar en .node binär fil (internt tilläggsformat)
  • Minskar oanvänd kod för mindre paket.
  • Kräver no .NET runtime på måldatorer
  • Ger inbyggda prestanda

Det kompilerade tillägget finns i csAddon/dist/csAddon.node.

Steg 4: Testa Windows-API:et

Nu ska vi kontrollera att tillägget fungerar genom att anropa det från huvudprocessen. Öppna src/main.js och följ dessa steg:

4.1. Läs in C#-tillägget

Lägg till detta med dina andra require instruktioner överst i filen:

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

4.2. Skapa en testfunktion

Lägg till den här funktionen någonstans i filen (efter kräv-instruktionerna):

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. Anropa funktionen

Lägg till den här raden i slutet av createWindow() funktionen för att testa API:et när appen startar:

callPhiSilica();

När du kör appen skrivs sammanfattningen ut till konsolen. Härifrån kan du integrera tillägget i din app på det sätt du önskar - genom att exponera det via ett förinläsningsskript till återgivningsprocessen, anropa det via IPC-hanterare, eller använda det direkt i huvudprocessen.

Steg 5: Lägg till nödvändig kapacitet

Innan du kan använda Phi Silica-API:et måste du deklarera den kapacitet som krävs i appmanifestet. Öppna Package.appxmanifest och lägg till systemAIModels funktionen i avsnittet <Capabilities> :

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

Tips/Råd

Olika Windows API:er kräver olika funktioner. Kontrollera alltid API-dokumentationen för att se vilka funktioner som behövs. Vanliga är microphone, webcam, locationoch bluetooth.

Steg 6: Uppdatera felsökningsidentitet

När du ändrar Package.appxmanifest eller ändrar tillgångar som refereras till i manifestet (till exempel appikoner) måste du uppdatera appens felsökningsidentitet. Run:

npx winapp node add-electron-debug-identity

Det här kommandot:

  1. Läser din Package.appxmanifest för att hämta appinformation och funktioner
  2. electron.exe Registrerar sig i din node_modules med en tillfällig identitet
  3. Gör att du kan testa api:er som krävs för identitet utan fullständig MSIX-paketering

Anmärkning

Det här kommandot är redan en del av skriptet postinstall som vi lade till i installationsguiden, så det körs automatiskt efter npm install. Du måste dock köra den manuellt när du:

  • Ändra Package.appxmanifest (ändra funktioner, identitet eller egenskaper)
  • Uppdatera apptillgångar (ikoner, logotyper osv.)
  • Installera om eller uppdatera beroenden

Kör nu appen:

npm start

Kontrollera konsolens utdata – du bör se Phi Silica-sammanfattningen utskriven!

⚠️ Känt problem: App kraschar eller tomt fönster (klicka för att expandera)

Det finns en känd Windows bugg med gles paketering av Elektronprogram som gör att appen kraschar vid start eller inte renderar webbinnehåll. Problemet har åtgärdats i Windows men har ännu inte spridits till alla enheter.

Se konfigurationen av utvecklingsmiljön för en lösning.

Nästa steg

Grattis! Du har skapat ett internt tillägg som anropar Windows AI-API:er! 🎉

Nu är du redo att:

Eller utforska andra guider:

Ytterligare resurser

  • Last updated on