Windows AI를 사용하여 앱 빌드 시작 APIs

1. 디바이스가 사용하려는 Windows AI APIs 하드웨어 요구 사항을 충족하는지 확인합니다. 대부분의 APIs NPU를 사용하는 Copilot+ PC 필요합니다(Copilot+ PCs 개발자 가이드에 나열된 디바이스를 권장합니다). 일부 APIs 비 Copilot+ 디바이스에서 GPU 또는 CPU 실행을 지원합니다. 자세한 내용은 지원 하드웨어 테이블 참조하세요.

2. Windows 터미널에서 다음 명령을 실행합니다.

   winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/learn_wcr.winget
   

   다음 작업을 수행하는 WinGet 구성 파일을 실행합니다.

   • 최소 OS 버전을 확인합니다.
   • 개발자 모드를 사용하도록 설정합니다.
   • WinUI 및 기타 필수 워크로드를 사용하여 Visual Studio Community Edition을 설치합니다.
   • Windows 앱 SDK를 설치합니다.

• 디바이스가 사용하려는 Windows AI APIs 하드웨어 요구 사항을 충족하는지 확인합니다. 대부분의 APIs NPU를 사용하는 Copilot+ PC 필요합니다(Copilot+ PCs 개발자 가이드에 나열된 디바이스를 권장합니다). 일부는 APIs GPU 또는 CPU 실행을 지원합니다. 자세한 내용은 지원되는 하드웨어 테이블을 참조하세요.
• Windows 11 Insider Preview 빌드 26120.3073(개발 및 베타 채널) 이상을 설치합니다(OS 버전을 확인하려면 Windows Search에서 실행winver).
  • GPU용 Phi Silica: Windows 참가자 프로그램 실험 채널 빌드 26300.8553 이상을 사용하세요.
• 개발자용 설정>시스템에서> 개발자모드> 사용하도록 설정합니다. GPU에서 Phi Silica를 사용하려면 이것은 필수입니다.
• WinUI 및 Windows 앱 SDK를 사용하여 개발하기 위한 특정 워크로드 및 구성 요소와 함께 Visual Studio 를 설치합니다. 자세한 내용은 필수 워크로드 및 구성 요소를 참조하세요.
• GPU의 Phi Silica에는 Windows 앱 SDK 버전 2.2.2-experimental9(2026년 6월 실험적) 이상을 사용합니다.

1. Visual Studio에서 빈 앱, 패키지 (WinUI 3 - 데스크톱용) 템플릿을 선택하여 새 WinUI 프로젝트를 만듭니다.

   

2. 솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 속성>애플리케이션>일반을 선택하고 대상 프레임워크가 .NET 8.0으로 설정되어 있고 대상 OS가 10.0.22621 이상으로 설정되어 있는지 확인합니다.

   

3. Package.appxmanifest 파일을 편집하고(마우스 오른쪽 단추를 클릭하고 코드 보기 선택) 다음 코드 조각을 추가합니다.

   • systemAIModels 노드에 대한 <Capabilities> 기능:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • 노드에서 systemai 네임스페이스 지정자는 <Package>의 "IgnorableNamespaces"입니다.

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • 노드 요소 TargetDeviceFamily 에서 <Dependencies> 테스트된 최대 버전은 10.0.26226.0 이상이어야 합니다.

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

4. .waproj, .csproj 또는 .vcxproj 파일에 다음을 추가합니다. 이 단계는 Visual Studio가 테스트된 최대 버전을 재정의하지 않도록 하는 데 필요합니다.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리를 선택합니다.

6. NuGet 패키지 관리자에서 시험판 포함 확인란을 선택하고 Windows 앱 SDK 버전 1.8.250410001-experimental1을 선택합니다. 설치 또는 업데이트를 클릭합니다.

   

7. 빌드 구성이 디바이스에 적합한 아키텍처(예: ARM64 또는 x64)로 설정되어 있는지 확인합니다.

   

8. 앱을 빌드하고 실행합니다.

9. 앱이 성공적으로 시작되면 첫 번째 AIAPI를 계속 추가합니다. 그렇지 않으면 문제 해결을 참조하세요.

1. Visual Studio에서 WPF 애플리케이션 템플릿을 선택하여 새 WPF 프로젝트를 만듭니다.

2. 솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 프로젝트 파일 편집을 선택하여 XML로 엽니다. 내부의 <PropertyGroup> 모든 항목을 다음으로 바꿉다.

   <OutputType>WinExe</OutputType>
   <TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
   <Nullable>enable</Nullable>
   <UseWPF>true</UseWPF>
   <ImplicitUsings>enable</ImplicitUsings>
   <WindowsPackageType>None</WindowsPackageType>
   

3. Package.appxmanifest 파일을 편집하고(마우스 오른쪽 단추를 클릭하고 코드 보기 선택) 다음 코드 조각을 추가합니다.

   • systemAIModels 노드에 대한 <Capabilities> 기능:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • 노드에서 systemai 네임스페이스 지정자는 <Package>의 "IgnorableNamespaces"입니다.

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • 노드 요소 TargetDeviceFamily 에서 <Dependencies> 테스트된 최대 버전은 10.0.26226.0 이상이어야 합니다.

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

4. .waproj, .csproj 또는 .vcxproj 파일에 다음을 추가합니다. 이 단계는 Visual Studio가 테스트된 최대 버전을 재정의하지 않도록 하는 데 필요합니다.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. 솔루션 탐색기에서 종속성 노드를 마우스 오른쪽 단추로 클릭하고 Nuget 패키지 관리를 선택합니다.

6. NuGet 패키지 관리자에서 시험판 포함 확인란을 선택하고 Windows 앱 SDK 버전 1.8.250410001-experimental1을 선택합니다. 설치 또는 업데이트를 클릭합니다.

7. 앱을 빌드하고 실행합니다.

8. 앱이 성공적으로 시작되면 첫 번째 AIAPI를 계속 추가합니다. 그렇지 않으면 문제 해결을 참조하세요.

자세한 내용은 Windows 앱 SDK 지원을 위한 WPF 프로젝트 구성을 참조하세요.

1. Visual Studio에서 Windows Forms 앱 템플릿을 선택하여 새 WinForms 프로젝트를 만듭니다.

2. 솔루션 탐색기에서 프로젝트 노드 >프로젝트 파일 편집을 마우스 오른쪽 단추로 클릭하여 XML로 엽니다. 내부의 <PropertyGroup> 모든 항목을 다음으로 바꿉다.

   <OutputType>WinExe</OutputType>
   <TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
   <Nullable>enable</Nullable>
   <UseWindowsForms>true</UseWindowsForms>
   <ImplicitUsings>enable</ImplicitUsings>
   <WindowsPackageType>None</WindowsPackageType>
   

3. Package.appxmanifest 파일을 편집하고(마우스 오른쪽 단추를 클릭하고 코드 보기 선택) 다음 코드 조각을 추가합니다.

   • systemAIModels 노드에 대한 <Capabilities> 기능:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • 노드에서 systemai 네임스페이스 지정자는 <Package>의 "IgnorableNamespaces"입니다.

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • 노드 요소 TargetDeviceFamily 에서 <Dependencies> 테스트된 최대 버전은 10.0.26226.0 이상이어야 합니다.

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

4. .waproj, .csproj 또는 .vcxproj 파일에 다음을 추가합니다. 이 단계는 Visual Studio가 테스트된 최대 버전을 재정의하지 않도록 하는 데 필요합니다.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. 솔루션 탐색기에서 종속성 노드 >Nuget 패키지 관리...를 마우스 오른쪽 단추로 클릭합니다.

6. NuGet 패키지 관리자>찾아보기에서 시험판 포함을 선택하고 Windows 앱 SDK 버전 1.8.250410001-experimental1을 선택합니다. 설치 또는 업데이트를 클릭합니다.

7. 앱을 빌드하고 실행합니다.

8. 앱이 성공적으로 시작되면 첫 번째 AIAPI를 계속 추가합니다. 그렇지 않으면 문제 해결을 참조하세요.

자세한 내용은 Windows 앱 SDK 지원에 대한 WinForms 프로젝트 구성을 참조하세요.

1. 첫 번째 .NET MAUI 앱 빌드의 지침에 따라 MAUI 프로젝트를 만듭니다.

2. 솔루션 탐색기에서 프로젝트 노드 >프로젝트 파일 편집을 마우스 오른쪽 단추로 클릭하여 XML로 엽니다.

3. 프로젝트 파일의 맨 아래에 다음 줄을 추가하여 올바른 Microsoft.WindowsAppSDK 패키지 버전을 참조합니다(Windows 플랫폼용으로 컴파일할 때).

   <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
      <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.250410001-experimental1"/> 
   </ItemGroup>
   

   비고

   프로젝트 노드를 클릭하고 필요한 패키지를 추가하려면 NuGet 패키지 관리 옵션을 선택할 수 있지만, 앱이 Android 및 iOS와 같은 다른 플랫폼용으로 빌드하는 경우에도 Windows 전용 빌드에 대한 패키지 참조를 조건부로 지정하도록 프로젝트 파일을 편집해야 합니다.

4. .waproj, .csproj 또는 .vcxproj 파일에 다음을 추가합니다. 이 단계는 Visual Studio가 테스트된 최대 버전을 재정의하지 않도록 하는 데 필요합니다.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. 솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 속성을 선택한 다음 대상 Windows Framework가 10.0.22621 이상으로 설정되어 있는지 확인합니다.

6. Package.appxmanifest 파일을 편집하고(마우스 오른쪽 단추를 클릭하고 코드 보기 선택) 다음 코드 조각을 추가합니다.

   • systemAIModels 노드에 대한 <Capabilities> 기능:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • 노드에서 systemai 네임스페이스 지정자는 <Package>의 "IgnorableNamespaces"입니다.

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • 노드 요소 TargetDeviceFamily 에서 <Dependencies> 테스트된 최대 버전은 10.0.26226.0 이상이어야 합니다.

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

7. 앱을 빌드하고 실행합니다.

8. 앱이 성공적으로 시작되면 첫 번째 AIAPI를 계속 추가합니다. 그렇지 않으면 문제 해결을 참조하세요.

1. MainWindow.xaml에서 TextBlock 을 추가하여 LanguageModel 응답을 표시합니다.

   <TextBlock x:Name="OutputText" HorizontalAlignment="Center" VerticalAlignment="Center" />
   

2. MainWindow.xaml.cs 맨 위에 다음 using Microsoft.Windows.AI 지시문을 추가합니다.

   using Microsoft.Windows.AI; 
   

3. 에서 MainWindow.xaml.csMainWindow 클래스를 다음 코드로 바꿉니다. 이 코드는 LanguageModel을 사용할 수 있는지 확인한 다음 모델이 포도당의 분자 공식으로 응답하도록 요청하는 프롬프트를 제출합니다.

   public sealed partial class MainWindow : Window
   {
       public MainWindow()
       {
           this.InitializeComponent();
           InitAI();
       }
   
       private async void InitAI()
       {
           OutputText.Text = "Loading..";
   
           if (LanguageModel.GetReadyState() == AIFeatureReadyState.EnsureNeeded)
           {
               var result = await LanguageModel.EnsureReadyAsync();
               if (result.Status != PackageDeploymentStatus.CompletedSuccess)
               {
                   throw new Exception(result.ExtendedError().Message);
               }
           }            
   
           using LanguageModel languageModel = 
              await LanguageModel.CreateAsync();
   
           string prompt = "Provide the molecular formula of glucose.";
           var result = await languageModel.GenerateResponseAsync(prompt);
           OutputText.Text = result.Response;
       }
   }
   

4. 앱을 빌드하고 실행합니다.

5. 포도당에 대한 수식은 텍스트 블록에 나타납니다.

1. MainWindow.xaml에서 TextBlock 을 추가하여 LanguageModel 응답을 표시합니다.

   <TextBlock x:Name="OutputText" HorizontalAlignment="Center" VerticalAlignment="Center" />
   

2. MainWindow.xaml.cs 맨 위에 다음 using Microsoft.Windows.AI 지시문을 추가합니다.

   using Microsoft.Windows.AI; 
   

3. MainWindow.xaml.cs MainWindow 클래스를 다음 코드로 바꿉니다. 이 코드는 LanguageModel 을 사용할 수 있는지 확인한 다음 모델이 포도당의 분자 공식으로 응답하도록 요청하는 프롬프트를 제출합니다.

   public sealed partial class MainWindow : Window
   {
       public MainWindow()
       {
           this.InitializeComponent();
           InitAI();
       }
   
       private async void InitAI()
       {
           OutputText.Text = "Loading..";
   
           if (LanguageModel.GetReadyState() == AIFeatureReadyState.EnsureNeeded)
           {
               var result = await LanguageModel.EnsureReadyAsync();
               if (result.Status != PackageDeploymentStatus.CompletedSuccess)
               {
                   throw new Exception(result.ExtendedError().Message);
               }
           }            
   
           using LanguageModel languageModel = await LanguageModel.CreateAsync();
   
           string prompt = "Provide the molecular formula for glucose.";
           var result = await languageModel.GenerateResponseAsync(prompt);
           OutputText.Text = result.Response;
       }
   }
   

4. 앱을 빌드하고 실행합니다.

5. 포도당에 대한 수식은 텍스트 블록에 나타납니다.

1. Windows Forms 디자이너에서 레이블을 페이지로 끌어서 OutputLabel로 지정합니다.

2. Form1.cs 맨 위에 다음 using Microsoft.Windows.AI 지시문을 추가합니다.

   using Microsoft.Windows.AI; 
   

3. Form.cs Form 클래스를 다음 코드로 바꿉니다. 이 코드는 LanguageModel 을 사용할 수 있는지 확인한 다음 모델이 포도당의 분자 공식으로 응답하도록 요청하는 프롬프트를 제출합니다.

   public partial class Form1 : Window
   {
       public Form1()
       {
           this.InitializeComponent();
           InitAI();
       }
   
       private async void InitAI()
       {
           OutputLabel.Text = "Loading..";
   
           if (LanguageModel.GetReadyState() == AIFeatureReadyState.EnsureNeeded)
           {
               var result = await LanguageModel.EnsureReadyAsync();
               if (result.Status != PackageDeploymentStatus.CompletedSuccess)
               {
                   throw new Exception(result.ExtendedError().Message);
               }
           }            
   
           using LanguageModel languageModel = await LanguageModel.CreateAsync();
   
           string prompt = "Provide the molecular formula for glucose.";
           var result = await languageModel.GenerateResponseAsync(prompt);
           OutputLabel.Text = result.Response;
       }
   }
   

4. 앱을 빌드하고 실행합니다.

5. 포도당에 대한 수식은 텍스트 블록에 나타납니다.

MAUI 앱에 플랫폼별 코드를 추가하는 방법에 대한 자세한 내용은 플랫폼 코드 호출을 참조하세요.

이 예제에서는 Partial 클래스 및 부분 메서드 접근 방식을 사용하여 Windows 코드를 Platform\Windows 폴더에 배치합니다.

1. MainPage.xaml.cs에 부분 메서드 정의를 추가하고, .NET MAUI 앱 템플릿에서 만든 partial void ChangeLanguageModelAvailability(); 단추의 OnCounterClicked 처리기에서 그 부분 메서드를 호출합니다.

2. 솔루션 탐색기에서 플랫폼을 확장하고, Windows를 마우스 오른쪽 단추로 클릭하고, 클래스 추가>...를 선택하고, MainPage.cs 이름을 입력하고, 추가를 클릭합니다.

3. 새 MainPage.cs 편집기 창에 표시되어야 합니다. MainPage.xaml.cs로 다시 돌아가서 네임스페이스 줄을 복사합니다.

4. 새 MainPage.cs 다시 전환하고 네임스페이스 줄을 MainPage.xaml.cs 줄로 바꿉다. 이는 Platform\Windows 클래스를 기본 MainPage 클래스의 부분 확장으로 만들기 위한 것입니다.

5. MainPage.cs를 확장으로 만들기 완료하려면 클래스 선언에서 internal를 partial로 바꾸세요.

6. 1단계에서 정의된 ChangeLanguageModelAvailability partial 메서드에 다음 코드를 추가합니다.

   partial void ChangeLanguageModelAvailability() 
   { 
      try 
      { 
         AIFeatureReadyState readyState = Microsoft.Windows.AI.LanguageModel.GetReadyState(); 
         System.Diagnostics.Debug.WriteLine($"LanguageModel.GetReadyState: {readyState}"); 
      } 
      catch (Exception e) 
      { 
         System.Diagnostics.Debug.WriteLine($"LanguageModel is not available: {e}"); 
      } 
   }
   

7. 앱을 다시 실행하고 클릭하기 단추를 클릭한 다음 Visual Studio 디버그 출력 창에서 출력을 확인합니다.