Windows ML 모델 카탈로그 API 시작

이 가이드에서는 Windows ML 모델 카탈로그 API를 사용하여 Windows 애플리케이션에서 AI 모델을 관리하는 방법을 보여 줍니다. 카탈로그 원본을 설정하고, 호환되는 모델을 찾고, 사용할 모든 앱에 대해 디바이스의 공유 위치에 다운로드하는 방법을 알아봅니다.

필수 조건

Windows 앱 SDK에서 지원하는 Windows 버전을 실행하는 Windows PC
하나 이상의 모델 카탈로그 원본
호환되는 프로젝트에서 Windows 앱 SDK 1.8.3 이상

1단계: 모델 카탈로그 원본 만들기

먼저 모델에 액세스하는 방법에 대한 정보를 포함하여 모델의 인덱스인 모델 카탈로그 원본을 만들거나 가져와야 합니다. 자세한 내용은 모델 카탈로그 원본 문서를 참조하세요 .

모델 카탈로그 원본 JSON 파일은 온라인으로 호스트되거나, 엔드포인트를 통해 https:// 참조되거나, 로컬 파일에서 사용되며, 같은 C:\Users\...파일 경로를 통해 참조될 수 있습니다.

2단계: 소스를 사용하여 카탈로그를 초기화하기

단일 카탈로그 원본을 사용하여 카탈로그를 초기화합니다.

using Microsoft.Windows.AI.MachineLearning;
using Windows.Foundation;
using System;
using System.Threading.Tasks;

// Create a catalog source from a URI
var source = await ModelCatalogSource.CreateFromUriAsync(
    new Uri("https://contoso.com/models"));

// Create the catalog with the source
var catalog = new ModelCatalog(new ModelCatalogSource[] { source });

우선 순위가 다른 여러 카탈로그 원본을 구성할 수도 있습니다.

var catalog = new ModelCatalog(new ModelCatalogSource[0]);

// Add sources in order of preference (highest priority first)
catalog.Sources.Add(await ModelCatalogSource.CreateFromUriAsync(
    new Uri("https://contoso.com/models")));
catalog.Sources.Add(await ModelCatalogSource.CreateFromUriAsync(
    new Uri("https://contoso.com/secondaryModels")));

3단계: 이름으로 모델 찾기

구성된 모든 원본에서 모델을 검색합니다.

// Find a model by its name
CatalogModelInfo model = await catalog.FindModelAsync("phi-3.5-reasoning");

if (model != null)
{
    Console.WriteLine($"Found model: {model.Name}");
    Console.WriteLine($"Version: {model.Version}");
    Console.WriteLine($"Publisher: {model.Publisher}");
    Console.WriteLine($"Size: {model.ModelSizeInBytes / (1024 * 1024)} MB");
    Console.WriteLine($"Supported execution providers: {string.Join(", ", model.ExecutionProviders)}");
}

4단계: 모델 다운로드 및 사용

모델 인스턴스를 가져와 원하는 프레임워크에서 사용합니다.

// Get an instance of the model (downloads if necessary)
var progress = new Progress<double>(percent => 
    Console.WriteLine($"Download progress: {percent:P}"));

CatalogModelInstanceResult result = await model.GetInstanceAsync().AsTask(progress);

if (result.Status == CatalogModelInstanceStatus.Available)
{
    CatalogModelInstance instance = result.GetInstance();

    // Get the model path
    string modelPath = instance.ModelPaths[0];
    
    Console.WriteLine($"Model path: {modelPath}");
    
    // Inference your model using your own code
}
else
{
    Console.WriteLine($"Failed to get model: {result.ExtendedError}");
    Console.WriteLine($"Details: {result.DiagnosticText}");
}

전체 예제

다음은 이 모든 것을 하나로 묶는 전체 예제입니다.

using Microsoft.Windows.AI.MachineLearning;
using System;
using System.Threading.Tasks;

try
{
    // Create catalog with source
    var source = await ModelCatalogSource.CreateFromUriAsync(
        new Uri("https://contoso.com/models"));
    var catalog = new ModelCatalog(new ModelCatalogSource[] { source });
    
    // Find a model
    Console.WriteLine("Searching for model...");
    CatalogModelInfo model = await catalog.FindModelAsync("phi-3.5-reasoning");
    
    if (model != null)
    {
        Console.WriteLine($"Found model: {model.Name}");
        Console.WriteLine($"Version: {model.Version}");
        Console.WriteLine($"Publisher: {model.Publisher}");
        Console.WriteLine($"Size: {model.ModelSizeInBytes / (1024 * 1024)} MB");
        Console.WriteLine($"Supported execution providers: {string.Join(", ", model.ExecutionProviders)}");
        
        // Get an instance of the model (downloads if necessary)
        var progress = new Progress<double>(percent => 
            Console.WriteLine($"Download progress: {percent:P}"));
        
        CatalogModelInstanceResult result = await model.GetInstanceAsync().AsTask(progress);
        
        if (result.Status == CatalogModelInstanceStatus.Available)
        {
            CatalogModelInstance instance = result.GetInstance();

            // Get the model path
            string modelPath = instance.ModelPaths[0];
            
            Console.WriteLine($"Model path: {modelPath}");
            
            // Inference your model using your own code
        }
        else
        {
            Console.WriteLine($"Failed to get model: {result.ExtendedError}");
            Console.WriteLine($"Details: {result.DiagnosticText}");
        }
    }
    else
    {
        Console.WriteLine("Model not found");
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

실행 공급자별 필터링

고려할 실행 공급자를 사용자 지정합니다.

public async Task FilterByExecutionProvidersAsync(ModelCatalog catalog)
{
    // Only look for CPU-compatible models
    catalog.ExecutionProviders.Clear();
    catalog.ExecutionProviders.Add("cpuexecutionprovider");
    
    var cpuModels = await catalog.FindAllModelAsync();
    Console.WriteLine($"Found {cpuModels.Count} CPU-compatible models");
    
    // Look for DirectML-compatible models
    catalog.ExecutionProviders.Clear();
    catalog.ExecutionProviders.Add("dmlexecutionprovider");
    
    var dmlModels = await catalog.FindAllModelAsync();
    Console.WriteLine($"Found {dmlModels.Count} DirectML-compatible models");
}

모델 상태 확인

모델을 로컬에서 이미 사용할 수 있는지 확인합니다.

public void CheckModelStatus(ModelCatalog catalog)
{
    var availableModels = catalog.GetAvailableModels();
    
    foreach (var model in availableModels)
    {
        var status = model.GetStatus();
        Console.WriteLine($"Model {model.Name}: {status}");
        
        switch (status)
        {
            case CatalogModelStatus.Ready:
                Console.WriteLine("  ✓ Available locally");
                break;
            case CatalogModelStatus.NotReady:
                Console.WriteLine("  ⚠ Needs to be downloaded");
                break;
        }
    }
}

로컬 카탈로그 파일 사용

로컬 파일에서 카탈로그 원본을 만듭니다.

public async Task<ModelCatalog> CreateLocalCatalogAsync()
{
    // Load catalog from a local JSON file
    var localFile = Path.Combine(Package.Current.EffectivePath, "my-models.json");
    var source = await ModelCatalogSource.CreateFromUriAsync(new Uri(localFile));
    
    var catalog = new ModelCatalog(new ModelCatalogSource[] { source });
    return catalog;
}

다운로드에 대한 사용자 지정 헤더 추가

모델 다운로드에 대한 인증 또는 사용자 지정 헤더를 제공합니다.

public async Task DownloadWithCustomHeadersAsync(CatalogModelInfo model)
{
    var headers = new Dictionary<string, string>
    {
        ["Authorization"] = "Bearer your-token-here",
        ["User-Agent"] = "MyApp/1.0"
    };
    
    var result = await model.GetInstanceAsync(headers);
    // Handle result...
}

오류 처리

모델 카탈로그로 작업할 때 항상 적절한 오류 처리를 포함합니다.

public async Task<bool> SafeModelUsageAsync(string modelName)
{
    try
    {
        var source = await ModelCatalogSource.CreateFromUriAsync(
            new Uri("https://contoso.com/models"));
        var catalog = new ModelCatalog(new ModelCatalogSource[] { source });
        
        var model = await catalog.FindModelAsync(modelName);
        if (model == null)
        {
            Console.WriteLine($"Model '{modelName}' not found");
            return false;
        }
        
        var result = await model.GetInstanceAsync();
        if (result.Status != CatalogModelInstanceStatus.Available)
        {
            Console.WriteLine($"Failed to get model: {result.ExtendedError}");
            if (!string.IsNullOrEmpty(result.DiagnosticText))
            {
                Console.WriteLine($"Details: {result.DiagnosticText}");
            }
            return false;
        }
        
        using var instance = result.GetInstance();
        // Use the model...
        return true;
    }
    catch (UnauthorizedAccessException)
    {
        Console.WriteLine("Access denied - check permissions");
        return false;
    }
    catch (System.Net.Http.HttpRequestException ex)
    {
        Console.WriteLine($"Network error: {ex.Message}");
        return false;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Unexpected error: {ex.Message}");
        return false;
    }
}

모범 사례

카탈로그 인스턴스 다시 사용: 앱에서 인스턴스 다시 사용 ModelCatalog
다운로드 진행률 처리: 모델 다운로드 중에 사용자 피드백 제공
모델 인스턴스 삭제: 문을 사용하여 using 모델 인스턴스를 올바르게 삭제
호환성 확인: 모델 실행 공급자가 요구 사항과 일치하는지 확인
정상적으로 오류 처리: 모델을 사용하기 전에 항상 결과 상태 확인
모델 이름 사용: 디바이스 기능에 따라 최상의 모델 변형을 자동으로 선택하기 위해 모델 이름과 함께 사용 FindModelAsync

다음 단계

모델 카탈로그 원본 스키마에 대해 알아보기
Windows ML 개요 살펴보기

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-12