Niestandardowe adaptery Foundation Models: cykl życia, którego Apple odradza

Typ SystemLanguageModel.Adapter umożliwia aplikacji wczytanie niestandardowo wytrenowanych wag do modelu językowego Apple działającego na urządzeniu.¹ Framework to obsługuje. Apple udostępnia zestaw narzędzi treningowych. Istnieje udokumentowane uprawnienie, format pakietu .fmadapter oraz integracja z Background Assets pozwalająca pobrać odpowiedni adapter dla odpowiedniego urządzenia.

Własna dokumentacja Apple dotycząca tego samego typu zawiera również, cytując dosłownie: „Adapters consume a large amount of storage space and isn’t recommended for most apps.”¹ Wcześniejszy artykuł w tym klastrze, Foundation Models Use Cases, omawiał ścieżki, którymi powinna podążać większość aplikacji. Niniejszy artykuł to trzecia szyna: operacyjny cykl życia trenowania, pakowania i wdrażania niestandardowego adaptera oraz wyraźne wskazówki Apple, kiedy tego nie robić.

TL;DR

• Niestandardowy adapter to macierz wag wytrenowana metodą LoRA, która nakłada się na systemowy model językowy działający na urządzeniu.² Zestaw narzędzi Apple potwierdza tę technikę z nazwy.
• Każdy adapter jest powiązany z konkretną wersją modelu systemowego. Gdy Apple aktualizuje model bazowy, należy ponownie wytrenować adapter.³
• Rekomendacja Apple, w ich własnych słowach: „Use the base system model for most prompt engineering, guided generation, and tools. If you need to specialize the model, train a custom Adapter… Use custom adapters only if you’re comfortable training foundation models in Python.”¹
• Zasoby adapterów są duże (~160 MB), dystrybuowane przez Background Assets i ograniczone uprawnieniem (com.apple.developer.foundation-model-adapter), o które Account Holder członkostwa Apple Developer Program wnioskuje na potrzeby wdrożenia.³
• Ścieżka ta ma sens dla wąskiego zbioru aplikacji: takich, które replikują dostrojony serwerowy LLM na urządzeniu, takich, które mają ścisłe wymagania zgodności ze stylem, formatem lub polityką, lub takich, które mają udokumentowane ograniczenia inżynierii promptów na docelowym zadaniu.²

Czym właściwie jest adapter

SystemLanguageModel.Adapter to struct dostępny na iOS, iPadOS, Mac Catalyst, macOS i visionOS, wszystkich w wersji 26.0+.⁴ Opis tego typu według Apple:

„Use the base system model for most prompt engineering, guided generation, and tools. If you need to specialize the model, train a custom Adapter to alter the system model weights and optimize it for your custom task. Use custom adapters only if you’re comfortable training foundation models in Python.”⁴

Mechanizm jest udokumentowany. Przewodnik Apple dotyczący trenowania adapterów stwierdza to wprost:²

„The system model uses a parameter-efficient fine-tuning (PEFT) approach known as LoRA (Low-Rank Adaptation). In LoRA, the original model weights are frozen, and small trainable weight matrices called ‘adapters’ are embedded through the model’s network. During training, only adapter weights are updated, significantly reducing the number of parameters to train.”

LoRA to publiczna technika z opublikowaną historią prac naukowych.⁵ Wkład Apple to zestaw narzędzi, format pakietu .fmadapter, środowisko uruchomieniowe na urządzeniu wczytujące adapter oraz infrastruktura cyklu życia umożliwiająca dostarczanie go przez Background Assets.

Powierzchnia API tego typu

Struktura Adapter udostępnia niewielką powierzchnię:⁴

• init(fileURL: URL) throws: „Creates an adapter from the file URL.” Używane do lokalnego testowania w Xcode.
• init(name: String) throws: „Creates an adapter downloaded from the background assets framework.” Używane w środowisku produkcyjnym.
• func compile() async throws: „Prepares an adapter before being used with a LanguageModelSession. You should call this if your adapter has a draft model.”
• var creatorDefinedMetadata: [String : Any]: wartości z pola metadanych zdefiniowanego przez twórcę.
• static func removeObsoleteAdapters() throws: usuwa adaptery, które nie pasują już do bieżącego modelu systemowego.
• static func compatibleAdapterIdentifiers(name: String) -> [String]: pobiera identyfikatory kompatybilnych pakietów zasobów adapterów.
• enum AssetError: typ błędu dla niepowodzeń związanych z zasobami.

SystemLanguageModel ma sparowany inicjalizator dla adapterów: convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails), z opisem „Creates the base version of the model with an adapter.”⁶

Klucz uprawnienia wymagany wyłącznie przy wdrożeniu to com.apple.developer.foundation-model-adapter: „A Boolean value that indicates whether the app can enable custom adapters for the Foundation Models framework.”⁶ Nie jest on potrzebny do trenowania ani do lokalnego testowania w Xcode; jest natomiast wymagany przed wysyłką do App Store.³

Kryteria Apple „kiedy rozważyć adapter”

Strona zestawu narzędzi przedstawia konkretne sygnały adopcji:²

• „You have a dataset suitable for use with an LLM” lub używają już Państwo dostrojonego serwerowego LLM i zależy Państwu na parytecie na urządzeniu.
• „You need the model to become a subject-matter expert.”
• „You need the model to adhere to a specific style, format, or policy.”
• „Prompt engineering isn’t achieving the required accuracy or consistency for your task.”
• „You want lower latency at inference. If your prompt-engineered solutions require lengthy prompts with examples for every call, an adapter specialized for that task offers minimal prompting.”

Ten sam przewodnik wymienia również koszty, które należy ponieść:²

• Zbiór danych par prompt-odpowiedź demonstrujących docelową umiejętność.
• Proces oceny jakości adapterów.
• Proces wczytywania adapterów do aplikacji z serwera.

Oraz podatek za przechowywanie: „Each adapter will take approximately 160 MB of storage space in your app. Like other big assets, adapters shouldn’t be part of your app’s main bundle because with multiple adapter versions your app will become too big for people to install.”²

Rekomendacja frameworka, powtórzona przez Apple w dwóch oddzielnych miejscach, brzmi: domyślnie należy stosować inżynierię promptów wraz z wywoływaniem narzędzi, a po adaptery sięgać tylko wtedy, gdy powyższe kryteria są spełnione.

Trenowanie w wydaniu Apple

Pipeline treningowy jest oparty na Python. Zestaw narzędzi Apple zawiera przykładowy kod, zasoby modelu pasujące do konkretnej wersji modelu systemowego, narzędzia do obsługi zbiorów danych oraz krok eksportu, który tworzy pakiet .fmadapter.²

Wymagania sprzętowe: „Mac with Apple silicon and at least 32GB memory, or Linux GPU machines.” Python 3.11 lub nowszy.²

Format zbioru danych:²

• Format jsonl z polami role ("user" lub "assistant") oraz content.
• Od 100 do 1 000 próbek dla podstawowych zadań.
• 5 000+ próbek dla złożonych zadań.
• Plik Schema.md w zestawie narzędzi obejmuje pełen schemat, łącznie z polami dla generowania kierowanego oraz haków bezpieczeństwa AI.

Uwaga Apple dotycząca jakości danych warta jest zacytowania: „Focus on quality over quantity. A smaller dataset of clear, consistent, and well-structured samples may be more effective than larger dataset of noisy, low-quality samples.”²

Trenowanie uruchamiane jest z punktu wejścia train_adapter zestawu narzędzi:

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/

Opcjonalnie, po wytrenowaniu adaptera, można wytrenować pasujący draft model.² Draft model to mniejsza wersja systemowego modelu bazowego, która umożliwia speculative decoding — opublikowaną technikę przyspieszania wnioskowania.⁷ Sformułowanie Apple: „If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.”²

Ograniczenie pojedynczej wersji

Najbardziej istotnym operacyjnie faktem dotyczącym adapterów jest powiązanie z konkretną wersją modelu systemowego:³

„Each adapter is compatible with a single specific system model version. You must train a new adapter for every new base model version. A runtime error occurs if your app runs on a person’s device without a compatible adapter.”

Zestaw narzędzi jest wersjonowany wraz z modelem. W chwili pisania tego artykułu Apple wydało dwie wersje beta zestawu narzędzi (Beta 0.1.0 i Beta 0.2.0, obie wycofane) oraz jedno pełne wydanie: 26.0.0.² Stanowisko Apple dotyczące cykliczności wydań: „A new toolkit will be released for every system model update. The system model is shared across iOS, macOS, and visionOS, and system model updates will occur as part of those platforms’ OS updates (though not every OS update will have a model update).”²

Konsekwencja operacyjna: zespoły aplikacji wdrażające adaptery podpisują się pod cyklem życia aktualizacji modelu zgodnym z rytmem Apple. Każda aktualizacja modelu bazowego stanowi czynnik wymuszający ponowne trenowanie, ponowną ewaluację oraz ponowną publikację.

Pakowanie jako asset packs

Plik adaptera jest na tyle duży, że dołączanie go do aplikacji jest jawnie odradzane. Apple kieruje dostarczanie adapterów przez Background Assets.³

Zestaw narzędzi tworzy pakiety .fmadapter, które są przez niego również pakowane jako Background Assets asset packs. Narzędzie wiersza poleceń ba-package z Xcode 16 lub nowszego wykonuje pracę pakowania; zestaw narzędzi je wywołuje.³

Opcje hostingu:³

• Apple-Hosted, Managed. Apple hostuje zasób; system operacyjny zarządza cyklem życia pobierania.
• Self-Hosted, Managed. Zasób hostowany jest na własnym serwerze; system operacyjny zarządza cyklem życia pobierania.
• Self-Hosted, Unmanaged. Hosting i zarządzanie cyklem życia odbywa się we własnym zakresie.

Wymagane klucze Info.plist różnią się w zależności od opcji hostingu:³ Apple-Hosted Managed wymaga BAHasManagedAssetPacks, BAAppGroupID oraz BAUsesAppleHosting; Self-Hosted Managed wymaga pierwszych dwóch; Self-Hosted Unmanaged nie wymaga żadnego. Każda ścieżka posiada również cel rozszerzenia asset-downloader, który Xcode generuje automatycznie.

Wybór odpowiedniego adaptera w czasie wykonania

Gdy generowany jest plik BackgroundDownloadHandler.swift rozszerzenia asset-downloader, Xcode wpina callback shouldDownload(_:). Przykład Apple dla zasobów adapterów:³

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

SystemLanguageModel.Adapter.isCompatible(_:) zwraca true dla pakietów zasobów, których adapter pasuje do bieżącego modelu systemowego. Ten sam callback może również przepuszczać zasoby inne niż adaptery, których aplikacja potrzebuje.

Wczytywanie i śledzenie pobierania

Gdy zasób znajduje się już na urządzeniu, ścieżka wczytywania wygląda następująco:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

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

Konstrukcja inicjuje pobieranie, jeśli urządzenie nie ma w pamięci podręcznej kompatybilnego adaptera. Uwaga Apple dotycząca UX: „Because adapters can have a large data size they can take some time to download, especially if a person is on Wi-Fi or a cell network. If a person doesn’t have a network connection, they aren’t able to use your adapter right away.”³

Sekwencja statusów pochodzi z 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: ...
        }
    }
}

Pięć udokumentowanych przypadków DownloadStatusUpdate: .began, .paused, .downloading, .finished, .failed.³ Gałąź @unknown default frameworka jest obowiązkowa, ponieważ Apple może dodać przypadki w przyszłych wersjach SDK.

Po osiągnięciu statusu .finished adapter jest gotowy do podpięcia do sesji:

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

Draft model i jego ograniczenie częstotliwości

Jeśli adapter został dostarczony z draft model, wywołanie adapter.compile() przygotowuje go do użycia. Dokumentacja Apple wyodrębnia ten krok jako osobny i kosztowny obliczeniowo:³

„The first time a device downloads a new version of your adapter, a call to compile() fully compiles your draft model and saves it to the device. During subsequent launches of your app, a call to compile() checks for a saved compiled draft model and returns it immediately if it exists.”

Istnieje opublikowane ograniczenie częstotliwości:³

„Rate limiting protects device resources that are shared between all apps and processes. If the framework determines that a new compilation is necessary, it rate-limits the compilation process on all platforms, excluding macOS, to three draft model compilations per-app, per-day.”

Wyjątek dla macOS jest interesujący; limit obowiązuje na iOS, iPadOS i visionOS. Apple zaleca uruchamianie kompilacji w zadaniu zaplanowanym przez Background Tasks, aby praca nie blokowała uruchamiania aplikacji.³

Pułapka deweloperska: „The full compilation process runs every time you launch your app through Xcode because Xcode assigns your app a new UUID for every launch. If you receive a rate-limiting error while testing your app, stop your app in Xcode and re-launch it to reset the rate counter.”³

Testowanie i ograniczenie symulatora

Testowanie adapterów wymaga fizycznego urządzenia. Apple stwierdza to wprost: „Testing adapters requires a physical device and isn’t supported on Simulator.”³

Do lokalnego testowania w Xcode inicjalizacja odbywa się z URL pliku, a nie z nazwy:³

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

Wzorzec Apple: zaimportować lokalny plik do testów, a następnie usunąć go z projektu przed publikacją aplikacji, ponieważ pliki adapterów są zbyt duże, aby je dołączać.³

Co ta ścieżka kosztuje w wymiarze operacyjnym

Składając razem cykl życia, aplikacja wdrażająca niestandardowy adapter zapisuje się na:

1. Infrastrukturę treningową w Python. Mac z Apple silicon i co najmniej 32 GB pamięci jako minimum, ewentualnie maszyna GPU z systemem Linux.²
2. Cykl ponownego trenowania zgodny z rytmem Apple. Każda aktualizacja modelu systemowego oznacza nowy adapter i nową wersję zestawu narzędzi.³
3. Stos serwujący. Albo asset packs hostowane przez Apple poprzez App Store Connect, albo własny serwer z integracją asset-downloader.³
4. Adaptery na każdą wersję w pamięci. Wiele wersji modelu bazowego w obiegu oznacza wiele hostowanych adapterów, a urządzenie pobiera ten pasujący.³
5. Bramę uprawnień. Account Holder członkostwa Apple Developer Program wnioskuje o nie; nie da się wdrożyć bez zatwierdzenia.²
6. Podatek 160 MB na wersję adaptera. Nie w pakiecie aplikacji, lecz na urządzeniu użytkownika po pobraniu.²
7. Testowanie na fizycznym urządzeniu. Symulator nie uruchamia adapterów.³

Tak wygląda koszt operacyjny w prostej formie. Korzyść, gdy sygnały adopcji są jednoznaczne, jest następująca: model na urządzeniu staje się wyspecjalizowany pod dane zadanie przy minimalnej liczbie promptów, niższej latencji, bez kosztów API za wywołanie i z pełną lokalnością danych. Dla aplikacji, które już ponoszą koszty dostrojonego serwerowego wnioskowania i chcą uzyskać parytet na urządzeniu, jest to wymiana na takich właśnie warunkach.

Wnioski

1. Adaptery to LoRA — zgodnie z udokumentowaną przez Apple techniką. Zamrożone wagi bazowe, małe trenowalne macierze przeplecione w sieci modelu, podczas trenowania aktualizowane są wyłącznie wagi adaptera.²
2. Jeden adapter na wersję modelu systemowego — bez wyjątków. Należy planować ponowne trenowanie powiązane z wydaniami systemu operacyjnego.³
3. Przepływ .fmadapter jest kompletny. Trenowanie w Python, pakowanie zestawem narzędzi, hosting jako Background Assets asset pack, wczytanie po nazwie w aplikacji, kompilacja draft model w zadaniu w tle.
4. Apple samo zaleca, by większość aplikacji nie szła tą ścieżką. Dwie odrębne strony dokumentacji Apple odradzają to dla większości zastosowań.¹ Warto przeczytać kryteria na stronie zestawu narzędzi; domyślną odpowiedzią jest „nie”.
5. Testowanie odbywa się na sprzęcie. Symulator nie uruchamia adapterów. Plan testowy należy budować wokół sesji na fizycznych urządzeniach oraz slotu kompilacyjnego frameworka Background Tasks.

Pełen klaster Apple Ecosystem: kryteria decyzyjne wbudowanej specjalizacji; protokół Tool w rdzeniu frameworka; podział agentowych przepływów pracy między LLMami w aplikacji a narzędziowymi; App Intents vs MCP w szerszym pytaniu o routing. Hub znajduje się w Apple Ecosystem Series. Szerszy kontekst iOS z agentami AI znajdą Państwo w iOS Agent Development guide.

FAQ

Skąd mam wiedzieć, czy moja aplikacja rzeczywiście potrzebuje niestandardowego adaptera?

Warto przeczytać sekcję „When to consider an adapter” w przewodniku zestawu narzędzi Apple.² Sygnały: istniejący dostrojony serwerowy LLM, który chce się odzwierciedlić na urządzeniu, udokumentowany pułap inżynierii promptów dla dokładności, twarde wymaganie zgodności z konkretnym stylem, formatem lub polityką, lub cel latencji, którego sama inżynieria promptów nie osiąga. Większość aplikacji nie spełnia żadnego z nich i Apple to wprost stwierdza.

Co tak naprawdę kontroluje uprawnienie?

Wdrożenie, nie trenowanie. Dokumentacja Apple stwierdza wprost: „You don’t need this entitlement to train or locally test adapters.”³ Account Holder członkostwa Apple Developer Program wnioskuje o com.apple.developer.foundation-model-adapter ze strony Foundation Models Framework Adapter Entitlement, a uprawnienie odblokowuje ścieżkę wdrożenia do App Store.²

Jak duże są adaptery i gdzie się znajdują?

Liczba podana w dokumentacji Apple: „Each adapter will take approximately 160 MB of storage space in your app.”² Adaptery nie znajdują się w pakiecie aplikacji. Apple kieruje je przez Background Assets, hostowane na serwerach Apple (managed) lub na własnym serwerze (managed lub unmanaged), a urządzenie pobiera wersję pasującą do swojego bieżącego modelu systemowego.³

Co się stanie, gdy Apple zaktualizuje model bazowy?

Należy ponownie wytrenować. Z dokumentacji: „Each adapter is compatible with a single specific system model version. You must train a new adapter for every new base model version. A runtime error occurs if your app runs on a person’s device without a compatible adapter.”³ W praktyce stos serwujący hostuje wiele wersji adapterów równocześnie, a urządzenie pobiera właściwą na podstawie isCompatible(_:).

Jaki jest związek między adapterami a .contentTagging?

.contentTagging to jedna z dwóch statycznych właściwości SystemLanguageModel.UseCase udostępnianych przez Apple, omówiona w artykule towarzyszącym. Jest to specjalizacja zarządzana przez Apple, niewymagająca żadnego uprawnienia, dołączona do frameworka. Niestandardowy Adapter to ekwiwalent zarządzany przez dewelopera dla zadań, których przypadki użycia Apple nie obejmują. Dokumentacja Apple używa słowa „adapted” przy opisie wewnętrznego działania .contentTagging, ale nie jest to to samo co formalny typ Adapter. Formalny typ jest tym, którym zajmuje się ten artykuł.

Czy muszę trenować draft model?

Nie. Dokumentacja Apple: „If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.”² Adapter nadal się wczytuje i obsługuje zapytania; po prostu nie uzyska się przyspieszenia wnioskowania dzięki speculative decoding. Draft model to opcjonalny drugi przebieg trenowania.

Odniesienia