Referencia del esquema de origen del catálogo de modelos de Windows ML

En esta página se proporciona documentación de referencia para el esquema JSON usado por el origen del catálogo de modelos de Windows ML para definir orígenes de catálogo de modelos. Los orígenes del catálogo de modelos son archivos JSON que describen los modelos de IA disponibles, su compatibilidad e información de descarga.

El archivo de origen del catálogo de modelos se puede hospedar en línea en https:// direcciones URL o se puede hacer referencia a él como un archivo local de la aplicación.

Información general del esquema

Un catálogo de modelos es un archivo JSON que contiene una matriz de definiciones de modelo y metadatos opcionales. El esquema sigue las convenciones de esquema JSON estándar y está diseñada para ser legible y analizable por máquina.

El catálogo admite dos tipos de distribución de modelos:

Modelos basados en archivos: modelos distribuidos como archivos individuales (modelos ONNX, configuraciones, etc.)
Modelos basados en paquetes: modelos distribuidos como paquetes de Windows a través de la Tienda u otros administradores de paquetes

Estructura del catálogo raíz

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

Propiedades raíz

Propiedad	Tipo	Obligatorio	Description
`base`	string (URI)	Sí	Dirección URL de la documentación de referencia de la API de catálogo
`models`	array	Sí	Matriz de definiciones de modelo

Estructura de objetos de modelo

Cada modelo de la models matriz sigue esta estructura:

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

Propiedades del modelo

Propiedad	Tipo	Obligatorio	Description
`id`	cuerda / cadena	Sí	Identificador único para este modelo específico
`alias`	cuerda / cadena	No	Nombre de alias corto para el modelo
`name`	cuerda / cadena	Sí	Nombre completo del modelo
`version`	cuerda / cadena	Sí	Número de versión del modelo
`modelType`	cuerda / cadena	No	Tipo de modelo (actualmente solo se admite "ONNX")
`publisher`	cuerda / cadena	Sí	Publicador u organización que creó el modelo
`executionProviders`	cuerda / cadena	Sí	Lista separada por comas de proveedores de ejecución admitidos por el modelo
`description`	cuerda / cadena	No	Descripción detallada del modelo
`modelSizeBytes`	entero	No	Tamaño del modelo en bytes (mínimo: 0)
`license`	cuerda / cadena	Sí	Tipo de licencia (por ejemplo, "MIT", "BSD", "Apache")
`licenseUri`	cuerda / cadena	Sí	URI del documento de licencia
`licenseText`	cuerda / cadena	No	Contenido de texto de la licencia
`uri`	cuerda / cadena	No	URI base al que se puede acceder al modelo
`files`	array	Condicional*	Matriz de archivos asociados al modelo
`packages`	array	Condicional*	Matriz de paquetes necesarios para el modelo

Nota: Un modelo debe tener files or, packagespero no ambos.

Proveedores de ejecución

El executionProviders campo contiene una lista separada por comas de nombres de proveedor de ejecución:

"executionProviders": "CPUExecutionProvider,DmlExecutionProvider"

Nombres comunes del proveedor de ejecución:

Nombre del proveedor	Description
`CPUExecutionProvider`	Ejecución de CPU (siempre compatible)
`QNNExecutionProvider`	Qualcomm AI Engine (NPU)
`OpenVINOExecutionProvider`	Aceleración de Intel OpenVINO
`DmlExecutionProvider`	DirectML (aceleración de GPU)

File (objeto)

Los archivos se usan para distribuir componentes de modelo individuales (archivos ONNX, configuraciones, etc.):

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

Propiedad	Tipo	Obligatorio	Description
`name`	cuerda / cadena	Sí	Nombre del archivo
`uri`	cuerda / cadena	No	URI donde se puede descargar el archivo
`sha256`	cuerda / cadena	Sí	Hash SHA256 (cadena hexadecimal de 64 caracteres) para la comprobación de integridad

Nota: Si uri no se especifica, el URI del archivo se construye a partir de la propiedad base uri del modelo.

Package (objeto)

Los paquetes se usan para distribuir modelos como paquetes o aplicaciones de Windows:

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

Propiedad	Tipo	Obligatorio	Description
`packageFamilyName`	cuerda / cadena	Sí	Identificador de nombre de familia del paquete de Windows
`uri`	cuerda / cadena	Sí	URI donde se puede obtener el paquete
`sha256`	cuerda / cadena	Condicional*	Hash SHA256 para la comprobación de integridad

Nota: sha256 es necesario para los URI HTTPS, pero opcional para otros esquemas de URI (como ms-windows-store://).

Métodos de distribución

El catálogo admite varios métodos de distribución:

Distribución basada en archivos:

Descargas de HTTPS directas
Archivos hospedados en GitHub, Azure u otros servidores web
Archivos de modelo (.onnx), archivos de configuración (.json) y recursos auxiliares

Distribución basada en paquetes:

Paquetes de Microsoft Store (ms-windows-store:// URI)
Descargas directas de paquetes a través de HTTPS
Paquetes MSIX/APPX y paquetes individuales

Ejemplos completos

Ejemplo de modelo basado en archivos

Este es un catálogo de ejemplo con modelos basados en archivos:

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

Ejemplo de modelo basado en paquetes

Este es un catálogo de ejemplo con modelos basados en paquetes:

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

Validación de esquema

El catálogo de modelos de Windows ML sigue la especificación de esquema JSON (borrador 2020-12). Puede validar los archivos de catálogo con el esquema oficial para garantizar la compatibilidad.

Reglas de validación de claves

Campos obligatorios: cada modelo debe tener id, name, version, publisher, executionProvidersy license
Distribución exclusiva: los modelos deben especificar OR filespackages, pero no ambos
Formato SHA256: todos los hash SHA256 deben tener exactamente 64 caracteres hexadecimales
Proveedores de ejecución: debe ser objetos con al menos una name propiedad
Formato de URI: todos los URI deben tener el formato correcto según RFC 3986
Requisitos https: las descargas de paquetes a través de HTTPS deben incluir hashES SHA256

Errores comunes de validación

Campos obligatorios que faltan: asegúrese de que están presentes todas las propiedades necesarias
SHA256 no válido: compruebe que los valores hash son exactamente 64 caracteres hexadecimales
Distribución mixta: no especifique ni filespackages para el mismo modelo
URI no válidos: compruebe que todos los URI tienen el formato correcto y son accesibles
Falta SHA256 para paquetes HTTPS: las descargas de paquetes HTTPS requieren comprobación de integridad

Creación del catálogo

Paso 1: Elegir el método de distribución

Use la distribución basada en archivos cuando:

Los modelos son archivos ONNX estándar con recursos auxiliares
Tiene hospedaje web para archivos de modelo
Quiere descargas DE HTTPS sencillas
Los modelos son relativamente pequeños (< 1 GB por archivo)

Use la distribución basada en paquetes cuando:

Los modelos requieren integración del sistema
Estás distribuyendo a través de Microsoft Store
Los modelos incluyen proveedores de ejecución o dependencias
Necesita características de administración de paquetes de Windows

Paso 2: Estructurar los modelos

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

Paso 3: Agregar detalles de distribución

Para los modelos basados en archivos:

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

Para los modelos basados en paquetes:

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

Paso 4: Probar el catálogo

Validación de la sintaxis JSON mediante un validador JSON
Compruebe que todos los URI son accesibles y devuelven el contenido correcto.
Compruebe que los hash SHA256 coinciden con el contenido real del archivo.
Descarga de modelos de prueba mediante las API del catálogo de modelos de Windows ML

procedimientos recomendados

Usar versiones semánticas: siga el control de versiones semánticos (por ejemplo, "1.2.3") para el version campo
Proporcionar hash SHA256 preciso: incluya siempre los hash SHA256 correctos para la comprobación de integridad.
Nomenclatura coherente: usar convenciones de nomenclatura coherentes para alias e identificadores en las versiones del modelo
Descripciones claras: escriba descripciones útiles que expliquen las funcionalidades del modelo y los casos de uso.
Licencias adecuadas: incluya siempre información de licencia completa (tipo, URI y texto)
Accesibilidad de prueba: asegúrese de que todos los URI sean accesibles y devuelvan el contenido esperado.
Compatibilidad del proveedor de ejecución: asegúrese de que los proveedores de ejecución coinciden con las funcionalidades de hardware de destino.
Agrupación lógica: use alias para agrupar variantes de modelo relacionadas (diferentes versiones EP del mismo modelo base)
Organización de archivos: mantener los archivos relacionados juntos y usar nombres de archivo descriptivos
Seguridad: use HTTPS para todas las descargas de archivos e incluya la comprobación SHA256.

Consideraciones de hospedaje

Al hospedar un catálogo de modelos:

HTTPS requerido: siempre atiende catálogos y modelos a través de HTTPS
Encabezados CORS: configurar los encabezados CORS adecuados para el acceso entre orígenes
Content-Type: Servir JSON de catálogo con application/json tipo de contenido
Encabezados de caché: establezca los encabezados de caché adecuados para el rendimiento.
Autenticación: admite la autenticación HTTP estándar si es necesario.

Esquema JSON

A continuación se muestra el esquema JSON que se puede usar para la validación de la carga DE 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" ]
      }
    }
  }
}

Pasos siguientes

Información general sobre el catálogo de modelos
Siga la guía De introducción.
Exploración de la documentación de Windows ML

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-10-11