Windows ML 모델 카탈로그 원본 스키마 참조

이 페이지에서는 Windows ML 모델 카탈로그 원본에서 모델 카탈로그 원본을 정의하는 데 사용하는 JSON 스키마에 대한 참조 설명서를 제공합니다. 모델 카탈로그 원본은 사용 가능한 AI 모델, 호환성 및 다운로드 정보를 설명하는 JSON 파일입니다.

모델 카탈로그 원본 파일은 URL에서 https:// 온라인으로 호스트되거나 앱에서 로컬 파일로 참조될 수 있습니다.

스키마 개요

모델 카탈로그는 모델 정의 및 선택적 메타데이터의 배열을 포함하는 JSON 파일입니다. 스키마는 표준 JSON 스키마 규칙을 따르며 사람이 읽을 수 있고 기계 구문 분석이 가능하도록 설계되었습니다.

카탈로그는 두 가지 유형의 모델 배포를 지원합니다.

파일 기반 모델: 개별 파일로 배포된 모델(ONNX 모델, 구성 등)
패키지 기반 모델: Windows 패키지로 배포된 모델(MSIX)

루트 카탈로그 구조

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

루트 속성

재산	유형	필수	Description
`models`	배열	Yes	모델 정의 배열

모델 개체 구조

배열의 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`	문자열	Yes	이 특정 모델에 대한 카탈로그 내 고유 식별자
`name`	문자열	Yes	모델의 일반 이름(변형 간에 공유할 수 있습니다).
`version`	문자열	Yes	모델 버전 번호
`publisher`	문자열	Yes	모델을 만든 게시자 또는 조직
`executionProviders`	배열	Yes	모델에서 지원하는 실행 공급자 개체의 배열
`modelSizeBytes`	integer	아니오	모델 크기(최소: 0)
`license`	문자열	Yes	라이선스 유형(예: "MIT", "BSD", "Apache")
`licenseUri`	문자열	아니오	라이선스 문서에 대한 URI
`licenseText`	문자열	아니오	라이선스의 텍스트 콘텐츠
`uri`	문자열	아니오	모델에 액세스할 수 있는 기본 URI
`files`	배열	Conditional	모델과 연결된 파일의 배열
`packages`	배열	Conditional	모델에 필요한 패키지 배열

참고: 모델에는 ORfiles이 packages 있어야 하지만 둘 다 있어야 합니다.

실행 공급자

executionProviders 필드는 실행 공급자 개체의 배열입니다. 각 실행 공급자 개체에는 적어도 속성이 있어야 합니다.name

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

사용 가능한 모든 실행 공급자 이름의 포괄적인 목록은 Windows ML 문서 페이지에서 지원되는 실행 공급자를 참조하세요.

파일 개체

파일은 개별 모델 구성 요소(ONNX 파일, 구성 등)를 배포하는 데 사용됩니다.

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

재산	유형	필수	Description
`name`	문자열	Yes	파일 이름
`uri`	문자열	아니오	파일을 다운로드할 수 있는 URI
`sha256`	문자열	Yes	동일한 모델의 무결성 확인 및 중복 제거를 위한 SHA256 해시(64자 16진수 문자열)

참고: 지정하지 않으면 uri 파일 URI는 모델의 기본 uri 속성에서 생성됩니다.

패키지 개체

패키지는 Windows 패키지 또는 애플리케이션으로 모델을 배포하는 데 사용됩니다.

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

재산	유형	필수	Description
`packageFamilyName`	문자열	Yes	Windows 패키지 패밀리 이름 식별자
`uri`	문자열	Yes	패키지를 가져올 수 있는 URI(HTTPS 또는 로컬 파일 경로)
`sha256`	문자열	Conditional	무결성 확인을 위한 SHA256 해시(HTTPS URI에 필요)

배포 방법

카탈로그는 다음과 같은 여러 배포 방법을 지원합니다.

파일 기반 배포:

직접 HTTPS 다운로드
GitHub, Azure 또는 기타 웹 서버에서 호스트되는 파일
모델 파일(.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, ,nameversion, publisherexecutionProviders및license
배타적 배포: 모델은 OR files중 하나를 packages 지정해야 하지만 둘 다 지정하지는 않아야 합니다.
SHA256 형식: 모든 SHA256 해시는 정확히 64개의 16진수 문자여야 합니다.
실행 공급자: 적어도 속성이 있는 name 개체여야 합니다.
URI 형식: RFC 3986에 따라 모든 URI의 형식을 올바르게 지정해야 합니다.
HTTPS 패키지 무결성: HTTPS를 통한 패키지 다운로드에는 무결성 확인을 위한 SHA256 해시가 포함되어야 합니다.

일반적인 유효성 검사 오류

필수 필드 누락: 모든 필수 속성이 있는지 확인
잘못된 SHA256: 해시 값이 정확히 6466진수 문자인지 확인합니다.
혼합 분포: 동일한 모델에 대해 둘 다 filespackages 지정하지 마세요.
잘못된 URI: 모든 URI의 형식이 올바르게 지정되고 액세스할 수 있는지 확인
누락된 HTTPS 패키지용 SHA256: HTTPS 패키지 다운로드에는 무결성 확인이 필요합니다.

카탈로그 만들기

1단계: 배포 방법 선택

다음과 같은 경우 파일 기반 배포를 사용합니다.

모델은 지원 자산이 있는 표준 ONNX 파일입니다.
모델 파일에 대한 웹 호스팅이 있습니다.
간단한 HTTPS 다운로드를 원합니다.
모델은 비교적 작습니다(< 파일당 1GB)

다음과 같은 경우 패키지 기반 배포를 사용합니다.

모델에 시스템 통합이 필요합니다.
모델에는 실행 공급자 또는 종속성이 포함됩니다.
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를 사용하여 모델 다운로드 테스트

모범 사례

의미 체계 버전 관리 사용: 필드에 대한 의미 체계 버전 관리(예: "1.2.3")를 version 따릅니다.
정확한 SHA256 해시 제공: 무결성 확인을 위해 항상 올바른 SHA256 해시 포함
일관된 이름 지정: 모델 버전에서 ID 및 이름에 일관된 명명 규칙 사용
명확한 설명: 모델 기능 및 사용 사례를 설명하는 유용한 설명 작성
적절한 라이선스: 항상 전체 라이선스 정보(형식, URI 및 텍스트) 포함
접근성 테스트: 모든 URI에 액세스할 수 있는지 확인하고 예상 콘텐츠를 반환합니다.
실행 공급자 호환성: 실행 공급자가 대상 하드웨어 기능과 일치하는지 확인
논리 그룹화: 이름 필드를 사용하여 관련 모델 변형 그룹화(동일한 기본 모델의 다른 EP 버전)
파일 조직: 관련 파일을 함께 유지하고 설명이 포함된 파일 이름을 사용합니다.
보안: 모든 파일 다운로드에 HTTPS 사용 및 SHA256 확인 포함

호스팅 고려 사항

모델 카탈로그를 호스팅하는 경우:

HTTPS 필요: 항상 HTTPS를 통해 카탈로그 및 모델 제공
CORS 헤더: 원본 간 액세스를 위한 적절한 CORS 헤더 구성
콘텐츠 형식: 콘텐츠 형식을 사용하여 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)"
        }
      }
    }
  }
}

다음 단계

모델 카탈로그 개요에 대해 알아보기
시작 가이드를 따릅니다.
Windows ML 설명서 살펴보기

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-06