mlmodel — 개념, 파일 구조 및 mlpackage로 변환

mlmodel이란?

mlmodel은 Apple이 2017년 WWDC 2017에서 Core ML 프레임워크와 함께 발표한 바이너리 파일 형식입니다. 이 형식은 Google의 protobuf(Protocol Buffers) 직렬화 기술을 기반으로 하여 컴팩트한 크기(Float32의 모델 가중치)와 효율적인 메모리 로딩을 보장했습니다. .mlmodel 파일의 확장자는 .mlmodel이고 MIME 유형은 application/x-Apple-mlmodel이었습니다.

형식의 역사

.mlmodel 형식은 2017년부터 2021년까지 유일한 Core ML 형식이었습니다. 이 기간 동안 TensorFlow, Keras, PyTorch, Caffe, scikit-learn 및 기타 라이브러리의 수백만 모델이 coremltools를 통해 변환되었습니다. 모델 복잡성이 증가함에 따라 형식의 한계가 분명해졌습니다: protobuf는 편리한 버전 관리를 지원하지 않으며, 메타데이터는 바이너리 형식으로 저장되고(git diff에서 읽을 수 없음), 새 필드를 추가하려면 protobuf 스키마 변경이 필요했습니다.

주요 특징

mlmodel 파일은 모델을 컴팩트한 바이너리 표현으로 저장합니다. 크기는 수십 킬로바이트(선형 회귀)에서 기가바이트(수백만 개의 매개변수를 가진 신경망)까지 다양합니다. 이 형식은 모든 Core ML 모델 유형을 지원합니다: 신경망(NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), 앙상블 모델(TreeEnsemble, GradientBoosting), 회귀(LinearRegression, SVM), 전처리/후처리 파이프라인(OneHotEncoder, FeatureVectorizer).

mlmodel 파일 구조

.mlmodel 파일의 내부 구조는 CoreML.framework 프레임워크에 정의된 protobuf 스키마에 의해 결정됩니다. 주요 섹션은 다음과 같습니다: modelDescription — 모델의 입력, 출력 및 메타데이터 설명; modelParameters — 모델 유형의 특정 매개변수(신경망 가중치, 트리 앙상블, 회귀 계수); preprocessing — 전처리 구성(스케일링, 이미지 정규화); postprocessing — 후처리(softmax, argmax, 임계값).

modelDescription 섹션

modelDescription 섹션(MLModelDescription)에는 모델 이름, 작성자, 버전, 설명, 라이선스 및 모든 입력 및 출력 매개변수에 대한 자세한 설명(이름, 데이터 유형(Float32, Int32, String, Image), 차원, 이미지 형식(BGR, RGB), 선택적 제약 조건(값 범위))이 포함됩니다. 이 섹션은 Xcode에서 형식화된 입력 및 출력이 있는 Swift 모델 클래스를 생성하는 데 사용되었습니다.

modelParameters 섹션

modelParameters 섹션에는 학습된 모델의 실제 가중치와 매개변수가 포함됩니다. 신경망의 경우 각각 유형(convolution, pooling, activation, innerProduct), 가중치, 편향 및 매개변수(kernelSize, stride, padding)를 포함하는 레이어(NeuralNetworkLayer) 배열입니다. 앙상블 모델의 경우 — 의사 결정 트리와 해당 노드. 회귀의 경우 — 계수와 절편. 가중치는 Float32(값당 4바이트)로 저장됩니다.

preprocessing 섹션

preprocessing 섹션에서는 모델에 입력 데이터를 공급하기 전의 전처리 단계를 설명합니다. Core ML이 지원하는 것: 스케일링(Scaler) — 평균 및 표준 편차를 통한 정규화; 이미지 변환(ImagePreprocessing) — 크기 조정, 자르기, 색상 채널 정규화, BGR→RGB 변환; OneHotEncoder — 범주형 특성 인코딩; FeatureVectorizer — 여러 특성을 하나의 벡터로 결합.

mlmodel vs mlpackage: 비교 분석

mlpackage는 WWDC 2021에서 발표된 Core ML 모델의 차세대 형식입니다. 단일 바이너리 .mlmodel 파일과 달리 .mlpackage는 파일 구조가 있는 디렉토리(패키지)입니다: 모델 내용은 읽을 수 있는 JSON 파일(메타데이터, 레이어 구성)과 가중치용 별도 바이너리 파일로 저장됩니다. 이는 스토리지, 버전 관리 및 ML 모델 협업 방식에 근본적인 변화를 가져옵니다.

mlpackage의 파일 구조

.mlpackage 패키지에는 다음이 포함됩니다: ModelCI/ — 버전 관리된 모델 구성 디렉토리; Data/ — 바이너리 가중치 파일(SharedWeights.bin); Metadata.json — 이름, 작성자, 설명, 모델 버전, 생성 날짜; Model.json — 아키텍처 설명, 입력/출력, 레이어 유형; Manifests/ — CI/CD용 버전 매니페스트. 이 구조는 git에서 모델을 효율적으로 작업할 수 있게 합니다: 메타데이터와 구성은 추적되고 바이너리 가중치는 Git LFS를 사용할 수 있습니다.

mlmodel을 mlpackage로 변환하는 방법

.mlmodel에서 .mlpackage로의 변환은 두 가지 방법으로 수행됩니다: Xcode에서 빌드 중 자동으로(Xcode 자체가 컴파일 중에 .mlmodel을 .mlpackage로 변환) 또는 Python에서 coremltools를 통해 수동으로. 수동 변환은 더 많은 제어를 제공하며 모델 메타데이터 업데이트, 설명 추가 및 작성자 설정이 가능합니다. 변환 후 모델은 .mlpackage로 저장되며 원래 .mlmodel 대신 사용할 수 있습니다.

import coremltools as ct

model = ct.models.MLModel(
    "OldModel.mlmodel"
)
model.author = "IT Sectr"
model.short_description = "Converted from mlmodel"
model.version = "2.0"
model.save("NewModel.mlpackage")

Xcode에서의 자동 변환

.mlmodel 파일을 Xcode 프로젝트에 추가하면 시스템이 자동으로 형식을 감지하고 빌드 중에 Model Compiler를 실행합니다 — .mlmodel을 .mlpackage로 변환하는 도구입니다. 컴파일된 .mlpackage는 빌드 디렉토리(DerivedData)에 배치됩니다. 개발자는 이 프로세스를 인식하지 못합니다 — 모든 Core ML API는 원래 형식에 관계없이 모델과 일관되게 작동합니다. 그러나 Xcode는 .mlmodel을 추가할 때 .mlpackage 사용을 권장하는 경고를 표시합니다.

변환 후 검증

변환 후 모델이 정확도를 유지하는지 확인해야 합니다. coremltools는 동일한 입력 데이터에서 원본 모델과 변환된 모델의 예측을 비교하는 ct.utils.compare_models() 유틸리티를 제공합니다. Float32의 허용 오차는 1e-5 이하입니다. 오차가 이 임계값을 초과하면 모델에 새 형식에서 지원되지 않는 사용자 정의 레이어나 작업이 포함되었을 수 있습니다.

하위 호환성 및 지원

.mlmodel의 하위 호환성은 iOS 및 macOS의 모든 현재 버전에서 보장됩니다. Xcode 12 이상으로 컴파일된 애플리케이션은 원래 파일이 .mlmodel이더라도 자동으로 .mlpackage 버전의 모델을 받습니다. 그러나 Xcode 15(2023)부터 Apple은 새로운 모델 유형(동적 신경망, 제어된 학습)이 .mlpackage 형식에서만 사용 가능하며 .mlmodel은 새로운 기능을 받지 않을 것이라고 발표했습니다.

iOS 18+ 및 macOS 15+에서의 지원

iOS 18 및 macOS 15(Sequoia)부터 Core ML은 더 이상 .mlmodel 직접 로딩을 지원하지 않습니다. 모든 .mlmodel 모델은 사전에 .mlpackage로 변환되어야 하거나 빌드 중에 Xcode Model Compiler가 변환에 사용됩니다. 시스템 API MLModel(contentsOf:)는 프로젝트 빌드 단계에서 .mlpackage로 변환된 경우에만 .mlmodel 파일을 열 수 있습니다.

지원 종료 일정

Apple은 .mlmodel 지원의 완전한 제거 날짜를 공식적으로 발표하지 않았지만 역사적 맥락은 3-4년의 전환 기간을 시사합니다. .mlmodel 형식은 2017년에 도입되었고 .mlpackage는 2021년에 도입되었습니다. 지원 중단 경고는 Xcode 13(2021)에 나타났습니다. 32비트 애플리케이션(iOS 11이 지원 종료)과 유사하게 .mlmodel의 완전한 지원은 iOS 20-21(2026-2027)에 종료될 수 있습니다.

mlmodel이 여전히 유효한 경우

형식의 지원 중단에도 불구하고 .mlmodel은 여전히 기존 프로젝트와 일부 시나리오에서 발견됩니다. Core ML을 사용하는 개발자는 .mlmodel이 언제 워크플로의 일부로 남아 있는지, 성능 저하 없이 올바르게 상호 작용하는 방법을 이해해야 합니다.

레거시 — 오래된 프로젝트

2021년 이전에 시작된 기존 프로젝트에는 Swift Package Manager 또는 Xcode에 직접 로드된 수십 개의 .mlmodel 모델이 포함될 수 있습니다. 모든 모델을 .mlpackage로 마이그레이션하는 것은 특히 모델이 이전 버전의 coremltools(5.0 이전)로 생성된 경우 많은 노력이 필요할 수 있습니다. Apple은 가장 가까운 기능 업데이트 시 한 번에 하나의 모델씩 점진적으로 마이그레이션할 것을 권장합니다.

coremltools를 사용한 CI/CD 파이프라인

일부 기존 CI/CD 파이프라인은 자동 모델 변환에 coremltools 버전 4.x를 사용하며 기본적으로 .mlmodel로 내보냅니다. coremltools를 버전 5+로 업데이트하면 내보내기 형식이 .mlpackage로 변경되어 스크립트 및 테스트 업데이트가 필요할 수 있습니다. 이러한 경우 팀은 때때로 마이그레이션을 나중으로 계획하면서 임시로 .mlmodel로 내보내기를 유지합니다.

라이브러리 및 Pods

2021년 이전에 게시된 타사 라이브러리 및 CocoaPods에는 .mlmodel 형식의 모델이 포함될 수 있습니다. 예를 들어 얼굴 인식, 이미지 필터링 또는 AR 필터용 라이브러리입니다. 이러한 라이브러리를 사용하는 개발자는 Xcode가 빌드 시 자동으로 변환하므로 .mlmodel로 계속 작업할 수 있습니다. 그러나 작성자가 .mlpackage로 업데이트를 출시했는지 확인하는 것이 좋습니다.

mlmodel의 일반적인 문제

더 이상 사용되지 않는 .mlmodel 형식으로 작업할 때 개발자는 몇 가지 일반적인 문제에 직면합니다. 이러한 문제와 해결 방법을 알면 최신 프로젝트에 Core ML 모델을 통합할 때 시간 낭비를 방지하는 데 도움이 됩니다. 주요 문제를 살펴보겠습니다.

Xcode 지원 중단 경고

Xcode 13+에서 .mlmodel을 추가하면 경고가 나타납니다: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” 경고는 빌드를 차단하지 않지만 마이그레이션의 필요성을 나타냅니다. 경고를 해결하려면 coremltools를 통해 모델을 변환하거나 모델 생성 도구를 업데이트하십시오.

“Model file is not valid” 오류

이전 버전의 coremltools(3.0 이전)로 만든 .mlmodel 파일은 protobuf 코덱의 변경으로 인해 iOS 16+가 설치된 새 기기에서 열리지 않을 수 있습니다. 해결책은 Python을 통해 모델을 로드하는 것입니다: model = ct.models.MLModel(“old.mlmodel”), 그런 다음 다시 저장합니다: model.save(“fixed.mlmodel”), 또는 더 나은 것은 직접 .mlpackage로 변환하는 것입니다.

사용자 정의 레이어 문제

사용자 정의 레이어(사용자 정의 신경망 레이어)를 포함하는 .mlmodel 모델은 추가 단계 없이 직접 .mlpackage로 변환할 수 없습니다. 먼저 coremltools에서 모델을 로드하고 새 형식에서 지원되지 않는 레이어를 확인한 다음 .mlpackage용으로 구현해야 합니다. 사용자 정의 레이어가 중요하지 않은 경우 모델에서 제거할 수 있습니다.