Condividi tramite

Informazioni di riferimento sullo schema di origine del catalogo modelli di Windows ML

Questa pagina fornisce la documentazione di riferimento per lo schema JSON usato dall'origine del catalogo dei modelli di Windows ML per definire le origini del catalogo dei modelli. Le origini del catalogo dei modelli sono file JSON che descrivono i modelli di intelligenza artificiale disponibili, la compatibilità e le informazioni di download.

Il file di origine del catalogo modello può essere ospitato online in https:// URL o a cui si fa riferimento come file locale dall'app.

Panoramica dello schema

Un catalogo di modelli è un file JSON che contiene una matrice di definizioni di modello e metadati facoltativi. Lo schema segue le convenzioni standard dello schema JSON ed è progettato per essere leggibile e analizzabile dal computer.

Il catalogo supporta due tipi di distribuzione del modello:

  • Modelli basati su file: modelli distribuiti come singoli file (modelli ONNX, configurazioni e così via)
  • Modelli basati su pacchetti: modelli distribuiti come pacchetti di Windows tramite Store o altri gestori pacchetti

Struttura del catalogo radice

{
  "base": "https://contoso.com/catalog-docs-link",
  "models": [
    // Array of model objects
  ]
}

Proprietà radice

Proprietà TIPO Obbligatorio Description
base string (URI) Yes URL per la documentazione di riferimento dell'API del catalogo
models elenco Yes Matrice di definizioni di modello

Struttura di oggetti modello

Ogni modello nella models matrice segue questa struttura:

{
  "id": "unique-model-id",
  "alias": "model-alias",
  "name": "Model Display Name",
  "version": "1.0.0",
  "modelType": "ONNX",
  "publisher": "Publisher Name",
  "executionProviders": "CPUExecutionProvider",
  "description": "Model description",
  "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"
    }
  ]
}

Proprietà del modello

Proprietà TIPO Obbligatorio Description
id corda Yes Identificatore univoco per questo modello specifico
alias corda NO Nome alias breve per il modello
name corda Yes Nome completo del modello
version corda Yes Numero di versione del modello
modelType corda NO Tipo di modello (attualmente supportato solo "ONNX")
publisher corda Yes Autore o organizzazione che ha creato il modello
executionProviders corda Yes Elenco delimitato da virgole dei provider di esecuzione supportati dal modello
description corda NO Descrizione dettagliata del modello
modelSizeBytes numero intero NO Dimensioni del modello in byte (minimo: 0)
license corda Yes Tipo di licenza (ad esempio, "MIT", "BSD", "Apache")
licenseUri corda Yes URI del documento di licenza
licenseText corda NO Contenuto testuale della licenza
uri corda NO URI di base a cui è possibile accedere al modello
files elenco Condizionale* Matrice di file associati al modello
packages elenco Condizionale* Matrice di pacchetti necessari per il modello

Nota: un modello deve avere files OR packages, ma non entrambi.

Provider di esecuzione

Il executionProviders campo contiene un elenco delimitato da virgole dei nomi dei provider di esecuzione:

"executionProviders": "CPUExecutionProvider,DmlExecutionProvider"

Nomi comuni dei provider di esecuzione:

Nome provider Description
CPUExecutionProvider Esecuzione della CPU (sempre supportata)
QNNExecutionProvider Qualcomm AI Engine (NPU)
OpenVINOExecutionProvider Accelerazione Intel OpenVINO
DmlExecutionProvider DirectML (accelerazione GPU)

Oggetto File

I file vengono usati per distribuire singoli componenti del modello (file ONNX, configurazioni e così via):

{
  "name": "model.onnx",
  "uri": "https://models.example.com/model.onnx",
  "sha256": "d7f93e79ba1284a3ff2b4cea317d79f3e98e64acfce725ad5f4e8197864aef73"
}
Proprietà TIPO Obbligatorio Description
name corda Yes Nome del file.
uri corda NO URI in cui è possibile scaricare il file
sha256 corda Yes Hash SHA256 (stringa esadecimale a 64 caratteri) per la verifica dell'integrità

Nota: se uri non viene specificato, l'URI del file viene costruito dalla proprietà di base uri del modello.

Oggetto package

I pacchetti vengono usati per distribuire i modelli come pacchetti o applicazioni Di Windows:

{
  "packageFamilyName": "Microsoft.Example_8wekyb3d8bbwe",
  "uri": "ms-windows-store://pdp/?ProductId=9EXAMPLE123",
  "sha256": "a1b2c3d4e5f6789..."
}
Proprietà TIPO Obbligatorio Description
packageFamilyName corda Yes Identificatore del nome della famiglia di pacchetti di Windows
uri corda Yes URI in cui è possibile ottenere il pacchetto
sha256 corda Condizionale* Hash SHA256 per la verifica dell'integrità

Nota: sha256 è obbligatorio per gli URI HTTPS, ma facoltativo per altri schemi URI (ad esempio ms-windows-store://).

Metodi di distribuzione

Il catalogo supporta diversi metodi di distribuzione:

Distribuzione basata su file:

  • Download HTTPS diretti
  • File ospitati in GitHub, Azure o in altri server Web
  • File di modello (.onnx), file di configurazione (.json) e asset di supporto

Distribuzione basata su pacchetti:

  • Pacchetti di Microsoft Store (ms-windows-store:// URI)
  • Download diretti dei pacchetti tramite HTTPS
  • Bundle MSIX/APPX e singoli pacchetti

Esempi completi

Esempio di modello basato su file

Ecco un catalogo di esempio con modelli basati su file:

{
  "base": "https://learn.microsoft.com/windows/ai/model-catalog",
  "models": [
    {
      "id": "squeezenet-v1",
      "alias": "squeezenet",
      "name": "SqueezeNet Image Classifier",
      "version": "1.0",
      "modelType": "ONNX",
      "publisher": "WindowsAppSDK",
      "executionProviders": "CPUExecutionProvider",
      "description": "Lightweight CNN for image classification",
      "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"
        }
      ]
    }
  ]
}

Esempio di modello basato su pacchetto

Ecco un catalogo di esempio con modelli basati su pacchetti:

{
  "base": "https://learn.microsoft.com/windows/ai/model-catalog",
  "models": [
    {
      "id": "example-store-model",
      "alias": "store-model",
      "name": "Example Store Model",
      "version": "2.0.0",
      "modelType": "ONNX", 
      "publisher": "Microsoft",
      "executionProviders": "CPUExecutionProvider,DmlExecutionProvider",
      "license": "MIT",
      "licenseUri": "https://opensource.org/licenses/MIT",
      "licenseText": "MIT License - see URI for full text",
      "packages": [
        {
          "packageFamilyName": "Microsoft.ExampleAI_8wekyb3d8bbwe",
          "uri": "ms-windows-store://pdp/?ProductId=9NEXAMPLE123"
        }
      ]
    }
  ]
}

Convalida dello schema

Il catalogo dei modelli di Windows ML segue la specifica dello schema JSON (bozza 2020-12). È possibile convalidare i file di catalogo rispetto allo schema ufficiale per garantire la compatibilità.

Regole di convalida chiave

  1. Campi obbligatori: ogni modello deve avere id, name, version, publisher, executionProviderse license
  2. Distribuzione esclusiva: i modelli devono specificare files OR packages, ma non entrambi
  3. Formato SHA256: tutti gli hash SHA256 devono essere esattamente 64 caratteri esadecimali
  4. Provider di esecuzione: deve essere oggetti con almeno una name proprietà
  5. Formato URI: tutti gli URI devono essere formattati correttamente in base a RFC 3986
  6. Requisiti HTTPS: i download dei pacchetti tramite HTTPS devono includere hash SHA256

Errori di convalida comuni

  • Campi obbligatori mancanti: verificare che tutte le proprietà obbligatorie siano presenti
  • SHA256 non valido: verificare che i valori hash siano esattamente 64 caratteri esadecimali
  • Distribuzione mista: non specificare sia files che packages per lo stesso modello
  • URI non validi: verificare che tutti gli URI siano formattati correttamente e accessibili
  • Sha256 mancante per i pacchetti HTTPS: i download dei pacchetti HTTPS richiedono la verifica dell'integrità

Creazione del catalogo

Passaggio 1: Scegliere il metodo di distribuzione

Usare la distribuzione basata su file quando:

  • I modelli sono file ONNX standard con asset di supporto
  • È disponibile l'hosting Web per i file di modello
  • Si desidera scaricare HTTPS semplici
  • I modelli sono relativamente piccoli (< 1 GB per file)

Usare la distribuzione basata su pacchetti quando:

  • I modelli richiedono l'integrazione del sistema
  • Si sta distribuendo tramite Microsoft Store
  • I modelli includono provider di esecuzione o dipendenze
  • Sono necessarie funzionalità di gestione dei pacchetti di Windows

Passaggio 2: Strutturare i modelli

{
  "models": [
    {
      "id": "unique-identifier-v1.0",
      "name": "Human Readable Model Name",
      "version": "1.0.0",
      "publisher": "YourOrganization",
      "executionProviders": "CPUExecutionProvider",
      "license": "MIT"
      // Add files[] or packages[] here
    }
  ]
}

Passaggio 3: Aggiungere i dettagli della distribuzione

Per i modelli basati su file:

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

Per i modelli basati su pacchetti:

"packages": [
  {
    "packageFamilyName": "YourPublisher.YourApp_randomstring", 
    "uri": "ms-windows-store://pdp/?ProductId=YourProductId"
  }
]

Passaggio 4: Testare il catalogo

  1. Convalidare la sintassi JSON usando un validator JSON
  2. Verificare che tutti gli URI siano accessibili e restituire contenuto corretto
  3. Controllare che gli hash SHA256 corrispondano al contenuto effettivo del file
  4. Testare il download del modello usando le API del catalogo di modelli di Windows ML

Procedure consigliate

  1. Usare il controllo delle versioni semantiche: seguire il controllo delle versioni semantiche (ad esempio, "1.2.3") per il version campo
  2. Fornire hash SHA256 accurati: includere sempre hash SHA256 corretti per la verifica dell'integrità
  3. Denominazione coerente: usare convenzioni di denominazione coerenti per alias e ID tra le versioni del modello
  4. Descrizioni chiare: scrivere descrizioni utili che spiegano le funzionalità del modello e i casi d'uso
  5. Licenze appropriate: includere sempre informazioni complete sulla licenza (tipo, URI e testo)
  6. Accessibilità di test: verificare che tutti gli URI siano accessibili e restituire il contenuto previsto
  7. Compatibilità del provider di esecuzione: assicurarsi che i provider di esecuzione corrispondano alle funzionalità hardware di destinazione
  8. Raggruppamento logico: usare alias per raggruppare le varianti di modello correlate (versioni ep diverse dello stesso modello di base)
  9. Organizzazione file: mantenere insieme i file correlati e usare nomi di file descrittivi
  10. Sicurezza: usare HTTPS per tutti i download di file e includere la verifica SHA256

Considerazioni sull'hosting

Quando si ospita un catalogo di modelli:

  1. HTTPS obbligatorio: gestire sempre cataloghi e modelli tramite HTTPS
  2. Intestazioni CORS: configurare le intestazioni CORS appropriate per l'accesso tra le origini
  3. Content-Type: Serve catalog JSON con application/json tipo di contenuto
  4. Intestazioni della cache: impostare le intestazioni della cache appropriate per le prestazioni
  5. Autenticazione: supportare l'autenticazione HTTP standard, se necessario

Schema JSON

Di seguito è riportato lo schema JSON che può essere usato per la convalida del payload JSON.

{
  "$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": [ "base", "models" ],
  "properties": {
    "base": {
      "type": "string",
      "format": "uri",
      "description": "Base URL for the catalog API reference"
    },
    "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", "licenseUri" ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the model"
        },
        "alias": {
          "type": "string",
          "description": "Short alias name for the model"
        },
        "name": {
          "type": "string",
          "description": "Full name of the model"
        },
        "version": {
          "type": "string",
          "description": "Version of the model"
        },
        "modelType": {
          "type": "string",
          "enum": [ "ONNX" ],
          "description": "Type of machine learning model"
        },
        "publisher": {
          "type": "string",
          "description": "Publisher or organization that created the model"
        },
        "executionProviders": {
          "type": "string",
          "description": "Comma-separated list of execution providers supported by the model"
        },
        "description": {
          "type": "string",
          "description": "Detailed description of the model"
        },
        "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"
        },
        "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" ]
      }
    }
  }
}

Passaggi successivi

  • Last updated on