Referência do 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 os 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.

Descriçã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 padrão do esquema JSON e foi projetado para ser legível por humanos e analisado por máquina.

O catálogo suporta dois tipos de distribuição de modelo:

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

Estrutura do catálogo raiz

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

Propriedades da raiz

Estrutura do objeto do 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

Nota: Um modelo deve ter files OU packages, mas não ambos.

Fornecedores 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 a página Provedores de execução suportados em documentos de ML do Windows para obter uma lista abrangente de todos os nomes de provedores 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"
}

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

Objeto do pacote

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..."
}

Métodos de distribuição

O catálogo suporta vários métodos de distribuição:

Distribuição baseada em ficheiros:

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

Distribuição baseada em pacotes:

• Downloads diretos de pacotes via HTTPS
• Caminhos de ficheiros locais 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 exemplo de catálogo com modelos baseados em pacotes:

{
  "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 esquemas

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 em relação ao esquema oficial para garantir a compatibilidade.

Principais regras de validação

1. Campos obrigatórios: Cada modelo deve ter id, name, version, publisher, executionProviderse license
2. Distribuição exclusiva: Os modelos devem especificar files OU packages, mas não ambos
3. Formato SHA256: Todos os hashes SHA256 devem ter exatamente 64 caracteres hexadecimais
4. Provedores de execução: Devem ser objetos com pelo menos uma name propriedade
5. Formato URI: Todos os URIs devem ser formatados corretamente de acordo com a RFC 3986
6. Integridade do pacote HTTPS: Os downloads de pacotes via HTTPS devem incluir hashes SHA256 para verificação de integridade

Erros comuns de validação

• Campos obrigató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álidos: verifique se todos os URIs estão formatados e acessíveis corretamente
• SHA256 ausente para pacotes HTTPS: downloads de pacotes HTTPS exigem verificação de integridade

Criando seu catálogo

Etapa 1: Escolha 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ê quer downloads HTTPS simples
• Os modelos são relativamente pequenos (< 1GB por ficheiro)

Use a distribuição baseada em pacote quando:

• Os seus modelos requerem integração de sistemas
• Os modelos incluem provedores de execução ou dependências
• Você precisa de recursos de gerenciamento de pacotes do Windows
• Quer distribuir através de pacotes MSIX

Passo 2: Estruture os 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 ficheiros:

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

Para modelos baseados em pacotes:

"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 sintaxe JSON usando um validador JSON
2. Verifique se todos os URIs estão acessíveis e retornam o conteúdo correto
3. Verifique se os hashes SHA256 correspondem ao conteúdo real do arquivo
4. Download do modelo de teste usando as APIs do Catálogo de Modelos do Windows ML

Melhores práticas

1. Usar versionamento semântico: Siga o versionamento 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 em versões de modelo
4. Descrições claras: escreva descrições úteis que expliquem os recursos do modelo e os casos de uso
5. Licenciamento adequado: inclua sempre informações completas sobre a licença (tipo, URI e texto)
6. Testar a acessibilidade: verifique se todos os URIs estão acessíveis e retornam o conteúdo esperado
7. Compatibilidade do provedor de execução: garanta que os provedores de execução correspondam aos recursos de hardware de destino
8. Agrupamento lógico: use o campo de nome para agrupar variantes de modelo relacionadas (diferentes versões EP 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 arquivos e inclua a verificação SHA256

Considerações sobre hospedagem

Ao hospedar um catálogo de modelos:

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

Esquema JSON

A seguir está o esquema JSON que pode ser usado para validação de sua carga JSON útil.

{
  "$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óximos passos

• Saiba mais sobre a visão geral do Catálogo de modelos
• Siga o Guia de introdução
• Explore a documentação do Windows ML