Dokumentacja schematu źródłowego wykazu modeli uczenia maszynowego systemu Windows

Ta strona zawiera dokumentację referencyjną schematu JSON używanego przez źródło wykazu modeli uczenia maszynowego systemu Windows do definiowania źródeł wykazu modeli. Źródła wykazu modeli to pliki JSON, które opisują dostępne modele sztucznej inteligencji, ich zgodność i pobieranie informacji.

Plik źródłowy wykazu modeli może być hostowany w trybie online pod https:// adresem URL lub przywołyny jako plik lokalny z aplikacji.

Przegląd schematu

Wykaz modeli to plik JSON zawierający tablicę definicji modelu i opcjonalne metadane. Schemat jest zgodny ze standardową konwencją schematu JSON i jest przeznaczony zarówno do odczytania przez człowieka, jak i analizy maszyn.

Wykaz obsługuje dwa typy dystrybucji modeli:

• Modele oparte na plikach: Modele dystrybuowane jako pojedyncze pliki (modele ONNX, konfiguracje itp.)
• Modele oparte na pakietach: modele dystrybuowane jako pakiety systemu Windows (MSIX)

Struktura katalogu głównego

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

Właściwości katalogu głównego

Struktura obiektu modelu

Każdy model w tablicy models ma następującą 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"
    }
  ]
}

Właściwości modelu

Uwaga: model musi mieć wartość files OR packages, ale nie obie.

Dostawcy wykonywania

Pole executionProviders jest tablicą obiektów dostawcy wykonywania. Każdy obiekt dostawcy wykonywania musi mieć co najmniej name właściwość:

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

Zobacz stronę Obsługiwane dostawcy wykonywania w dokumentacji uczenia maszynowego systemu Windows, aby uzyskać pełną listę wszystkich dostępnych nazw dostawców wykonywania.

Obiekt pliku

Pliki są używane do dystrybucji poszczególnych składników modelu (pliki ONNX, konfiguracje itp.):

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

Uwaga: jeśli uri nie zostanie określony, identyfikator URI pliku jest konstruowany z właściwości podstawowej uri modelu.

Obiekt pakietu

Pakiety są używane do dystrybucji modeli jako pakietów lub aplikacji systemu Windows:

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

Metody dystrybucji

Wykaz obsługuje kilka metod dystrybucji:

Dystrybucja oparta na plikach:

• Bezpośrednie pobieranie https
• Pliki hostowane w usłudze GitHub, na platformie Azure lub na innych serwerach internetowych
• Pliki modelu (), pliki konfiguracji (.onnx.json) i zasoby pomocnicze

Dystrybucja oparta na pakietach:

• Pobieranie pakietów bezpośrednich za pośrednictwem protokołu HTTPS
• Lokalne ścieżki plików dla pakietów
• Pakiety MSIX

Kompletne przykłady

Przykład modelu opartego na plikach

Oto przykładowy wykaz z modelami opartymi na plikach:

{
  "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"
        }
      ]
    }
  ]
}

Przykład modelu opartego na pakietach

Oto przykładowy wykaz z modelami opartymi na pakietach:

{
  "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"
        }
      ]
    }
  ]
}

Weryfikacja schematu

Katalog modeli uczenia maszynowego systemu Windows jest zgodny ze specyfikacją schematu JSON (wersja robocza 2020-12). Możesz zweryfikować pliki wykazu względem oficjalnego schematu, aby zapewnić zgodność.

Reguły walidacji kluczy

1. Wymagane pola: każdy model musi mieć idwartości , , nameversion, publisher, executionProvidersilicense
2. Dystrybucja wyłączna: modele muszą określać wartość files OR packages, ale nie obie
3. Format SHA256: Wszystkie skróty SHA256 muszą mieć dokładnie 64 znaki szesnastkowe
4. Dostawcy wykonywania: muszą być obiektami z co najmniej właściwością name
5. Format identyfikatora URI: Wszystkie identyfikatory URI muszą być prawidłowo sformatowane zgodnie z RFC 3986
6. Integralność pakietu HTTPS: Pobieranie pakietów za pośrednictwem protokołu HTTPS musi zawierać skróty SHA256 na potrzeby weryfikacji integralności

Typowe błędy walidacji

• Brak wymaganych pól: Upewnij się, że wszystkie wymagane właściwości są obecne
• Nieprawidłowy algorytm SHA256: Sprawdź, czy wartości skrótu mają dokładnie 64 znaki szesnastkowe
• Rozkład mieszany: nie określaj zarówno modelu, jak files i packages dla tego samego modelu
• Nieprawidłowe identyfikatory URI: Sprawdź, czy wszystkie identyfikatory URI są prawidłowo sformatowane i dostępne
• Brak sha256 dla pakietów HTTPS: pobieranie pakietów HTTPS wymaga weryfikacji integralności

Tworzenie katalogu

Krok 1. Wybieranie metody dystrybucji

Użyj dystrybucji opartej na plikach, gdy:

• Modele są standardowymi plikami ONNX z pomocniczymi aktywami
• Masz hosting internetowy dla plików modelu
• Chcesz pobrać proste pliki HTTPS
• Modele są stosunkowo małe (< 1 GB na plik)

Użyj dystrybucji opartej na pakietach, gdy:

• Modele wymagają integracji systemu
• Modele obejmują dostawców wykonywania lub zależności
• Potrzebne są funkcje zarządzania pakietami systemu Windows
• Chcesz dystrybuować za pośrednictwem pakietów MSIX

Krok 2. Tworzenie struktury modeli

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

Krok 3. Dodawanie szczegółów dystrybucji

W przypadku modeli opartych na plikach:

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

W przypadku modeli opartych na pakietach:

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

Krok 4. Testowanie katalogu

1. Weryfikowanie składni JSON przy użyciu modułu sprawdzania poprawności JSON
2. Sprawdź, czy wszystkie identyfikatory URI są dostępne i zwracają poprawną zawartość
3. Sprawdź skróty SHA256 pasują do rzeczywistej zawartości pliku
4. Testowanie pobierania modelu przy użyciu interfejsów API wykazu modeli uczenia maszynowego systemu Windows

Najlepsze rozwiązania

1. Użyj semantycznego przechowywania wersji: postępuj zgodnie z semantycznym przechowywaniem wersji (np. "1.2.3") dla version pola
2. Podaj dokładne skróty SHA256: Zawsze uwzględniaj poprawne skróty SHA256 na potrzeby weryfikacji integralności
3. Spójne nazewnictwo: używaj spójnych konwencji nazewnictwa dla identyfikatorów i nazw w różnych wersjach modelu
4. Jasne opisy: Napisz przydatne opisy, które wyjaśniają możliwości modelu i przypadki użycia
5. Odpowiednie licencjonowanie: zawsze zawierają pełne informacje o licencji (typ, identyfikator URI i tekst)
6. Dostępność testowa: upewnij się, że wszystkie identyfikatory URI są dostępne i zwracają oczekiwaną zawartość
7. Zgodność dostawcy wykonywania: upewnij się, że dostawcy wykonywania są zgodni z docelowymi możliwościami sprzętowymi
8. Grupowanie logiczne: użyj pola nazwy do grupowania powiązanych wariantów modelu (różne wersje EP tego samego modelu podstawowego)
9. Organizacja plików: Zachowaj powiązane pliki razem i używaj opisowych nazw plików
10. Zabezpieczenia: użyj protokołu HTTPS dla wszystkich plików do pobrania i dołącz weryfikację SHA256

Zagadnienia dotyczące hostingu

W przypadku hostowania wykazu modeli:

1. Wymagany protokół HTTPS: zawsze obsługuje katalogi i modele za pośrednictwem protokołu HTTPS
2. Nagłówki CORS: konfigurowanie odpowiednich nagłówków CORS na potrzeby dostępu między źródłami
3. Typ zawartości: obsługa kodu JSON wykazu z application/json typem zawartości
4. Nagłówki pamięci podręcznej: ustaw odpowiednie nagłówki pamięci podręcznej pod kątem wydajności
5. Uwierzytelnianie: obsługa standardowego uwierzytelniania HTTP, jeśli jest to wymagane

Schemat JSON

Poniżej przedstawiono schemat JSON, który może służyć do weryfikacji ładunku 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": [ "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)"
        }
      }
    }
  }
}

Dalsze kroki

• Dowiedz się więcej o wykazie modeli — omówienie
• Postępuj zgodnie z przewodnikiem Wprowadzenie
• Zapoznaj się z dokumentacją usługi Windows ML