Foundation Models 커스텀 어댑터: Apple이 권장하지 않는 라이프사이클

SystemLanguageModel.Adapter 타입을 사용하면 앱이 커스텀 트레이닝된 가중치를 Apple의 온디바이스 언어 모델에 로드할 수 있습니다.¹ 프레임워크가 이를 지원합니다. Apple은 트레이닝 툴킷을 제공합니다. 문서화된 entitlement, .fmadapter 패키지 포맷, 그리고 적합한 디바이스에 적합한 어댑터를 다운로드하기 위한 Background Assets 통합이 있습니다.

같은 타입에 대한 Apple 자체 문서는 또한 다음과 같이 그대로 인용하면 명시합니다: “어댑터는 많은 양의 저장 공간을 소비하며 대부분의 앱에는 권장되지 않습니다.”¹ 이 클러스터의 이전 포스트인 Foundation Models 사용 사례는 대부분의 앱이 따라야 할 정해진 길을 다루었습니다. 이 포스트는 세 번째 길입니다: 커스텀 어댑터를 트레이닝하고, 패키징하고, 출시하는 운영상의 라이프사이클, 그리고 그것을 하지 말아야 할 때에 대한 Apple의 명시적 가이드입니다.

TL;DR

• 커스텀 어댑터는 온디바이스 시스템 언어 모델 위에 오버레이되는 LoRA로 트레이닝된 가중치 행렬입니다.² Apple의 툴킷은 이 기법을 이름으로 명확히 확인합니다.
• 각 어댑터는 단일 시스템 모델 버전에 바인딩됩니다. Apple이 베이스 모델을 업데이트하면 어댑터를 다시 트레이닝해야 합니다.³
• Apple의 권장 사항은 그들의 표현으로: “대부분의 프롬프트 엔지니어링, 가이디드 제너레이션, 도구에는 베이스 시스템 모델을 사용하세요. 모델을 특화해야 하는 경우 커스텀 Adapter를 트레이닝하세요… Python로 파운데이션 모델을 트레이닝하는 것에 익숙한 경우에만 커스텀 어댑터를 사용하세요.”¹
• 어댑터 에셋은 크기가 크며(~160 MB), Background Assets를 통해 번들링되고, Apple Developer Program 멤버십의 Account Holder가 배포를 위해 요청하는 entitlement(com.apple.developer.foundation-model-adapter) 뒤에 게이팅됩니다.³
• 이 경로는 좁은 범위의 앱에 적합합니다: 파인튜닝된 서버 사이드 LLM을 온디바이스에서 복제하는 앱, 엄격한 스타일/포맷/정책 준수 요구 사항이 있는 앱, 또는 대상 작업에 대해 문서화된 프롬프트 엔지니어링의 한계가 있는 앱.²

어댑터가 실제로 무엇인가

SystemLanguageModel.Adapter는 struct이며, iOS, iPadOS, Mac Catalyst, macOS, visionOS에서 사용 가능하고, 모두 26.0+입니다.⁴ Apple의 타입에 대한 설명:

“대부분의 프롬프트 엔지니어링, 가이디드 제너레이션, 도구에는 베이스 시스템 모델을 사용하세요. 모델을 특화해야 하는 경우 시스템 모델 가중치를 변경하고 커스텀 작업에 맞게 최적화하기 위해 커스텀 Adapter를 트레이닝하세요. Python로 파운데이션 모델을 트레이닝하는 것에 익숙한 경우에만 커스텀 어댑터를 사용하세요.”⁴

이 메커니즘은 문서화되어 있습니다. Apple의 어댑터 트레이닝 가이드는 직접적으로 명시합니다:²

“시스템 모델은 LoRA(Low-Rank Adaptation)로 알려진 파라미터 효율적 파인튜닝(PEFT) 접근 방식을 사용합니다. LoRA에서는 원본 모델 가중치가 동결되고, ‘어댑터’라고 불리는 작은 트레이닝 가능한 가중치 행렬이 모델 네트워크를 통해 임베딩됩니다. 트레이닝 중에는 어댑터 가중치만 업데이트되며, 트레이닝할 파라미터 수가 크게 감소합니다.”

LoRA는 발표된 논문 이력이 있는 공개된 기법입니다.⁵ Apple의 기여는 툴킷, .fmadapter 패키지 포맷, 어댑터를 로드하는 온디바이스 런타임, 그리고 Background Assets를 통해 출시하기 위한 라이프사이클 배관입니다.

타입의 API 표면

Adapter 구조체는 작은 표면을 노출합니다:⁴

• init(fileURL: URL) throws: “파일 URL로부터 어댑터를 생성합니다.” 로컬 Xcode 테스트에 사용됩니다.
• init(name: String) throws: “background assets 프레임워크에서 다운로드된 어댑터를 생성합니다.” 프로덕션에서 사용됩니다.
• func compile() async throws: “LanguageModelSession과 함께 사용되기 전에 어댑터를 준비합니다. 어댑터에 드래프트 모델이 있는 경우 이를 호출해야 합니다.”
• var creatorDefinedMetadata: [String : Any]: 메타데이터의 creator-defined 필드의 값.
• static func removeObsoleteAdapters() throws: 현재 시스템 모델과 더 이상 일치하지 않는 어댑터를 제거합니다.
• static func compatibleAdapterIdentifiers(name: String) -> [String]: 호환 가능한 어댑터 에셋 팩의 ID를 가져옵니다.
• enum AssetError: 에셋 관련 실패에 대한 오류 타입.

SystemLanguageModel에는 어댑터를 위한 짝을 이루는 이니셜라이저가 있습니다: convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails), 설명은 “어댑터가 있는 모델의 베이스 버전을 생성합니다.”입니다.⁶

배포 전용 entitlement 키는 com.apple.developer.foundation-model-adapter입니다: “앱이 Foundation Models 프레임워크에 대해 커스텀 어댑터를 활성화할 수 있는지를 나타내는 Boolean 값.”⁶ 트레이닝이나 로컬 Xcode 테스트에는 필요하지 않으며, App Store에 출시하기 전에는 반드시 필요합니다.³

Apple의 “어댑터 고려 시점” 기준

툴킷 페이지는 구체적인 채택 신호를 제시합니다:²

• “LLM과 함께 사용하기에 적합한 데이터셋이 있는 경우” 또는 이미 파인튜닝된 서버 기반 LLM을 사용 중이며 온디바이스 패리티를 원하는 경우.
• “모델이 특정 분야의 전문가가 되어야 하는 경우.”
• “모델이 특정 스타일, 포맷, 또는 정책을 준수해야 하는 경우.”
• “프롬프트 엔지니어링이 작업에 필요한 정확도나 일관성을 달성하지 못하는 경우.”
• “추론에서 더 낮은 지연 시간을 원하는 경우. 프롬프트 엔지니어링된 솔루션이 매 호출마다 예제가 포함된 긴 프롬프트를 필요로 한다면, 해당 작업에 특화된 어댑터는 최소한의 프롬프팅을 제공합니다.”

같은 가이드는 또한 부담해야 할 비용을 나열합니다:²

• 대상 스킬을 보여주는 프롬프트와 응답 쌍의 데이터셋.
• 어댑터의 품질을 평가하기 위한 프로세스.
• 서버에서 앱으로 어댑터를 로드하는 프로세스.

그리고 저장 공간 세금: “각 어댑터는 앱에서 약 160 MB의 저장 공간을 차지합니다. 다른 큰 에셋과 마찬가지로, 여러 어댑터 버전이 있으면 앱이 사람들이 설치하기에 너무 커지므로 어댑터는 앱의 메인 번들에 포함되어서는 안 됩니다.”²

프레임워크의 권장 사항은 Apple이 두 개의 별도 위치에서 다시 진술한 대로, 프롬프트 엔지니어링과 도구 호출을 기본으로 하고 위의 기준이 통과되는 경우에만 어댑터에 손을 대는 것입니다.

Apple의 형식대로 트레이닝하기

트레이닝 파이프라인은 Python입니다. Apple의 툴킷은 샘플 코드, 특정 시스템 모델 버전과 일치하는 모델 에셋, 데이터셋 유틸리티, 그리고 .fmadapter 패키지를 생성하는 익스포트 단계를 제공합니다.²

하드웨어 요구 사항: “Apple silicon과 최소 32GB 메모리가 있는 Mac, 또는 Linux GPU 머신.” Python 3.11 이상.²

데이터셋 형식:²

• 형식은 role("user" 또는 "assistant")과 content 필드가 있는 jsonl입니다.
• 기본 작업의 경우 100~1,000개의 샘플.
• 복잡한 작업의 경우 5,000개 이상의 샘플.
• 툴킷의 Schema.md는 가이디드 제너레이션과 AI 안전 후크를 위한 필드를 포함하여 전체 스키마를 다룹니다.

데이터 품질에 대한 Apple의 메모는 인용할 가치가 있습니다: “양보다 질에 집중하세요. 명확하고, 일관되며, 잘 구조화된 샘플의 더 작은 데이터셋이 노이즈가 많고, 품질이 낮은 샘플의 더 큰 데이터셋보다 더 효과적일 수 있습니다.”²

트레이닝은 툴킷의 train_adapter 진입점에서 호출됩니다:

python -m examples.train_adapter \
  --train-data /path/to/train.jsonl \
  --eval-data /path/to/valid.jsonl \
  --epochs 5 \
  --learning-rate 1e-3 \
  --batch-size 4 \
  --checkpoint-dir /path/to/my_checkpoints/

선택적으로, 어댑터를 트레이닝한 후 일치하는 드래프트 모델을 트레이닝할 수 있습니다.² 드래프트 모델은 시스템 베이스 모델의 더 작은 버전으로, 발표된 추론 가속 기법인 추측적 디코딩(speculative decoding)을 활성화합니다.⁷ Apple의 표현: “드래프트 모델을 트레이닝하지 않기로 선택한 경우, 어댑터의 사용 사례에 대해 추측적 디코딩을 사용할 수 없습니다.”²

단일 버전 제약

어댑터에 대해 운영상 가장 영향력 있는 사실은 특정 시스템 모델 버전에 대한 바인딩입니다:³

“각 어댑터는 단일 특정 시스템 모델 버전과 호환됩니다. 새로운 베이스 모델 버전마다 새 어댑터를 트레이닝해야 합니다. 호환 가능한 어댑터 없이 앱이 사용자의 디바이스에서 실행되면 런타임 오류가 발생합니다.”

툴킷은 모델과 함께 버전이 매겨집니다. 작성 시점 기준으로 Apple은 두 개의 베타 툴킷 버전(Beta 0.1.0과 Beta 0.2.0, 둘 다 제거됨)과 하나의 정식 릴리스인 26.0.0을 출시했습니다.² Apple의 릴리스 주기 진술: “모든 시스템 모델 업데이트마다 새 툴킷이 릴리스됩니다. 시스템 모델은 iOS, macOS, visionOS에서 공유되며, 시스템 모델 업데이트는 해당 플랫폼의 OS 업데이트의 일부로 발생합니다(모든 OS 업데이트에 모델 업데이트가 있는 것은 아닙니다).”²

운영적 함의: 어댑터를 출시하는 앱 팀은 Apple의 주기에서 실행되는 모델 업데이트 라이프사이클을 구독하게 됩니다. 각 베이스 모델 업그레이드는 재트레이닝, 재평가, 재출시를 강제하는 함수입니다.

에셋 팩으로 패키징

어댑터 파일은 앱에 번들링하기에는 너무 커서 명시적으로 권장되지 않습니다. Apple은 어댑터 전달을 Background Assets를 통해 라우팅합니다.³

툴킷은 .fmadapter 패키지를 생성하며, 툴킷은 또한 이를 Background Assets 에셋 팩으로 번들링합니다. Xcode 16 이상의 ba-package 명령줄 도구가 번들링 작업을 수행하며, 툴킷이 이를 호출합니다.³

호스팅 선택지:³

• Apple-Hosted, Managed. Apple이 에셋을 호스팅하고, OS가 다운로드 라이프사이클을 관리합니다.
• Self-Hosted, Managed. 자체 서버에서 호스팅하고, OS가 다운로드 라이프사이클을 관리합니다.
• Self-Hosted, Unmanaged. 직접 호스팅하고 라이프사이클을 직접 관리합니다.

필요한 Info.plist 키는 호스팅 선택지에 따라 다릅니다:³ Apple-Hosted Managed는 BAHasManagedAssetPacks, BAAppGroupID, BAUsesAppleHosting이 필요하고; Self-Hosted Managed는 처음 두 개가 필요하며; Self-Hosted Unmanaged는 아무것도 필요하지 않습니다. 각 경로에는 또한 Xcode가 생성하는 에셋 다운로더 익스텐션 타깃이 있습니다.

런타임에 적합한 어댑터 선택하기

에셋 다운로더 익스텐션의 BackgroundDownloadHandler.swift가 생성될 때, Xcode는 shouldDownload(_:) 콜백을 연결합니다. 어댑터 에셋에 대한 Apple의 예시 본문:³

func shouldDownload(_ assetPack: AssetPack) -> Bool {
    if assetPack.id.hasPrefix("mygameshader") {
        return true
    }
    return SystemLanguageModel.Adapter.isCompatible(assetPack)
}

SystemLanguageModel.Adapter.isCompatible(_:)는 어댑터가 현재 시스템 모델과 일치하는 에셋 팩에 대해 true를 반환합니다. 같은 콜백은 또한 앱이 필요로 하는 어댑터가 아닌 에셋도 통과시킬 수 있습니다.

다운로드 로드 및 추적

에셋이 디바이스에 있으면 로드 경로는 다음과 같습니다:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

let adapter = try SystemLanguageModel.Adapter(name: "myAdapter")

생성은 디바이스에 호환 가능한 어댑터가 캐시되어 있지 않은 경우 다운로드를 시작합니다. UX에 대한 Apple의 메모: “어댑터는 데이터 크기가 클 수 있어 다운로드에 시간이 걸릴 수 있습니다. 특히 사람이 Wi-Fi나 셀룰러 네트워크에 있는 경우에 그렇습니다. 사람이 네트워크 연결이 없는 경우에는 어댑터를 즉시 사용할 수 없습니다.”³

상태 시퀀스는 AssetPackManager에서 옵니다:³

let assetpackIDList = SystemLanguageModel.Adapter.compatibleAdapterIdentifiers(name: name)
if let assetPackID = assetpackIDList.first {
    let statusUpdates = AssetPackManager.shared.statusUpdates(forAssetPackWithID: assetPackID)
    for await status in statusUpdates {
        switch status {
        case .began(let assetPack): ...
        case .paused(let assetPack): ...
        case .downloading(let assetPack, let progress): ...
        case .finished(let assetPack): ...
        case .failed(let assetPack, let error): ...
        @unknown default: ...
        }
    }
}

문서화된 다섯 가지 DownloadStatusUpdate 케이스: .began, .paused, .downloading, .finished, .failed.³ 프레임워크의 @unknown default 분기는 Apple이 향후 SDK 버전에서 케이스를 추가할 수 있기 때문에 필수입니다.

상태가 .finished에 도달한 후, 어댑터는 세션에 연결할 준비가 됩니다:

let adaptedModel = SystemLanguageModel(adapter: adapter)
let session = LanguageModelSession(model: adaptedModel)

드래프트 모델과 그 속도 제한

어댑터에 드래프트 모델이 함께 출시된 경우, adapter.compile()을 호출하여 사용을 위해 준비합니다. Apple의 문서는 이를 별도의, 계산적으로 비용이 많이 드는 단계로 명시합니다:³

“디바이스가 새 버전의 어댑터를 처음 다운로드할 때, compile() 호출은 드래프트 모델을 완전히 컴파일하여 디바이스에 저장합니다. 앱의 후속 실행 중에는 compile() 호출이 저장된 컴파일된 드래프트 모델을 확인하고 존재하는 경우 즉시 반환합니다.”

발표된 속도 제한이 있습니다:³

“속도 제한은 모든 앱과 프로세스 간에 공유되는 디바이스 리소스를 보호합니다. 프레임워크가 새 컴파일이 필요하다고 판단하면 macOS를 제외한 모든 플랫폼에서 컴파일 프로세스를 앱당, 일일 3개의 드래프트 모델 컴파일로 속도 제한합니다.”

macOS 제외는 흥미롭습니다; 이 제한은 iOS, iPadOS, visionOS에 적용됩니다. Apple은 컴파일 작업이 앱 실행을 차단하지 않도록 Background Tasks 스케줄된 작업 내에서 컴파일을 실행할 것을 권장합니다.³

개발 시 주의 사항: “Xcode를 통해 앱을 실행할 때마다 Xcode가 매 실행마다 앱에 새 UUID를 할당하기 때문에 전체 컴파일 프로세스가 실행됩니다. 앱을 테스트하는 동안 속도 제한 오류를 받는 경우, Xcode에서 앱을 중지하고 다시 실행하여 속도 카운터를 리셋하세요.”³

테스트 및 시뮬레이터 제약

어댑터 테스트에는 물리적 디바이스가 필요합니다. Apple은 명확하게 말합니다: “어댑터 테스트에는 물리적 디바이스가 필요하며 시뮬레이터에서는 지원되지 않습니다.”³

Xcode에서 로컬 테스트를 위해, 이름이 아닌 파일 URL에서 초기화합니다:³

let localURL = URL(filePath: "absolute/path/to/my_adapter.fmadapter")
let adapter = try SystemLanguageModel.Adapter(fileURL: localURL)

Apple의 패턴: 테스트를 위해 로컬 파일을 임포트하고, 어댑터 파일이 번들링하기에 너무 크기 때문에 앱을 게시하기 전에 프로젝트에서 제거합니다.³

운영 측면에서 이 경로가 부담시키는 비용

라이프사이클을 종합하면, 커스텀 어댑터를 출시하는 앱은 다음에 가입하게 됩니다:

1. Python 트레이닝 인프라. 최소한 32 GB 메모리의 Apple silicon Mac, 또는 Linux GPU 머신.²
2. Apple의 시계에 따른 재트레이닝 주기. 모든 시스템 모델 업데이트는 새로운 어댑터와 새로운 툴킷 버전을 의미합니다.³
3. 서빙 스택. App Store Connect를 통한 Apple 호스팅 에셋 팩, 또는 에셋 다운로더 통합을 실행하는 자체 서버 중 하나.³
4. 저장 공간에 버전별 어댑터. 다양한 베이스 모델 버전이 사용 중이라는 것은 여러 어댑터를 호스팅해야 하며, 디바이스가 일치하는 것을 가져온다는 것을 의미합니다.³
5. Entitlement 게이트. Apple Developer Program 멤버십의 Account Holder가 요청하며, 승인 없이는 출시할 수 없습니다.²
6. 어댑터 버전당 160 MB 세금. 앱 번들에는 없지만, 다운로드 후 사용자의 디바이스에 있습니다.²
7. 물리적 디바이스 테스트. 시뮬레이터는 어댑터를 실행하지 않습니다.³

이것이 평이한 형태의 운영 비용입니다. 채택 신호가 통과될 때의 이점은: 온디바이스 모델이 최소한의 프롬프팅, 더 낮은 지연 시간, 호출당 API 비용 없음, 그리고 완전한 데이터 로컬리티로 작업에 특화됩니다. 이미 파인튜닝된 서버 사이드 추론에 비용을 지불하고 있고 온디바이스 패리티를 원하는 앱에게는, 평이한 표현으로 그것이 거래입니다.

핵심 요점

1. 어댑터는 Apple이 문서화한 기법으로 LoRA입니다. 동결된 베이스 가중치, 모델 네트워크를 통과하는 작은 트레이닝 가능한 행렬, 트레이닝 중 어댑터 가중치만 업데이트됩니다.²
2. 시스템 모델 버전당 하나의 어댑터, 예외 없음. OS 릴리스에 묶인 재트레이닝을 계획하세요.³
3. .fmadapter 흐름은 엔드 투 엔드입니다. Python로 트레이닝하고, 툴킷으로 패키징하고, Background Assets 에셋 팩으로 호스팅하고, 앱에서 이름으로 로드하고, 백그라운드 작업에서 드래프트 모델을 컴파일합니다.
4. Apple 자체가 대부분의 앱은 이 경로를 가지 않을 것을 권장합니다. 두 개의 별도 Apple 문서 페이지가 대부분의 사용 사례에 대해 이를 권장하지 않습니다.¹ 툴킷 페이지의 기준을 읽으세요; 기본 답변은 “아니오”입니다.
5. 하드웨어에서 테스트하세요. 시뮬레이터는 어댑터를 실행하지 않습니다. 물리적 디바이스 세션과 Background Tasks 프레임워크의 컴파일 슬롯을 중심으로 테스트 계획을 수립하세요.

전체 Apple Ecosystem 클러스터: 내장된 특화에 대한 결정 기준; 프레임워크의 핵심에 있는 Tool 프로토콜; 인앱과 도구 LLM 사이의 에이전틱 워크플로우 분리; 더 넓은 라우팅 질문에 대한 App Intents vs MCP. 허브는 Apple Ecosystem Series에 있습니다. AI 에이전트가 있는 더 넓은 iOS 컨텍스트에 대해서는 iOS Agent Development guide를 참조하세요.

FAQ

내 앱이 실제로 커스텀 어댑터가 필요한지 어떻게 알 수 있나요?

툴킷 가이드에서 Apple의 “어댑터 고려 시점” 섹션을 읽으세요.² 신호: 온디바이스에서 미러링하려는 기존의 파인튜닝된 서버 사이드 LLM, 정확도에 대한 문서화된 프롬프트 엔지니어링의 한계, 특정 스타일/포맷/정책 준수에 대한 엄격한 요구 사항, 또는 프롬프트 엔지니어링만으로는 놓치는 지연 시간 목표. 대부분의 앱은 이 중 어느 것도 통과하지 않으며 Apple은 그렇게 말합니다.

Entitlement는 실제로 무엇을 게이팅하나요?

배포이며, 트레이닝이 아닙니다. Apple의 문서는 명시적으로 명시합니다: “어댑터를 트레이닝하거나 로컬에서 테스트하기 위해 이 entitlement가 필요하지 않습니다.”³ Apple Developer Program 멤버십의 Account Holder가 Foundation Models Framework Adapter Entitlement 페이지에서 com.apple.developer.foundation-model-adapter를 요청하며, 그 entitlement가 App Store 출시를 위한 경로를 통과시킵니다.²

어댑터는 얼마나 크고 어디에 있나요?

Apple의 문서화된 숫자: “각 어댑터는 앱에서 약 160 MB의 저장 공간을 차지합니다.”² 어댑터는 앱 번들에 있지 않습니다. Apple은 이를 Background Assets를 통해 라우팅하고, Apple 서버(managed) 또는 자체 서버(managed 또는 unmanaged)에 호스팅하며, 디바이스가 현재 시스템 모델과 일치하는 버전을 다운로드합니다.³

Apple이 베이스 모델을 업데이트하면 어떻게 되나요?

다시 트레이닝합니다. 문서에서: “각 어댑터는 단일 특정 시스템 모델 버전과 호환됩니다. 새 베이스 모델 버전마다 새 어댑터를 트레이닝해야 합니다. 호환 가능한 어댑터 없이 앱이 사용자의 디바이스에서 실행되면 런타임 오류가 발생합니다.”³ 실제로는 서빙 스택이 여러 어댑터 버전을 동시에 호스팅하며 디바이스가 isCompatible(_:)을 기반으로 적합한 것을 가져옵니다.

어댑터와 .contentTagging의 관계는 무엇인가요?

.contentTagging은 Apple이 제공하는 두 개의 SystemLanguageModel.UseCase 정적 속성 중 하나로, 동반 포스트에서 다룹니다. 이는 entitlement에 의해 게이팅되지 않는, 프레임워크에 포함된 Apple-managed 특화입니다. 커스텀 Adapter는 Apple의 사용 사례가 다루지 않는 작업에 대한 개발자 관리 등가물입니다. Apple의 문서는 .contentTagging이 내부적으로 어떻게 작동하는지를 설명할 때 “adapted”라는 단어를 사용하지만, 이는 공식 Adapter 타입과 동일하지 않습니다. 공식 타입은 이 포스트가 다루는 것입니다.

드래프트 모델을 트레이닝해야 하나요?

아닙니다. Apple의 문서: “드래프트 모델을 트레이닝하지 않기로 선택한 경우, 어댑터의 사용 사례에 대해 추측적 디코딩을 사용할 수 없습니다.”² 어댑터는 여전히 로드되고 서비스됩니다; 단순히 추측적 디코딩 추론 속도 향상을 얻지 못할 뿐입니다. 드래프트 모델은 선택적인 두 번째 트레이닝 패스입니다.

참고 자료