Rozpocznij pracę z interfejsami API katalogu modeli uczenia maszynowego Windows

W tym przewodniku pokazano, jak używać interfejsów API wykazu modeli uczenia maszynowego systemu Windows do udostępniania modeli sztucznej inteligencji między aplikacjami na komputerze użytkownika. Dowiesz się, jak skonfigurować źródła katalogu, znaleźć zgodne modele i pobrać je do wspólnej lokalizacji na urządzeniu, aby mogły być używane przez wszystkie aplikacje.

Wymagania wstępne

Krok 1. Tworzenie źródła wykazu modeli

Najpierw należy utworzyć lub uzyskać źródło wykazu modeli, które jest indeksem modeli, w tym informacje o sposobie uzyskiwania dostępu do modelu. Aby uzyskać więcej informacji, zobacz dokumentację źródłową wykazu modeli .

Plik JSON źródła wykazu modeli może być hostowany w trybie online, przywoływany za pośrednictwem https:// punktów końcowych lub używany z pliku lokalnego, do którego można uzyskać dostęp poprzez ścieżki plików takie jak C:\Users\....

Krok 2. Inicjowanie katalogu przy użyciu źródła

Zainicjuj wykaz za pomocą pojedynczego źródła wykazu:

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

Można również skonfigurować wiele źródeł wykazu z różnymi priorytetami:

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

Krok 3. Znajdowanie modelu według nazwy

Wyszukaj model we wszystkich skonfigurowanych źródłach:

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

Krok 4. Pobieranie i używanie modelu

Pobierz wystąpienie modelu i użyj go z pożądanym frameworkiem.

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

Kompletny przykład

Oto kompletny przykład, który ujął to wszystko razem:

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

Filtrowanie według dostawców przetwarzania

Dostosuj dostawców wykonywania, które należy wziąć pod uwagę:

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

Sprawdzanie stanu modelu

Sprawdź, czy model jest już dostępny lokalnie:

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

Korzystanie z plików wykazu lokalnego

Utwórz źródło wykazu na podstawie pliku lokalnego:

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

Dodawanie niestandardowych nagłówków do pobrania

Podaj uwierzytelnianie lub nagłówki niestandardowe dla pobierania modeli:

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

Obsługa błędów

Zawsze uwzględnij prawidłową obsługę błędów podczas pracy z katalogiem modeli:

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

Najlepsze rozwiązania

  1. Ponowne używanie wystąpień katalogu: Ponowne używanie ModelCatalog wystąpień w aplikacji
  2. Obsługa postępu pobierania: przekazywanie opinii użytkowników podczas pobierania modelu
  3. Zwalnianie wystąpień modelu: użyj using instrukcji do prawidłowego zwalniania wystąpień modelu
  4. Sprawdź zgodność: Sprawdź, czy dostawcy wykonywania modelu spełniają wymagania
  5. Obsługa niepowodzeń w sposób bezproblemowy: zawsze sprawdzaj stan wyników przed użyciem modeli
  6. Użyj nazw modeli: użyj FindModelAsync z nazwami modeli do automatycznego wyboru najlepszego wariantu modelu na podstawie możliwości urządzenia

Dalsze kroki

  • Last updated on