Phi Silica Addon 만들기

이 가이드에서는 Electron 앱에서 Phi Silica AI API를 호출하는 C# 네이티브 추가 기능을 만드는 방법을 보여 줍니다. Phi Silica는 NPU(신경 처리 장치)를 사용하는 Windows 11 디바이스에서 로컬로 실행되는 작은 언어 모델입니다.

필수 조건

이 가이드를 시작하기 전에 다음을 수행했는지 확인합니다.

• 개발 환경 설정 완료
• Copilot+ PC - Phi Silica에는 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에 대한 참조가 있는 프로젝트 파일
• README.md - 추가 기능을 사용하는 방법에 대한 설명서

또한 이 명령어는 애드온을 빌드하기 위한 build-csAddon 스크립트를 추가하고, 빌드 아티팩트를 정리하기 위한 clean-csAddon 스크립트를 package.json에 추가합니다.

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

2단계: Phi Silica를 사용하여 AI 기능 추가

실제 Windows 앱 SDK API를 추가해 보겠습니다. Phi Silica 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}";
            }
        }
    }
}

3단계: C# 추가 기능 빌드

이제 추가 기능을 다시 빌드합니다.

npm run build-csAddon

네이티브 AOT (Ahead-of-Time 컴파일)을 사용하여 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 Silica API를 사용하려면 앱 매니페스트에서 필요한 기능을 선언해야 합니다. Package.appxmanifest을 열고 <Capabilities> 섹션 안에 systemAIModels 기능을 추가합니다.

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

6단계: 디버그 ID 업데이트

매니페스트에서 참조되는 자산(예: 앱 아이콘)을 수정 Package.appxmanifest 하거나 변경할 때마다 앱의 디버그 ID를 업데이트해야 합니다. Run:

npx winapp node add-electron-debug-identity

이 명령은 다음과 같습니다.

1. Package.appxmanifest 앱 세부 정보 및 기능을 가져오기 위해 읽습니다.
2. electron.exe를 임시 ID를 사용하여 node_modules에 등록합니다.
3. 전체 MSIX 패키징 없이 ID 필수 API를 테스트할 수 있습니다.

이제 앱을 실행합니다.

npm start

콘솔 출력을 확인합니다. Phi Silica 요약이 인쇄되어 표시됩니다.

다음 단계

축하합니다! Windows AI API를 호출하는 네이티브 추가 기능을 성공적으로 만들었습니다. 🎉

이제 다음을 수행할 준비가 되었습니다.

• 배포용 앱 패키지 - 배포할 수 있는 MSIX 패키지 만들기

또는 다른 가이드를 살펴보세요.

• WinML 추가 기능 만들기 - Windows Machine Learning 사용하는 방법을 알아봅니다.
• 시작 개요 - 기본 가이드로 돌아가기

추가 리소스

• winapp CLI 설명서 - 전체 CLI 참조
• 샘플 Electron 앱 - 완전한 동작 예제
• Windows Electron용 AI 추가 기능 - Windows AI Addon for Electron은 JavaScript에서 직접 Windows AI API 대한 액세스를 제공하는 Node.js 네이티브 추가 기능입니다.
• AI 개발자 갤러리 - 모든 AI API의 샘플 갤러리
• Windows 앱 SDK 샘플 - Windows 앱 SDK 샘플 컬렉션
• node-api-dotnet - C# ↔ JavaScript interop 라이브러리