Referenz zum Quellschema des Windows ML-Modellkatalogs

Diese Seite enthält Referenzdokumentation für das JSON-Schema, das von der Windows ML-Modellkatalogquelle zum Definieren von Modellkatalogquellen verwendet wird. Modellkatalogquellen sind JSON-Dateien, die verfügbare KI-Modelle, deren Kompatibilität und Downloadinformationen beschreiben.

Ihre Modellkatalogquelldatei kann online unter https:// URLs gehostet oder als lokale Datei aus Ihrer App referenziert werden.

Schemaübersicht

Ein Modellkatalog ist eine JSON-Datei, die ein Array von Modelldefinitionen und optionalen Metadaten enthält. Das Schema folgt standardmäßigen JSON-Schemakonventionen und ist so konzipiert, dass es sowohl lesbar als auch maschinenparsierbar ist.

Der Katalog unterstützt zwei Typen von Modellverteilungen:

• Dateibasierte Modelle: Modelle, die als einzelne Dateien verteilt werden (ONNX-Modelle, Konfigurationen usw.)
• Paketbasierte Modelle: Modelle, die als Windows-Pakete (MSIX) verteilt werden

Stammkatalogstruktur

{
  "models": [
    // Array of model objects
  ]
}

Stammeigenschaften

Modellobjektstruktur

Jedes Modell im models Array folgt dieser Struktur:

{
  "id": "phi-3.5-cpu",
  "name": "phi-3.5",
  "version": "1.0.0",
  "publisher": "Publisher Name",
  "executionProviders": [
    {
      "name": "CPUExecutionProvider"
    }
  ],
  "modelSizeBytes": 13632917530,
  "license": "MIT",
  "licenseUri": "https://opensource.org/licenses/MIT",
  "licenseText": "License text content",
  "uri": "https://models.example.com/model-base",
  "files": [
    {
      "name": "model.onnx",
      "uri": "https://models.example.com/model.onnx",
      "sha256": "d7f93e79ba1284a3ff2b4cea317d79f3e98e64acfce725ad5f4e8197864aef73"
    }
  ]
}

Modelleigenschaften

Hinweis: Ein Modell muss entweder files ODER packageshaben, aber nicht beide.

Ausführungsanbieter

Das executionProviders Feld ist ein Array von Ausführungsanbieterobjekten. Jedes Ausführungsanbieterobjekt muss mindestens eine name Eigenschaft aufweisen:

"executionProviders": [
  {
    "name": "CPUExecutionProvider"
  },
  {
    "name": "DmlExecutionProvider"
  }
]

Eine umfassende Liste aller verfügbaren Ausführungsanbieter finden Sie auf der Seite "Unterstützte Ausführungsanbieter" auf der Windows ML-Dokumentationsseite .

File-Objekt

Dateien werden verwendet, um einzelne Modellkomponenten zu verteilen (ONNX-Dateien, Konfigurationen usw.):

{
  "name": "model.onnx",
  "uri": "https://models.example.com/model.onnx",
  "sha256": "d7f93e79ba1284a3ff2b4cea317d79f3e98e64acfce725ad5f4e8197864aef73"
}

Hinweis: Wenn uri nicht angegeben, wird der Datei-URI aus der Basiseigenschaft uri des Modells erstellt.

Package-Objekt

Pakete werden verwendet, um Modelle als Windows-Pakete oder -Anwendungen zu verteilen:

{
  "packageFamilyName": "Microsoft.Example_8wekyb3d8bbwe",
  "uri": "https://example.com/packages/model.msix",
  "sha256": "a1b2c3d4e5f6789..."
}

Verteilungsmethoden

Der Katalog unterstützt mehrere Verteilungsmethoden:

Dateibasierte Verteilung:

• Direkte HTTPS-Downloads
• Auf GitHub, Azure oder anderen Webservern gehostete Dateien
• Modelldateien (.onnx), Konfigurationsdateien (.json) und unterstützende Ressourcen

Paketbasierte Verteilung:

• Direkte Paketdownloads über HTTPS
• Lokale Dateipfade für Pakete
• MSIX-Pakete

Vollständige Beispiele

Beispiel für ein dateibasiertes Modell

Hier ist ein Beispielkatalog mit dateibasierten Modellen:

{
  "models": [
    {
      "id": "squeezenet-v1",
      "name": "squeezenet",
      "version": "1.0",
      "publisher": "WindowsAppSDK",
      "executionProviders": [
        {
          "name": "CPUExecutionProvider"
        }
      ],
      "modelSizeBytes": 13632917530,
      "license": "BSD",
      "licenseUri": "https://github.com/microsoft/WindowsAppSDK-Samples/raw/main/LICENSE",
      "licenseText": "BSD 3-Clause License",
      "uri": "https://github.com/microsoft/WindowsAppSDK-Samples/raw/main/models",
      "files": [
        {
          "name": "SqueezeNet.onnx",
          "uri": "https://github.com/microsoft/WindowsAppSDK-Samples/raw/main/models/SqueezeNet.onnx",
          "sha256": "d7f93e79ba1284a3ff2b4cea317d79f3e98e64acfce725ad5f4e8197864aef73"
        },
        {
          "name": "Labels.txt",
          "uri": "https://github.com/microsoft/WindowsAppSDK-Samples/raw/main/models/Labels.txt", 
          "sha256": "dc1fd0d4747096d3aa690bd65ec2f51fdb3e5117535bfbce46fa91088a8f93a9"
        }
      ]
    }
  ]
}

Beispiel für paketbasiertes Modell

Hier ist ein Beispielkatalog mit paketbasierten Modellen:

{
  "models": [
    {
      "id": "example-packaged-model-cpu",
      "name": "example-packaged-model",
      "version": "2.0.0",
      "publisher": "Microsoft",
      "executionProviders": [
        {
          "name": "CPUExecutionProvider"
        },
        {
          "name": "DmlExecutionProvider"
        }
      ],
      "license": "MIT",
      "licenseUri": "https://opensource.org/licenses/MIT",
      "licenseText": "MIT License - see URI for full text",
      "packages": [
        {
          "packageFamilyName": "Microsoft.ExampleAI_8wekyb3d8bbwe",
          "uri": "https://example.com/packages/ExampleAI.msix",
          "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        }
      ]
    }
  ]
}

Schemavalidierung

Der Windows ML-Modellkatalog folgt der JSON-Schemaspezifikation (Entwurf 2020-12). Sie können Ihre Katalogdateien anhand des offiziellen Schemas überprüfen, um die Kompatibilität sicherzustellen.

Wichtige Gültigkeitsprüfungsregeln

1. Erforderliche Felder: Jedes Modell muss idüber , name, version, publisher, und executionProviderslicense
2. Exklusive Verteilung: Modelle müssen entweder files ODER packagesangeben, aber nicht beide
3. SHA256-Format: Alle SHA256-Hashes müssen genau 64 Hexadezimalzeichen sein.
4. Ausführungsanbieter: Muss Objekte mit mindestens einer name Eigenschaft sein
5. URI-Format: Alle URIs müssen gemäß RFC 3986 ordnungsgemäß formatiert sein.
6. HTTPS-Paketintegrität: Paketdownloads über HTTPS müssen SHA256-Hashes für die Integritätsprüfung enthalten.

Häufige Überprüfungsfehler

• Fehlende Pflichtfelder: Stellen Sie sicher, dass alle erforderlichen Eigenschaften vorhanden sind.
• Ungültiges SHA256: Überprüfen Sie, ob Hashwerte genau 64 Hexzeichen sind.
• Gemischte Verteilung: Geben Sie nicht sowohl als auch filespackages für dasselbe Modell an
• Ungültige URIs: Überprüfen, ob alle URIs ordnungsgemäß formatiert und barrierefrei sind
• Fehlende SHA256 für HTTPS-Pakete: HTTPS-Paketdownloads erfordern integritätsüberprüfung

Erstellen ihres Katalogs

Schritt 1: Auswählen der Verteilungsmethode

Verwenden Sie die dateibasierte Verteilung in folgenden Fällen:

• Ihre Modelle sind standardmäßige ONNX-Dateien mit unterstützenden Ressourcen
• Sie haben Webhosting für Modelldateien
• Sie möchten einfache HTTPS-Downloads
• Modelle sind relativ klein (< 1 GB pro Datei)

Paketbasierte Verteilung verwenden, wenn:

• Für Ihre Modelle ist eine Systemintegration erforderlich.
• Modelle umfassen Ausführungsanbieter oder Abhängigkeiten
• Sie benötigen Windows-Paketverwaltungsfeatures
• Sie möchten über MSIX-Pakete verteilen

Schritt 2: Strukturieren Ihrer Modelle

{
  "models": [
    {
      "id": "unique-identifier-cpu",
      "name": "unique-identifier",
      "version": "1.0.0",
      "publisher": "YourOrganization",
      "executionProviders": [
        {
          "name": "CPUExecutionProvider"
        }
      ],
      "license": "MIT",
      "files": []  // or "packages": []
    }
  ]
}

Schritt 3: Hinzufügen von Verteilungsdetails

Für dateibasierte Modelle:

"uri": "https://yourserver.com/models/base-path",
"files": [
  {
    "name": "model.onnx",
    "sha256": "your-calculated-sha256-hash"
  }
]

Für paketbasierte Modelle:

"packages": [
  {
    "packageFamilyName": "YourPublisher.YourApp_randomstring",
    "uri": "https://yourserver.com/packages/YourApp.msix",
    "sha256": "your-calculated-sha256-hash"
  }
]

Schritt 4: Testen Des Katalogs

1. Überprüfen der JSON-Syntax mithilfe eines JSON-Validators
2. Überprüfen, ob auf alle URIs zugegriffen werden kann und korrekte Inhalte zurückgegeben werden
3. Überprüfen von SHA256-Hashes mit dem tatsächlichen Dateiinhalt
4. Testen des Modelldownloads mithilfe der Windows ML-Modellkatalog-APIs

Bewährte Methoden

1. Verwenden der semantischen Versionsverwaltung: Folgen der semantischen Versionsverwaltung (z. B. "1.2.3") für das version Feld
2. Bereitstellen präziser SHA256-Hashes: Geben Sie immer korrekte SHA256-Hashes zur Integritätsüberprüfung an.
3. Einheitliche Benennung: Verwenden konsistenter Benennungskonventionen für IDs und Namen in modellübergreifenden Versionen
4. Klare Beschreibungen: Schreiben Sie hilfreiche Beschreibungen, die Modellfunktionen und Anwendungsfälle erläutern
5. Ordnungsgemäße Lizenzierung: Schließen Sie immer vollständige Lizenzinformationen (Typ, URI und Text) ein.
6. Testen der Barrierefreiheit: Stellen Sie sicher, dass auf alle URIs zugegriffen werden kann, und geben Sie den erwarteten Inhalt zurück.
7. Kompatibilität des Ausführungsanbieters: Sicherstellen, dass Ausführungsanbieter den Zielhardwarefunktionen entsprechen
8. Logische Gruppierung: Verwenden des Namensfelds zum Gruppieren verwandter Modellvarianten (unterschiedliche EP-Versionen des gleichen Basismodells)
9. Dateiorganisation: Zusammenhalten verwandter Dateien und Verwenden aussagekräftiger Dateinamen
10. Sicherheit: Https für alle Dateidownloads verwenden und SHA256-Überprüfung einschließen

Überlegungen zum Hosting

Beim Hosten eines Modellkatalogs:

1. HTTPS erforderlich: Immer Kataloge und Modelle über HTTPS bereitstellen
2. CORS-Header: Konfigurieren der entsprechenden CORS-Header für den ursprungsübergreifenden Zugriff
3. Content-Type: Serve catalog JSON with application/json content type
4. Cacheheader: Festlegen geeigneter Cacheheader für die Leistung
5. Authentifizierung: Unterstützung der standardmäßigen HTTP-Authentifizierung bei Bedarf

JSON-Schema

Im Folgenden sehen Sie das JSON-Schema, das für die Überprüfung Ihrer JSON-Nutzlast verwendet werden kann.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "WinML Model Catalog Schema",
  "description": "JSON schema for WindowsML Model catalog configuration",
  "type": "object",
  "required": [ "models" ],
  "properties": {
    "models": {
      "type": "array",
      "description": "Array of machine learning models in the catalog",
      "items": {
        "$ref": "#/$defs/Model"
      }
    }
  },
  "$defs": {
    "Model": {
      "type": "object",
      "required": [ "id", "name", "version", "publisher", "executionProviders", "license" ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique-in-the-catalog identifier for the model"
        },
        "name": {
          "type": "string",
          "description": "Common name of the model"
        },
        "version": {
          "type": "string",
          "description": "Version of the model"
        },
        "publisher": {
          "type": "string",
          "description": "Publisher or organization that created the model"
        },
        "executionProviders": {
          "type": "array",
          "description": "Array of execution providers supported by the model",
          "items": {
            "$ref": "#/$defs/ExecutionProvider"
          }
        },
        "modelSizeBytes": {
          "type": "integer",
          "minimum": 0,
          "description": "Size of the model in bytes"
        },
        "license": {
          "type": "string",
          "description": "License type (e.g., MIT, BSD, Apache)"
        },
        "licenseUri": {
          "type": "string",
          "format": "uri",
          "description": "URI to the license document"
        },
        "licenseText": {
          "type": "string",
          "description": "Text content of the license"
        },
        "uri": {
          "type": "string",
          "format": "uri",
          "description": "URI where the model can be accessed"
        },
        "files": {
          "type": "array",
          "description": "Array of files associated with the model",
          "items": {
            "$ref": "#/$defs/File"
          }
        },
        "packages": {
          "type": "array",
          "description": "Array of packages required for the model",
          "items": {
            "$ref": "#/$defs/Package"
          }
        }
      },
      "oneOf": [
        {
          "required": [ "files" ],
          "not": { "required": [ "packages" ] }
        },
        {
          "required": [ "packages" ],
          "not": { "required": [ "files" ] }
        }
      ]
    },
    "File": {
      "type": "object",
      "required": [ "name", "sha256" ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the file"
        },
        "uri": {
          "type": "string",
          "format": "uri",
          "description": "URI where the file can be downloaded"
        },
        "sha256": {
          "type": "string",
          "pattern": "^[a-fA-F0-9]{64}$",
          "description": "SHA256 hash of the file for integrity verification"
        }
      }
    },
    "Package": {
      "type": "object",
      "required": [ "packageFamilyName", "uri" ],
      "properties": {
        "packageFamilyName": {
          "type": "string",
          "description": "Windows package family name identifier"
        },
        "uri": {
          "type": "string",
          "format": "uri",
          "description": "URI where the package can be obtained (HTTPS or local file path)"
        },
        "sha256": {
          "type": "string",
          "pattern": "^[a-fA-F0-9]{64}$",
          "description": "SHA256 hash of the package for integrity verification"
        }
      },
      "if": {
        "properties": {
          "uri": {
            "pattern": "^https://"
          }
        }
      },
      "then": {
        "required": [ "packageFamilyName", "uri", "sha256" ]
      }
    },
    "ExecutionProvider": {
      "type": "object",
      "required": [ "name" ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the execution provider (e.g., CPUExecutionProvider)"
        }
      }
    }
  }
}

Nächste Schritte

• Informationen zum Modellkatalog (Übersicht)
• Folgen Sie dem Leitfaden "Erste Schritte".
• Windows ML-Dokumentation erkunden