Création d’un module complémentaire Phi Silice

Ce guide vous montre comment créer un module complémentaire natif C# qui appelle l’API IA Phi Silicon dans votre application Electron. Phi Silica est un petit modèle de langage qui s’exécute localement sur des appareils Windows 11 pris en charge.

Prerequisites

Avant de commencer ce guide, vérifiez que vous avez :

Note

Si vous n’êtes pas sur le matériel Phi Silica pris en charge, vous pouvez toujours suivre ce guide pour découvrir le processus de création du module complémentaire. Le code gère correctement les appareils non pris en charge en retournant un message indiquant que le modèle n’est pas disponible.

Étape 1 : Créer un complément natif C#

Maintenant pour la partie excitante , nous allons créer un module complémentaire natif qui appelle Windows API ! Nous allons utiliser un modèle C# qui tire parti de node-api-dotnet pour ponter JavaScript et C#.

npx winapp node create-addon --template cs

Cela crée un csAddon/ dossier avec :

  • addon.cs - Votre code C# qui appelle les API Windows
  • csAddon.csproj - fichier Project avec des références au Kit de développement logiciel (SDK) Windows et SDK d'application Windows
  • README.md - Documentation sur l’utilisation du module complémentaire

La commande ajoute également un build-csAddon script à votre package.json pour générer le module complémentaire et un clean-csAddon script pour le nettoyage des artefacts de build :

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

Le modèle inclut automatiquement des références aux deux kits SDK, ce qui vous permet de commencer immédiatement à appeler Windows API !

Vérifions que tout est configuré correctement en créant le module complémentaire :

# Build the C# addon
npm run build-csAddon

Note

Vous pouvez également créer un module complémentaire C++ à l’aide npx winapp node create-addon (sans l’indicateur --template ). Les compléments C++ utilisent node-addon-api et fournissent un accès direct aux API Windows avec des performances maximales. Pour plus d’options, consultez le guide du module complémentaire de notification C++ pour obtenir une procédure pas à pas ou la documentation complète de la commande .

Étape 2 : Ajouter des fonctionnalités d’IA avec Phi Silicon

Ajoutons une API SDK d'application Windows réelle . Nous allons utiliser le modèle IA Phi Silicon pour synthétiser du texte directement sur appareil.

Ouvrez csAddon/addon.cs et ajoutez ce code :

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

Note

Phi Silica nécessite un matériel Windows 11 pris en charge. Si vous n’avez pas de matériel compatible, l’API retourne un message indiquant que le modèle n’est pas disponible. Vous pouvez toujours suivre ce didacticiel et crée un package de l’application ; elle prendra correctement en charge les appareils non pris en charge.

Étape 3 : Générer le module complémentaire C#

Maintenant, générez à nouveau le module complémentaire :

npm run build-csAddon

Cela compile votre code C# à l’aide d’AOT natif (compilation anticipée), qui :

  • Crée un .node fichier binaire (format de complément natif)
  • Supprime le code inutilisé pour une taille d’offre groupée plus petite
  • Ne nécessite aucun runtime .NET sur les machines cibles
  • Fournit la performance native

Le module complémentaire compilé sera dans csAddon/dist/csAddon.node.

Étape 4 : Tester l’API Windows

Maintenant, vérifions que le module complémentaire fonctionne en l’appelant à partir du processus principal. Ouvrez src/main.js et procédez comme suit :

4.1. Charger le module complémentaire C#

Ajoutez-le avec vos autres require instructions en haut du fichier :

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

4.2. Créer une fonction de test

Ajoutez cette fonction quelque part dans votre fichier (après les instructions require) :

const callPhiSilica = async () => {
  console.log('Summarizing with Phi Silica: ')
  const result = await csAddon.Addon.summarizeText("The Windows App Development CLI lets Electron apps call Windows-native APIs from JavaScript. Package identity enables features such as notifications and background tasks.");
  console.log('Summary:', result);
};

4.3. Appeler la fonction

Ajoutez cette ligne à la fin de la createWindow() fonction pour tester l’API au démarrage de l’application :

callPhiSilica();

Lorsque vous exécutez l’application, le résumé est imprimé dans la console. À partir de là, vous pouvez intégrer le module complémentaire dans votre application comme vous le souhaitez, qu’il s’agisse de l’exposer via un script de préchargement au processus de rendu, de l’appeler depuis les gestionnaires IPC, ou de l’utiliser directement dans le processus principal.

Étape 5 : Ajouter une fonctionnalité requise

Avant de pouvoir utiliser l’API Phi Silicon, vous devez déclarer la systemAIModels fonctionnalité dans votre manifeste d’application. Il se trouve dans son propresystemai espace de noms — et non dans rescap —, alors ouvrez Package.appxmanifest, déclarez cet espace de noms sur <Package> et marquez-le comme ignorable, puis ajoutez la capacité :

<Package
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
  IgnorableNamespaces="rescap systemai">
  ...
  <Capabilities>
    <rescap:Capability Name="runFullTrust" />
    <systemai:Capability Name="systemAIModels" />
  </Capabilities>
</Package>

Il faut également que TargetDeviceFamily/@MaxVersionTested soit au moins 10.0.26226.0.

Tip

Différentes API Windows nécessitent des fonctionnalités différentes, et elles ne vivent pas toutes dans le même espace de noms. Vérifiez toujours la documentation de l’API pour le nom de la fonctionnalité et l’élément auquel il appartient. Les éléments courants incluent microphone, webcam, location, et bluetooth.

Étape 6 : Mettre à jour l’identité de débogage

Chaque fois que vous modifiez Package.appxmanifest ou modifiez des ressources référencées dans le manifeste (comme les icônes d’application), vous devez mettre à jour l’identité de débogage de votre application. Run:

npx winapp node add-electron-debug-identity

Cette commande :

  1. Lit Package.appxmanifest afin d'obtenir les détails et les fonctionnalités de l'application
  2. Enregistre electron.exe dans votre node_modules avec une identité temporaire
  3. Vous permet de tester les API nécessitant une identité sans la nécessité d'un empaquetage MSIX complet

Note

Cette commande fait déjà partie du postinstall script que nous avons ajouté dans le guide d’installation. Elle s’exécute donc automatiquement après npm install. Toutefois, vous devez l’exécuter manuellement chaque fois que vous :

  • Modifier Package.appxmanifest (modifier les fonctionnalités, l’identité ou les propriétés)
  • Mettre à jour les ressources de l’application (icônes, logos, etc.)
  • Réinstaller ou mettre à jour des dépendances

Exécutez maintenant votre application :

npm start

Vérifiez la sortie de la console : vous devriez voir le résumé de Phi Silica imprimé !

⚠️ Problème connu : Blocage de l’application ou fenêtre vide (cliquez pour développer)

Il existe un bogue Windows connu avec l'empaquetage sparse des applications Electron, qui provoque le plantage de l'application au démarrage ou empêche l'affichage du contenu Web. Le problème a été résolu dans Windows mais n’a pas encore été propagé à tous les appareils.

Consultez la configuration de l’environnement de développement pour la solution de contournement.

Prochaines étapes

Félicitations! Vous avez créé avec succès un module complémentaire natif faisant appel aux API d'IA de Windows ! 🎉

Vous êtes maintenant prêt à :

Ou explorez d’autres guides :

Ressources additionnelles

  • Dernière mise à jour :