Freigeben über

Erste Schritte mit Windows ML-Modellkatalog-APIs

In diesem Handbuch erfahren Sie, wie Sie die Windows ML-Modellkatalog-APIs zum Verwalten von KI-Modellen in Ihren Windows-Anwendungen verwenden. Sie erfahren, wie Sie Katalogquellen einrichten, kompatible Modelle finden und sie an einem freigegebenen Speicherort auf dem Gerät speichern, sodass alle Apps darauf zugreifen können.

Voraussetzungen

Schritt 1: Erstellen einer Modellkatalogquelle

Sie müssen zuerst eine Modellkatalogquelle erstellen oder abrufen, bei der es sich um einen Index von Modellen handelt, einschließlich Informationen zum Zugriff auf das Modell. Weitere Informationen finden Sie in den Dokumentdokumenten zur Modellkatalogquelle .

Die JSON-Datei des Modellkatalogs kann entweder online gehostet, über https:// Endpunkte referenziert oder aus einer lokalen Datei referenziert werden, auf die über Dateipfade wie C:\Users\... verwiesen wird.

Schritt 2: Initialisieren Sie Ihren Katalog mit Ihrer Quelle

Initialisieren eines Katalogs mit einer einzelnen Katalogquelle:

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

Sie können auch mehrere Katalogquellen mit unterschiedlichen Prioritäten konfigurieren:

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

Schritt 3: Suchen eines Modells anhand des Namens

Suchen Nach einem Modell in allen konfigurierten Quellen:

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

Schritt 4: Herunterladen und Verwenden eines Modells

Rufen Sie eine Modellinstanz ab, und verwenden Sie sie mit Ihrem gewünschten Framework:

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

Vollständiges Beispiel

Hier ist ein vollständiges Beispiel, das alles zusammenfügt:

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

Filtern nach Ausführungsanbietern

Passen Sie die zu berücksichtigenden Ausführungsanbieter an:

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

Überprüfen des Modellstatus

Überprüfen Sie, ob ein Modell bereits lokal verfügbar ist:

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

Verwenden von lokalen Katalogdateien

Erstellen Sie eine Katalogquelle aus einer lokalen Datei:

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

Hinzufügen von benutzerdefinierten Kopfzeilen für Downloads

Stellen Sie Authentifizierungs- oder benutzerdefinierte Header für Modelldownloads bereit.

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

Fehlerbehandlung

Geben Sie beim Arbeiten mit dem Modellkatalog immer die richtige Fehlerbehandlung an:

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

Bewährte Methoden

  1. Wiederverwendung von Kataloginstanzen: Wiederverwendung von ModelCatalog Instanzen in Ihrer gesamten App
  2. Behandeln des Downloadfortschritts: Bereitstellung von Benutzerfeedback während des Modelldownloads
  3. Entsorgen von Modellinstanzen: Verwenden Sie using-Anweisungen zum ordnungsgemäßen Entsorgen von Modellinstanzen
  4. Kompatibilität überprüfen: Überprüfen, ob modellausführungsanbieter Ihren Anforderungen entsprechen
  5. Behandeln von Fehlern ordnungsgemäß: Überprüfen Sie immer den Ergebnisstatus, bevor Sie Modelle verwenden
  6. Modellnamen verwenden: Verwenden FindModelAsync mit Modellnamen für die automatische Auswahl der besten Modellvariante basierend auf den Gerätefunktionen.

Nächste Schritte

  • Last updated on