Foundation Models Custom Adapters: Der Lebenszyklus, von dem Apple abrät

Der Typ SystemLanguageModel.Adapter ermöglicht es einer App, individuell trainierte Gewichte in das geräteinterne Sprachmodell von Apple zu laden.¹ Das Framework unterstützt dies. Apple liefert ein Trainings-Toolkit aus. Es gibt eine dokumentierte Berechtigung, ein .fmadapter-Paketformat und eine Background-Assets-Integration, um den passenden Adapter für das passende Gerät herunterzuladen.

Apples eigene Dokumentation zum selben Typ besagt zudem wörtlich: „Adapters consume a large amount of storage space and isn’t recommended for most apps.”¹ Der frühere Beitrag in diesem Cluster, Foundation Models Use Cases, behandelte die Pfade, die die meisten Apps einschlagen sollten. Dieser Beitrag ist die dritte Schiene: der operative Lebenszyklus von Training, Verpackung und Auslieferung eines Custom Adapters – und Apples ausdrückliche Empfehlung, wann man darauf verzichten sollte.

TL;DR

• Ein Custom Adapter ist eine LoRA-trainierte Gewichtsmatrix, die das geräteinterne System-Sprachmodell überlagert.² Apples Toolkit bestätigt die Technik namentlich.
• Jeder Adapter ist an eine einzige Version des Systemmodells gebunden. Wenn Apple das Basismodell aktualisiert, müssen Sie den Adapter neu trainieren.³
• Apples Empfehlung lautet in eigenen Worten: „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.”¹
• Adapter-Assets sind groß (~160 MB), werden über Background Assets gebündelt und durch eine Berechtigung (com.apple.developer.foundation-model-adapter) abgesichert, die der Account Holder einer Apple Developer Program-Mitgliedschaft für die Bereitstellung beantragt.³
• Der Pfad ergibt für eine schmale Auswahl an Apps Sinn: solche, die ein feinjustiertes serverseitiges LLM auf dem Gerät replizieren, solche mit strengen Anforderungen an Stil-, Format- oder Richtlinientreue, oder solche mit dokumentierten Prompt-Engineering-Obergrenzen für ihre Zielaufgabe.²

Was ein Adapter tatsächlich ist

SystemLanguageModel.Adapter ist ein struct, verfügbar unter iOS, iPadOS, Mac Catalyst, macOS und visionOS, jeweils ab Version 26.0+.⁴ Apples Beschreibung des Typs:

„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.”⁴

Der Mechanismus ist dokumentiert. Apples Adapter-Trainingsleitfaden besagt es direkt:²

„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 ist eine öffentliche Technik mit einer veröffentlichten Forschungshistorie.⁵ Apples Beitrag besteht aus dem Toolkit, dem .fmadapter-Paketformat, der geräteinternen Laufzeitumgebung, die den Adapter lädt, sowie der Lebenszyklus-Infrastruktur, um ihn über Background Assets auszuliefern.

Die API-Oberfläche des Typs

Das Adapter-Struct legt eine kleine Oberfläche offen:⁴

• init(fileURL: URL) throws: „Creates an adapter from the file URL.” Wird für lokale Tests in Xcode genutzt.
• init(name: String) throws: „Creates an adapter downloaded from the background assets framework.” Wird in der Produktion genutzt.
• 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]: Werte aus dem ersteller-definierten Feld der Metadaten.
• static func removeObsoleteAdapters() throws: entfernt Adapter, die nicht mehr zu einem aktuellen Systemmodell passen.
• static func compatibleAdapterIdentifiers(name: String) -> [String]: ruft die IDs kompatibler Adapter-Asset-Pakete ab.
• enum AssetError: Fehlertyp für Asset-bezogene Fehlschläge.

SystemLanguageModel verfügt über einen passenden Initialisierer für Adapter: convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails) mit der Beschreibung „Creates the base version of the model with an adapter.”⁶

Der reine Bereitstellungs-Berechtigungsschlüssel lautet com.apple.developer.foundation-model-adapter: „A Boolean value that indicates whether the app can enable custom adapters for the Foundation Models framework.”⁶ Für das Training oder lokale Tests in Xcode brauchen Sie ihn nicht; vor der Auslieferung an den App Store hingegen schon.³

Apples Rubrik „Wann sollte man einen Adapter erwägen”

Die Toolkit-Seite legt konkrete Adoptionssignale dar:²

• „You have a dataset suitable for use with an LLM” oder Sie nutzen bereits ein feinjustiertes serverbasiertes LLM und möchten geräteinterne Parität.
• „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.”

Derselbe Leitfaden listet auch die Kosten auf, die Sie übernehmen:²

• Einen Datensatz aus Prompt-Antwort-Paaren, die Ihre Zielfähigkeit demonstrieren.
• Einen Prozess zur Bewertung der Qualität Ihrer Adapter.
• Einen Prozess zum Laden Ihrer Adapter aus einem Server in Ihre App.

Und die Speichersteuer: „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.”²

Die Empfehlung des Frameworks, von Apple an zwei separaten Stellen wiederholt, lautet, standardmäßig auf Prompt Engineering kombiniert mit Tool Calling zu setzen und nur dann zu Adaptern zu greifen, wenn die obige Rubrik freie Bahn signalisiert.

Training, in Apples Form

Die Trainings-Pipeline ist Python. Apples Toolkit liefert Beispielcode, die Modell-Assets passend zu einer bestimmten Systemmodell-Version, Datensatz-Werkzeuge sowie den Exportschritt, der ein .fmadapter-Paket erzeugt.²

Hardware-Anforderungen: „Mac with Apple silicon and at least 32GB memory, or Linux GPU machines.” Python 3.11 oder neuer.²

Datensatzform:²

• Format ist jsonl mit Feldern role ("user" oder "assistant") und content.
• 100 bis 1.000 Stichproben für einfache Aufgaben.
• 5.000+ Stichproben für komplexe Aufgaben.
• Eine Schema.md im Toolkit deckt das vollständige Schema ab, einschließlich Felder für Guided Generation und KI-Sicherheits-Hooks.

Apples Hinweis zur Datenqualität ist zitierwürdig: „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.”²

Das Training wird über den Einstiegspunkt train_adapter des Toolkits aufgerufen:

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/

Optional können Sie nach dem Adapter-Training ein passendes Draft Model trainieren.² Ein Draft Model ist eine kleinere Version des System-Basismodells, die spekulative Dekodierung ermöglicht – eine veröffentlichte Technik zur Inferenz-Beschleunigung.⁷ Apples Formulierung: „If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.”²

Die Single-Version-Beschränkung

Die operativ folgenreichste Tatsache an Adaptern ist die Bindung an eine bestimmte Systemmodell-Version:³

„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.”

Das Toolkit ist parallel zum Modell versioniert. Zum Zeitpunkt des Schreibens hat Apple zwei Beta-Toolkit-Versionen ausgeliefert (Beta 0.1.0 und Beta 0.2.0, beide entfernt) sowie ein Vollrelease: 26.0.0.² Apples Aussage zum Release-Rhythmus: „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).”²

Die operative Konsequenz: App-Teams, die Adapter ausliefern, abonnieren einen Modell-Aktualisierungs-Lebenszyklus, der nach Apples Takt läuft. Jeder Sprung der Basismodell-Version ist eine erzwingende Funktion für Neutraining, Neubewertung und Neuveröffentlichung.

Verpackung als Asset Packs

Die Adapter-Datei ist groß genug, dass das Bündeln in der App ausdrücklich abgeraten wird. Apple leitet die Adapter-Auslieferung über Background Assets.³

Das Toolkit erzeugt .fmadapter-Pakete, die das Toolkit zudem als Background-Assets-Asset-Packs bündelt. Das Befehlszeilen-Werkzeug ba-package aus Xcode 16 oder neuer übernimmt die Bündelungsarbeit; das Toolkit ruft es intern auf.³

Hosting-Optionen:³

• Apple-Hosted, Managed. Apple hostet das Asset; das Betriebssystem verwaltet den Download-Lebenszyklus.
• Self-Hosted, Managed. Sie hosten auf Ihrem Server; das Betriebssystem verwaltet den Download-Lebenszyklus.
• Self-Hosted, Unmanaged. Sie hosten und verwalten den Lebenszyklus selbst.

Die erforderlichen Info.plist-Schlüssel unterscheiden sich je nach Hosting-Wahl:³ Apple-Hosted Managed benötigt BAHasManagedAssetPacks, BAAppGroupID und BAUsesAppleHosting; Self-Hosted Managed benötigt die ersten beiden; Self-Hosted Unmanaged benötigt keinen davon. Jeder Pfad hat zudem ein Asset-Downloader-Extension-Target, das Xcode generiert.

Den richtigen Adapter zur Laufzeit auswählen

Wenn die Datei BackgroundDownloadHandler.swift der Asset-Downloader-Extension generiert wird, verdrahtet Xcode einen shouldDownload(_:)-Callback. Apples Beispiel-Implementierung für Adapter-Assets:³

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

SystemLanguageModel.Adapter.isCompatible(_:) gibt true für Asset Packs zurück, deren Adapter zum aktuellen Systemmodell passt. Derselbe Callback kann auch Nicht-Adapter-Assets durchreichen, die Ihre App benötigt.

Downloads laden und verfolgen

Sobald das Asset auf dem Gerät liegt, sieht der Lade-Pfad so aus:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

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

Die Konstruktion stößt einen Download an, falls das Gerät keinen kompatiblen Adapter zwischengespeichert hat. Apples Hinweis zur 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.”³

Die Status-Sequenz stammt aus 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: ...
        }
    }
}

Die fünf dokumentierten DownloadStatusUpdate-Fälle: .began, .paused, .downloading, .finished, .failed.³ Der @unknown default-Zweig des Frameworks ist verpflichtend, da Apple in zukünftigen SDK-Versionen weitere Fälle hinzufügen kann.

Sobald der Status .finished erreicht, ist der Adapter bereit, in eine Session eingehängt zu werden:

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

Das Draft Model und sein Rate-Limit

Falls Ihr Adapter mit einem Draft Model ausgeliefert wurde, bereitet ein Aufruf von adapter.compile() es zur Nutzung vor. Apples Dokumentation hebt dies als separaten, rechenintensiven Schritt hervor:³

„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.”

Es gibt ein veröffentlichtes Rate-Limit:³

„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.”

Der macOS-Ausschluss ist interessant; das Limit gilt unter iOS, iPadOS und visionOS. Apple empfiehlt, die Kompilierung innerhalb eines durch Background Tasks geplanten Tasks laufen zu lassen, damit die Arbeit den App-Start nicht blockiert.³

Eine Entwicklungs-Falle: „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.”³

Tests und die Simulator-Beschränkung

Adapter-Tests erfordern ein physisches Gerät. Apple ist eindeutig: „Testing adapters requires a physical device and isn’t supported on Simulator.”³

Für lokale Tests in Xcode initialisieren Sie über eine Datei-URL statt über einen Namen:³

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

Apples Muster: die lokale Datei zum Testen importieren, dann vor der Veröffentlichung der App aus dem Projekt entfernen, da Adapter-Dateien zu groß zum Bündeln sind.³

Was dieser Pfad operativ kostet

Setzt man den Lebenszyklus zusammen, verpflichtet sich eine App, die einen Custom Adapter ausliefert, zu Folgendem:

1. Python-Trainingsinfrastruktur. Mindestens ein Mac mit Apple silicon und 32 GB Speicher oder eine Linux-GPU-Maschine.²
2. Eine Neutrainings-Kadenz nach Apples Takt. Jede Aktualisierung des Systemmodells bedeutet einen frischen Adapter und eine frische Toolkit-Version.³
3. Einen Auslieferungs-Stack. Entweder Apple-gehostete Asset Packs über App Store Connect oder Ihr eigener Server mit einer Asset-Downloader-Integration.³
4. Adapter pro Version im Speicher. Mehrere Basismodell-Versionen im Feld bedeuten mehrere gehostete Adapter, wobei das Gerät den passenden zieht.³
5. Ein Berechtigungs-Tor. Der Account Holder Ihrer Apple Developer Program-Mitgliedschaft beantragt sie; ohne Genehmigung können Sie nicht ausliefern.²
6. Die 160-MB-Steuer pro Adapter-Version. Nicht im App Bundle, aber nach dem Download auf dem Gerät des Benutzers.²
7. Tests auf physischen Geräten. Der Simulator führt keine Adapter aus.³

So sieht der operative Aufwand in klarer Form aus. Der Nutzen, sobald die Adoptionssignale freie Bahn geben, ist: Das geräteinterne Modell wird mit minimalem Prompting für Ihre Aufgabe spezialisiert, geringere Latenz, keine API-Kosten pro Aufruf und vollständige Datenlokalität. Für Apps, die bereits für feinjustierte serverseitige Inferenz bezahlen und geräteinterne Parität wünschen, ist das der Tausch in klarer Form.

Erkenntnisse

1. Adapter sind LoRA, gemäß Apples dokumentierter Technik. Eingefrorene Basisgewichte, kleine trainierbare Matrizen durch das Modellnetzwerk hindurch, nur die Adapter-Gewichte werden während des Trainings aktualisiert.²
2. Ein Adapter pro Systemmodell-Version, ohne Ausnahme. Planen Sie Neutraining gebunden an OS-Releases ein.³
3. Der .fmadapter-Workflow ist End-to-End. Training in Python, Verpacken mit dem Toolkit, Hosten als Background-Assets-Asset-Pack, Laden über Namen in Ihrer App, Kompilieren des Draft Models in einem Hintergrund-Task.
4. Apple selbst empfiehlt den meisten Apps, diesen Pfad nicht zu gehen. Zwei separate Apple-Dokumentationsseiten raten für die meisten Anwendungsfälle davon ab.¹ Lesen Sie die Rubrik auf der Toolkit-Seite; die Antwort lautet standardmäßig „nein”.
5. Testen Sie auf Hardware. Der Simulator führt keine Adapter aus. Bauen Sie den Testplan rund um Sitzungen auf physischen Geräten und den Kompilierungs-Slot des Background Tasks-Frameworks auf.

Das vollständige Apple Ecosystem-Cluster: die Entscheidungs-Rubrik für eingebaute Spezialisierung; das Tool-Protokoll im Kern des Frameworks; die Aufteilung agentischer Workflows zwischen In-App- und Tooling-LLMs; App Intents vs MCP für die übergreifende Routing-Frage. Der Hub befindet sich unter der Apple Ecosystem Series. Für breiteren Kontext zu iOS mit AI-Agenten siehe den iOS Agent Development guide.

FAQ

Wie weiß ich, ob meine App tatsächlich einen Custom Adapter benötigt?

Lesen Sie Apples Abschnitt „When to consider an adapter” im Toolkit-Leitfaden.² Die Signale: ein bestehendes feinjustiertes serverseitiges LLM, das Sie auf dem Gerät spiegeln möchten, eine dokumentierte Prompt-Engineering-Obergrenze bei der Genauigkeit, eine harte Anforderung an spezifische Stil-, Format- oder Richtlinientreue oder ein Latenzziel, das Prompt Engineering allein verfehlt. Die meisten Apps erfüllen keines davon, und Apple sagt das auch so.

Was reguliert die Berechtigung tatsächlich?

Die Bereitstellung, nicht das Training. Apples Dokumentation stellt es ausdrücklich fest: „You don’t need this entitlement to train or locally test adapters.”³ Der Account Holder Ihrer Apple Developer Program-Mitgliedschaft beantragt com.apple.developer.foundation-model-adapter von der Foundation Models Framework Adapter Entitlement-Seite, und die Berechtigung gibt den Weg zur Auslieferung an den App Store frei.²

Wie groß sind Adapter und wo liegen sie?

Apples dokumentierte Größenangabe: „Each adapter will take approximately 160 MB of storage space in your app.”² Adapter liegen nicht im App Bundle. Apple leitet sie über Background Assets, gehostet entweder auf Apple-Servern (managed) oder Ihrem eigenen Server (managed oder unmanaged), und das Gerät lädt die Version herunter, die zu seinem aktuellen Systemmodell passt.³

Was passiert, wenn Apple das Basismodell aktualisiert?

Sie trainieren neu. Aus den Dokumenten: „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.”³ In der Praxis hostet Ihr Auslieferungs-Stack mehrere Adapter-Versionen gleichzeitig und das Gerät zieht die richtige basierend auf isCompatible(_:).

Wie ist das Verhältnis zwischen Adaptern und .contentTagging?

.contentTagging ist eine von zwei statischen SystemLanguageModel.UseCase-Eigenschaften, die Apple ausliefert, behandelt im Begleitbeitrag. Es ist eine von Apple verwaltete Spezialisierung, ohne Berechtigungssperre, im Framework enthalten. Ein Custom Adapter ist das vom Entwickler verwaltete Äquivalent für Aufgaben, die Apples Use Cases nicht abdecken. Apples Dokumente verwenden das Wort „adapted”, wenn beschrieben wird, wie .contentTagging intern funktioniert, aber das ist nicht dasselbe wie der formale Adapter-Typ. Den formalen Typ behandelt dieser Beitrag.

Muss ich ein Draft Model trainieren?

Nein. Apples Dokumente: „If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.”² Der Adapter lädt und arbeitet weiterhin; Sie erhalten lediglich nicht den Inferenz-Geschwindigkeitsvorteil durch Speculative Decoding. Das Draft Model ist ein optionaler zweiter Trainingsdurchlauf.

Referenzen