Compartilhar via

Referência de esquema de origem do catálogo de modelos do Windows ML

Esta página fornece documentação de referência para o esquema JSON usado pela Origem do Catálogo de Modelos do Windows ML para definir fontes de catálogo de modelos. As fontes do catálogo de modelos são arquivos JSON que descrevem modelos de IA disponíveis, sua compatibilidade e informações de download.

O arquivo de origem do catálogo de modelos pode ser hospedado online em https:// URLs ou referenciado como um arquivo local do seu aplicativo.

Visão geral do esquema

Um catálogo de modelos é um arquivo JSON que contém uma matriz de definições de modelo e metadados opcionais. O esquema segue as convenções de esquema JSON padrão e foi projetado para ser legível por humanos e analisável por máquina.

O catálogo dá suporte a dois tipos de distribuição de modelo:

  • Modelos baseados em arquivo: modelos distribuídos como arquivos individuais (modelos ONNX, configurações etc.)
  • Modelos baseados em pacote: modelos distribuídos como pacotes do Windows (MSIX)

Estrutura do catálogo raiz

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

Propriedades raiz

Propriedade Tipo Obrigatório Description
models matriz Yes Matriz de definições de modelo

Estrutura de objeto de modelo

Cada modelo na models matriz segue esta estrutura:

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

Propriedades do modelo

Propriedade Tipo Obrigatório Description
id cadeia Yes Identificador exclusivo no catálogo para este modelo específico
name cadeia Yes Nome comum do modelo (pode ser compartilhado entre variantes)
version cadeia Yes Número da versão do modelo
publisher cadeia Yes Publicador ou organização que criou o modelo
executionProviders matriz Yes Matriz de objetos do provedor de execução com suporte no modelo
modelSizeBytes inteiro Não Tamanho do modelo em bytes (mínimo: 0)
license cadeia Yes Tipo de licença (por exemplo, "MIT", "BSD", "Apache")
licenseUri cadeia Não URI para o documento de licença
licenseText cadeia Não Conteúdo de texto da licença
uri cadeia Não URI base em que o modelo pode ser acessado
files matriz Condicional Matriz de arquivos associados ao modelo
packages matriz Condicional Matriz de pacotes necessários para o modelo

Observação: um modelo deve ter files OR packages, mas não ambos.

Provedores de execução

O executionProviders campo é uma matriz de objetos do provedor de execução. Cada objeto do provedor de execução deve ter pelo menos uma name propriedade:

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

Consulte os provedores de execução com suporte na página de documentos do Windows ML para obter uma lista abrangente de todos os nomes de provedor de execução disponíveis.

Objeto de arquivo

Os arquivos são usados para distribuir componentes de modelo individuais (arquivos ONNX, configurações etc.):

{
  "name": "model.onnx",
  "uri": "https://models.example.com/model.onnx",
  "sha256": "d7f93e79ba1284a3ff2b4cea317d79f3e98e64acfce725ad5f4e8197864aef73"
}
Propriedade Tipo Obrigatório Description
name cadeia Yes Nome do arquivo
uri cadeia Não URI em que o arquivo pode ser baixado
sha256 cadeia Yes Hash SHA256 (cadeia de caracteres hexadecedora de 64 caracteres) para verificação de integridade e eliminação de duplicação de modelos idênticos

Observação: se uri não for especificado, o URI do arquivo será construído a partir da propriedade base uri do modelo.

Objeto Package

Os pacotes são usados para distribuir modelos como pacotes ou aplicativos do Windows:

{
  "packageFamilyName": "Microsoft.Example_8wekyb3d8bbwe",
  "uri": "https://example.com/packages/model.msix",
  "sha256": "a1b2c3d4e5f6789..."
}
Propriedade Tipo Obrigatório Description
packageFamilyName cadeia Yes Identificador de nome da família de pacotes do Windows
uri cadeia Yes URI em que o pacote pode ser obtido (HTTPS ou caminho de arquivo local)
sha256 cadeia Condicional Hash SHA256 para verificação de integridade (necessário para URIs HTTPS)

Métodos de distribuição

O catálogo dá suporte a vários métodos de distribuição:

Distribuição baseada em arquivo:

  • Downloads de HTTPS diretos
  • Arquivos hospedados no GitHub, no Azure ou em outros servidores Web
  • Arquivos de modelo (.onnx), arquivos de configuração (.json) e ativos de suporte

Distribuição baseada em pacote:

  • Downloads de pacote direto via HTTPS
  • Caminhos de arquivo local para pacotes
  • Pacotes MSIX

Exemplos completos

Exemplo de modelo baseado em arquivo

Aqui está um catálogo de exemplo com modelos baseados em arquivo:

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

Exemplo de modelo baseado em pacote

Aqui está um catálogo de exemplo com modelos baseados em pacote:

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

Validação de esquema

O Catálogo de Modelos do Windows ML segue a especificação do Esquema JSON (rascunho 2020-12). Você pode validar seus arquivos de catálogo no esquema oficial para garantir a compatibilidade.

Regras de validação de chave

  1. Campos necessários: cada modelo deve terid, name, , version, publishere executionProviderslicense
  2. Distribuição exclusiva: os modelos devem especificar files OR packages, mas não ambos
  3. Formato SHA256: todos os hashes SHA256 devem ter exatamente 64 caracteres hexadecimal
  4. Provedores de execução: devem ser objetos com pelo menos uma name propriedade
  5. Formato de URI: todas as URIs devem ser formatadas corretamente de acordo com o RFC 3986
  6. Integridade do pacote HTTPS: downloads de pacote via HTTPS devem incluir hashes SHA256 para verificação de integridade

Erros comuns de validação

  • Campos necessários ausentes: verifique se todas as propriedades necessárias estão presentes
  • SHA256 inválido: verifique se os valores de hash são exatamente 64 caracteres hexadecimais
  • Distribuição mista: não especifique ambos files e packages para o mesmo modelo
  • URIs inválidas: verifique se todas as URIs estão formatadas corretamente e acessíveis
  • SHA256 ausente para pacotes HTTPS: downloads de pacote HTTPS exigem verificação de integridade

Criando seu catálogo

Etapa 1: Escolher o método de distribuição

Use a distribuição baseada em arquivo quando:

  • Seus modelos são arquivos ONNX padrão com ativos de suporte
  • Você tem hospedagem na Web para arquivos de modelo
  • Você deseja downloads HTTPS simples
  • Os modelos são relativamente pequenos (< 1 GB por arquivo)

Use a distribuição baseada em pacote quando:

  • Seus modelos exigem integração do sistema
  • Os modelos incluem provedores de execução ou dependências
  • Você precisa de recursos de gerenciamento de pacotes do Windows
  • Você deseja distribuir por meio de pacotes MSIX

Etapa 2: Estruturar seus modelos

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

Etapa 3: Adicionar detalhes de distribuição

Para modelos baseados em arquivo:

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

Para modelos baseados em pacote:

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

Etapa 4: Testar seu catálogo

  1. Validar a sintaxe JSON usando um validador JSON
  2. Verifique se todas as URIs estão acessíveis e retorne o conteúdo correto
  3. Verifique se os hashes SHA256 correspondem ao conteúdo real do arquivo
  4. Testar o download do modelo usando as APIs do Catálogo de Modelos do Windows ML

Práticas recomendadas

  1. Usar controle de versão semântico: siga o controle de versão semântico (por exemplo, "1.2.3") para o version campo
  2. Forneça hashes SHA256 precisos: inclua sempre hashes SHA256 corretos para verificação de integridade
  3. Nomenclatura consistente: use convenções de nomenclatura consistentes para IDs e nomes entre versões de modelo
  4. Descrições claras: escrever descrições úteis que explicam recursos de modelo e casos de uso
  5. Licenciamento adequado: inclua sempre informações de licença completas (tipo, URI e texto)
  6. Testar a acessibilidade: verifique se todas as URIs estão acessíveis e retorne o conteúdo esperado
  7. Compatibilidade do provedor de execução: garantir que os provedores de execução correspondam aos recursos de hardware de destino
  8. Agrupamento lógico: usar o campo de nome para agrupar variantes de modelo relacionadas (versões ep diferentes do mesmo modelo base)
  9. Organização de arquivos: mantenha os arquivos relacionados juntos e use nomes de arquivo descritivos
  10. Segurança: use HTTPS para todos os downloads de arquivo e inclua a verificação SHA256

Considerações sobre hospedagem

Ao hospedar um catálogo de modelos:

  1. HTTPS necessário: sempre servir catálogos e modelos por HTTPS
  2. Cabeçalhos CORS: configurar cabeçalhos CORS apropriados para acesso entre origens
  3. Tipo de Conteúdo: Servir JSON do catálogo com application/json tipo de conteúdo
  4. Cabeçalhos de cache: definir cabeçalhos de cache apropriados para desempenho
  5. Autenticação: dar suporte à autenticação HTTP padrão, se necessário

Esquema JSON

Veja a seguir o esquema JSON que pode ser usado para validação do conteúdo 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)"
        }
      }
    }
  }
}

Próximas etapas

  • Last updated on