创建 Phi 硅插件

本指南介绍如何创建一个 C# 本机加载项，用于在 Electron 应用中调用 Phi 硅 AI API。 Phi Silica 是一种小型语言模型，可以在具有 NPU（神经处理单元）的 Windows 11 设备上本地运行。

先决条件

在开始本指南之前，请确保已：

  • 已完成 开发环境设置
  • AI+ PC - Phi 硅需要具有 NPU（神经处理单元）的设备

注释

如果你不在AI+ PC，仍可以按照本指南了解加载项创建过程。 代码将通过返回指示模型不可用的消息来正常处理没有 NPU 支持的设备。

步骤 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 的 Project 文件
  • README.md - 有关如何使用加载项的文档

该命令还会在build-csAddon中添加一个package.json脚本用于创建加载项，以及一个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 的设备，并运行 Windows 11（AI+ PC）。 如果没有兼容的硬件，API 将返回一条消息，指示模型不可用。 你仍然可以完成本教程并打包应用 - 它将正常处理没有 NPU 支持的设备。

步骤 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 is a powerful tool that bridges cross-platform development with Windows-native capabilities.");
  console.log('Summary:', result);
};

4.3。 调用函数

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

callPhiSilica();

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

步骤 5：添加必需功能

在使用 Phi 硅 API 之前，需要在应用清单中声明所需的功能。 打开Package.appxmanifest并在systemAIModels节中添加<Capabilities>功能：

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

Tip

不同的Windows API 需要不同的功能。 请始终检查 API 文档，了解所需的功能。 常见项包括microphone、webcam和locationbluetooth。

步骤 6：更新调试标识

每当修改 Package.appxmanifest 或更改清单中引用的资产（如应用图标），都需要更新应用的调试标识。 运行：

npx winapp node add-electron-debug-identity

此命令：

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

注释

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

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

现在运行应用：

npm start

检查控制台输出 - 应看到显示的 Phi 硅石摘要！

⚠️ 已知问题：应用崩溃或空白窗口（单击以展开）

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

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

后续步骤

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

现在，你已准备好：

或者浏览其他指南：

其他资源

  • Last updated on