Windows ML モデルカタログソーススキーマリファレンス

このページでは、モデルカタログソースを定義するために Windows ML モデルカタログソースによって使用される JSON スキーマのリファレンスドキュメントを提供します。モデルカタログソースは、使用可能な AI モデルとその互換性、ダウンロード情報を記述する JSON ファイルです。

モデルカタログソースファイルは、 https:// URL でオンラインでホストすることも、アプリからローカルファイルとして参照することもできます。

スキーマの概要

モデルカタログは、モデル定義とオプションのメタデータの配列を含む JSON ファイルです。スキーマは標準の JSON スキーマ規則に従っており、人間が判読でき、コンピューターで解析できるように設計されています。

カタログでは、次の 2 種類のモデル分布がサポートされています。

ファイルベースのモデル: 個々のファイルとして配布されるモデル (ONNX モデル、構成など)
パッケージベースのモデル: Windows パッケージとして配布されるモデル (MSIX)

ルートカタログ構造

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

ルートプロパティ

プロパティ	タイプ	必須	Description
`models`	アレイ	イエス	モデル定義の配列

Model オブジェクト構造

models配列内の各モデルは、次の構造に従います。

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

モデルのプロパティ

プロパティ	タイプ	必須	Description
`id`	文字列	イエス	この特定のモデルの一意のカタログ内識別子
`name`	文字列	イエス	モデルの共通名 (バリアント間で共有できます)
`version`	文字列	イエス	モデルのバージョン番号
`publisher`	文字列	イエス	モデルを作成した発行元または組織
`executionProviders`	アレイ	イエス	モデルでサポートされている実行プロバイダーオブジェクトの配列
`modelSizeBytes`	整数	いいえ	モデルのサイズ (バイト単位) (最小: 0)
`license`	文字列	イエス	ライセンスの種類 (例: "MIT"、"BSD"、"Apache")
`licenseUri`	文字列	いいえ	ライセンスドキュメントの URI
`licenseText`	文字列	いいえ	ライセンスのテキストコンテンツ
`uri`	文字列	いいえ	モデルにアクセスできるベース URI
`files`	アレイ	Conditional	モデルに関連付けられているファイルの配列
`packages`	アレイ	Conditional	モデルに必要なパッケージの配列

注: モデルには、 files OR packagesが必要ですが、両方を持つ必要はありません。

実行プロバイダー

executionProviders フィールドは、実行プロバイダーオブジェクトの配列です。各実行プロバイダーオブジェクトには、少なくとも name プロパティが必要です。

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

使用可能なすべての実行プロバイダー名の包括的な一覧については、Windows ML のサポートされている実行プロバイダーに関するドキュメントページを参照してください。

File オブジェクト

ファイルは、個々のモデルコンポーネント (ONNX ファイル、構成など) を配布するために使用されます。

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

プロパティ	タイプ	必須	Description
`name`	文字列	イエス	ファイルの名前
`uri`	文字列	いいえ	ファイルをダウンロードできる URI
`sha256`	文字列	イエス	整合性検証と同一モデルのデデュピングのための SHA256 ハッシュ (64 文字の 16 進文字列)

注: uri が指定されていない場合、ファイル URI はモデルの基本 uri プロパティから構築されます。

Package オブジェクト

パッケージは、モデルを Windows パッケージまたはアプリケーションとして配布するために使用されます。

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

プロパティ	タイプ	必須	Description
`packageFamilyName`	文字列	イエス	Windows パッケージファミリ名識別子
`uri`	文字列	イエス	パッケージを取得できる URI (HTTPS またはローカルファイルパス)
`sha256`	文字列	Conditional	整合性検証用の SHA256 ハッシュ (HTTPS URI に必要)

配布方法

カタログでは、いくつかの配布方法がサポートされています。

ファイルベースの配布:

HTTPS の直接ダウンロード
GitHub、Azure、またはその他の Web サーバーでホストされているファイル
モデルファイル (.onnx)、構成ファイル (.json)、およびサポート資産

パッケージベースの配布:

HTTPS を使用した直接パッケージのダウンロード
パッケージのローカルファイルパス
MSIX パッケージ

完全な例

ファイルベースのモデルの例

ファイルベースのモデルを含むカタログの例を次に示します。

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

パッケージベースのモデルの例

パッケージベースのモデルを含むカタログの例を次に示します。

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

スキーマの検証

Windows ML モデルカタログは、JSON スキーマ仕様 (ドラフト 2020-12) に従います。互換性を確保するために、公式スキーマに対してカタログファイルを検証できます。

キー検証規則

必須フィールド: すべてのモデルに id、 name、 version、 publisher、 executionProviders、および license
排他分散: モデルでは、 files OR packagesのいずれかを指定する必要がありますが、両方を指定することはできません
SHA256 形式: すべての SHA256 ハッシュは、64 桁の 16 進数文字である必要があります
実行プロバイダー: 少なくとも name プロパティを持つオブジェクトである必要があります
URI 形式: すべての URI は RFC 3986 に従って適切に書式設定する必要があります
HTTPS パッケージの整合性: HTTPS 経由のパッケージのダウンロードには、整合性検証のために SHA256 ハッシュを含める必要があります

一般的な検証エラー

必須フィールドがありません: すべての必須プロパティが存在することを確認する
SHA256 が無効です: ハッシュ値が 64 桁の 16 進文字であることを確認してください
混合分布: 同じモデルに対して files と packages の両方を指定しないでください
無効な URI: すべての URI が適切に書式設定され、アクセス可能であることを確認する
HTTPS パッケージに SHA256 がない: HTTPS パッケージのダウンロードには整合性検証が必要

カタログの作成

手順 1: 配布方法を選択する

次の場合は、ファイルベースの配布を使用します。

モデルは、サポート資産を含む標準の ONNX ファイルです
モデルファイルの Web ホスティングがある
単純な HTTPS ダウンロードが必要な場合
モデルは比較的小さい (ファイルあたり 1 GB < )

パッケージベースの配布は、次の場合に使用します。

モデルにシステム統合が必要
モデルには、実行プロバイダーまたは依存関係が含まれます
Windows パッケージ管理機能が必要です
MSIX パッケージを使用して配布する場合

手順 2: モデルを構成する

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

手順 3: 配布の詳細を追加する

ファイルベースのモデルの場合:

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

パッケージベースのモデルの場合:

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

手順 4: カタログをテストする

JSON 検証コントロールを使用して JSON 構文を検証する
すべての URI が アクセス可能であることを確認し、正しいコンテンツを返す
SHA256 ハッシュが実際の ファイルの内容と一致するかどうかを確認する
Windows ML モデルカタログ API を使用したテスト モデルのダウンロード

ベストプラクティス

セマンティックバージョン管理の使用: version フィールドのセマンティックバージョン管理 (例: "1.2.3") に従う
正確な SHA256 ハッシュを提供する: 整合性検証用の正しい SHA256 ハッシュを常に含める
一貫性のある名前付け: モデルバージョン間で ID と名前に一貫性のある名前付け規則を使用する
明確な説明: モデルの機能とユースケースについて説明する役立つ説明を記述する
適切なライセンス: 常に完全なライセンス情報 (種類、URI、テキスト) を含める
アクセシビリティのテスト: すべての URI がアクセス可能であることを確認し、期待されるコンテンツを返す
実行プロバイダーの互換性: 実行プロバイダーがターゲットハードウェア機能と一致していることを確認する
論理グループ化: 名前フィールドを使用して関連するモデルバリアントをグループ化する (同じ基本モデルの異なる EP バージョン)
ファイルの編成: 関連ファイルを一緒に保持し、わかりやすいファイル名を使用する
セキュリティ: すべてのファイルダウンロードに HTTPS を使用し、SHA256 検証を含める

ホスティングに関する考慮事項

モデルカタログをホストする場合:

HTTPS が必要: HTTPS 経由でカタログとモデルを常に提供する
CORS ヘッダー: クロスオリジンアクセス用に適切な CORS ヘッダーを構成する
Content-Type: application/json コンテンツタイプでカタログ JSON を提供する
キャッシュヘッダー: パフォーマンスのために適切なキャッシュヘッダーを設定する
認証: 必要に応じて標準の HTTP 認証をサポートする

JSON スキーマ

JSON ペイロードの検証に使用できる 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)"
        }
      }
    }
  }
}

次のステップ

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-01-06