创建 Phi Silica 插件

本指南介绍如何创建一个 C# 本机加载项,用于在 Electron 应用中调用 Phi 硅 AI API。 Phi Silica 是一种小型语言模型,可在受支持的 Windows 11 设备上本地运行,包括配备 NPU(神经处理单元)的 Copilot+ PC 和符合条件的 GPU 设备。

先决条件

在开始本指南之前,请确保具备:

注释

如果设备上没有 Phi Silica,仍可以按照本指南了解加载项创建过程。 代码检查模型可用性,如果模型无法运行,则返回一条消息。 如果模型受支持但尚未准备就绪,则代码将调用 EnsureReadyAsync() 下载或初始化它。

步骤 1:创建 C# 本地附加组件

现在,对于令人兴奋的部分, 让我们创建一个调用 Windows API 的本机加载项! 我们将使用利用 node-api-dotnet 桥接 JavaScript 和 C# 的 C# 模板。

npx winapp node create-addon --template cs

这将创建一个 csAddon/ 文件夹,其中包含:

  • addon.cs - 将调用 Windows API 的 C# 代码
  • csAddon.csproj - 引用 Windows SDK 和 Windows 应用 SDK 的项目文件
  • README.md - 有关如何使用加载项的文档

该命令还向你的 package.json 添加一个用于构建插件的 build-csAddon 脚本,以及一个用于清理构建工件的 clean-csAddon 脚本:

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

该模板会自动包含对两个 SDK 的引用,因此你可以立即开始调用Windows API!

让我们通过构建加载项来验证所有设置是否正确。

# Build the C# addon
npm run build-csAddon

注释

还可以使用 npx winapp node create-addon (不使用 --template 标志)创建 C++ 加载项。 C++ 加载项使用 node-addon-api并提供对具有最佳性能的 Windows API 的直接访问。 有关更多选项,请参阅 C++ 通知插件指南以获取演练或完整命令文档。

步骤 2:使用 Phi 硅添加 AI 功能

让我们添加一个真正的Windows 应用 SDK API - 我们将使用 Phi 硅 AI 模型直接在设备上汇总文本。

打开 csAddon/addon.cs 并添加以下代码:

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

注释

Phi Silica 支持搭载 NPU 的 Copilot+ PC 以及符合条件的 GPU 设备。 请查阅当前要求,以获取受支持的硬件、Windows 和 Windows 应用 SDK 版本以及 GPU 驱动程序的相关信息。 当模型无法在设备上运行时,该示例将返回“模型不可用”。

步骤 3:生成 C# 加载项

现在再次生成加载项:

npm run build-csAddon

这使用本机 AOT(提前编译)编译你的 C# 代码,它:

  • 创建 .node 二进制文件(原生附加组件格式)
  • 剪裁未使用的代码以缩小捆绑包大小
  • 目标计算机上不需要 .NET 运行时
  • 提供本地化性能

编译的加载项将位于 csAddon/dist/csAddon.node.

步骤 4:测试Windows API

现在,让我们通过从主进程调用加载项来验证加载项是否正常工作。 打开 src/main.js 并按照以下步骤操作:

4.1. 加载 C# 插件

将此项与文件顶部的其他 require 语句一起添加:

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

4.2。 创建测试函数

在文件中的某个位置添加此函数(在 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。 调用函数

在函数末尾 createWindow() 添加此行,以在应用启动时测试 API:

callPhiSilica();

运行应用时,摘要将打印到控制台。 从这里开始,你可以按照自己的意愿将插件集成到应用中——无论是通过预加载脚本将其暴露到渲染进程、从IPC处理程序调用它,还是直接在主进程中使用它。

步骤 5:添加必需功能

在使用 Phi 硅 API 之前,需要在应用清单中声明 systemAIModels 功能。 它位于 自己的systemai 命名空间中,而不是 rescap 如此打开 Package.appxmanifest,声明该命名空间 <Package> 并将其标记为可忽略,然后添加该功能:

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

它还需要 TargetDeviceFamily/@MaxVersionTested 至少为 10.0.26226.0。

Tip

不同的Windows API 需要不同的功能,它们并不全部位于同一命名空间中。 始终检查 API 文档,了解功能名称和它所属的元素。 常见项包括microphone、webcam和locationbluetooth。

步骤 6:更新调试标识

每当修改 Package.appxmanifest 或更改清单中引用的资产(如应用图标),都需要更新应用的调试标识。 运行:

npx winapp node add-electron-debug-identity

此命令:

  1. 读取您的 Package.appxmanifest 以获取应用的详细信息和功能
  2. 使用临时标识在你的 node_modules 中注册 electron.exe
  3. 让您无需完整的 MSIX 打包即可测试需要标识的 API

注释

此命令已经是我们在安装指南中添加的 postinstall 脚本的一部分,因此它在 npm install 之后自动运行。 但是,无论何时,都需要手动运行它:

  • 修改 Package.appxmanifest (更改功能、标识或属性)
  • 更新应用资产(图标、徽标等)
  • 重新安装或更新依赖项

现在运行应用:

npm start

检查控制台输出 - 你应该看到打印的 Phi Silica 摘要!

⚠️ 已知问题:应用崩溃或空白窗口(单击以展开)

稀疏打包 Electron 应用程序存在一个已知的 Windows bug,会导致应用在启动时崩溃或不呈现 Web 内容。 此问题已在Windows中修复,但尚未传播到所有设备。

有关解决方法,请参阅 开发环境设置 。

后续步骤

祝贺! 你已成功创建调用 Windows AI API 的本机加载项! 🎉

现在,你已准备好:

或者浏览其他指南:

其他资源