Справочник по исходной схеме каталога моделей Машинного обучения Windows

Эта страница содержит справочную документацию по схеме JSON, используемой источником каталога моделей Windows ML для определения источников каталога моделей. Источники каталога моделей — это JSON-файлы, описывающие доступные модели ИИ, их совместимость и скачивание сведений.

Исходный файл каталога моделей можно размещать в Интернете по https:// URL-адресам или ссылаться как на локальный файл из приложения.

Общее представление схемы

Каталог моделей — это JSON-файл, содержащий массив определений моделей и необязательные метаданные. Схема соответствует стандартным соглашениям схемы JSON и предназначена как для чтения, так и для машинного анализа.

Каталог поддерживает два типа распределения моделей:

Модели на основе файлов: модели, распределенные в виде отдельных файлов (модели ONNX, конфигурации и т. д.)
Модели на основе пакетов: модели, распределенные в виде пакетов Windows через Магазин или другие диспетчеры пакетов

Структура корневого каталога

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

Корневые свойства

Недвижимость	Тип	Обязательно	Description
`models`	массив	Да	Массив определений моделей

Структура объектов модели

Каждая модель в массиве 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`	массив	Условный*	Массив файлов, связанных с моделью
`packages`	массив	Условный*	Массив пакетов, необходимых для модели

Примечание. Модель должна иметь либо files ИЛИ 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-символьная шестнадцатеричная строка) для проверки целостности и отмены дупирования идентичных моделей

Примечание. Если uri не указано, URI файла создается из базового uri свойства модели.

Объект package

Пакеты используются для распространения моделей в виде пакетов или приложений Windows:

{
  "packageFamilyName": "Microsoft.Example_8wekyb3d8bbwe",
  "uri": "ms-windows-store://pdp/?ProductId=9EXAMPLE123",
  "sha256": "a1b2c3d4e5f6789..."
}

Недвижимость	Тип	Обязательно	Description
`packageFamilyName`	струна	Да	Идентификатор имени семейства пакетов Windows
`uri`	струна	Да	URI, в котором можно получить пакет
`sha256`	струна	Условный*	Хэш SHA256 для проверки целостности

Примечание.sha256 Требуется для URI HTTPS, но необязательно для других схем URI (напримерms-windows-store://).

Методы распространения

Каталог поддерживает несколько методов распространения:

Распределение на основе файлов:

Прямые загрузки HTTPS
Файлы, размещенные на GitHub, Azure или других веб-серверах
Файлы модели (), файлы конфигурации (.onnx.json) и вспомогательные ресурсы

Распределение на основе пакетов:

Пакеты Microsoft Store (ms-windows-store:// URI)
Прямые загрузки пакетов через HTTPS
Пакеты MSIX/APPX и отдельные пакеты

Полные примеры

Пример модели на основе файлов

Ниже приведен пример каталога с моделями на основе файлов:

{
  "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-store-model-cpu",
      "name": "example-store-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": "ms-windows-store://pdp/?ProductId=9NEXAMPLE123"
        }
      ]
    }
  ]
}

Проверка схемы

Каталог моделей Машинного обучения Windows следует спецификации схемы JSON (черновик 2020-12). Вы можете проверить файлы каталога на основе официальной схемы, чтобы обеспечить совместимость.

Правила проверки ключей

Обязательные поля: каждая модель должна иметь id, name, version, publisher, executionProvidersи license
Эксклюзивное распределение: модели должны указывать либо files OR packages, но не оба
Формат SHA256: все хэши SHA256 должны иметь ровно 64 шестнадцатеричных символов.
Поставщики выполнения: должны быть объектами по крайней мере свойством name
Формат URI: все URI должны быть правильно отформатированы в соответствии с RFC 3986
Требования к HTTPS: скачивание пакетов через HTTPS должно включать хэши SHA256

Распространенные ошибки проверки

Отсутствующие обязательные поля: убедитесь, что присутствуют все необходимые свойства
Недопустимое значение SHA256: убедитесь, что хэш-значения — это всего 64 шестнадцатеричных символов.
Смешанное распределение: не указывайте оба files и packages для одной модели
Недопустимые URI: убедитесь, что все URI правильно отформатированы и доступны
Отсутствуют SHA256 для пакетов HTTPS: загрузка пакетов HTTPS требует проверки целостности

Создание каталога

Шаг 1. Выбор метода распространения

Используйте распределение на основе файлов, когда:

Ваши модели являются стандартными файлами ONNX с вспомогательными ресурсами
У вас есть веб-размещение для файлов моделей
Требуется простое скачивание HTTPS
Модели относительно малы (< 1 ГБ на файл)

Используйте распределение на основе пакетов, когда:

Для моделей требуется интеграция системы
Вы распространяетесь через Microsoft Store
Модели включают поставщиков выполнения или зависимости
Вам нужны функции управления пакетами Windows

Шаг 2. Структура моделей

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

Шаг 3. Добавление сведений о дистрибутиве

Для моделей на основе файлов:

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

Для моделей на основе пакетов:

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

Шаг 4. Тестирование каталога

Проверка синтаксиса JSON с помощью проверяющего элемента JSON
Убедитесь, что все URI доступны и возвращают правильное содержимое
Проверка хэшей SHA256 соответствует фактическому содержимому файла
Тестовая модель загрузки с помощью API каталога моделей Windows ML

Лучшие практики

Используйте семантическое управление версиями: выполните семантические версии (например, "1.2.3") для version поля
Предоставление точных хэшей SHA256: всегда включать правильные хэши SHA256 для проверки целостности
Согласованное именование. Используйте согласованные соглашения об именовании для идентификаторов и имен в разных версиях модели.
Четкие описания: написание полезных описаний, объясняющих возможности модели и варианты использования
Надлежащее лицензирование. Всегда включать полные сведения о лицензии (тип, URI и текст)
Проверка специальных возможностей. Убедитесь, что все URI доступны и возвращают ожидаемое содержимое.
Совместимость поставщика выполнения. Убедитесь, что поставщики выполнения соответствуют целевым возможностям оборудования
Логическое группирование: используйте поле имени для группирования связанных вариантов модели (разные версии EP одной базовой модели)
Организация файлов: держать связанные файлы вместе и использовать описательные имена файлов
Безопасность: использование HTTPS для всех скачиваемого файла и включение проверки SHA256

Схема 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"
        },
        "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)"
        }
      }
    }
  }
}

Дальнейшие шаги

Общие сведения о каталоге моделей
Следуйте руководству по началу работы
Ознакомьтесь с документацией по Windows ML

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-11-12