Foundation Models Custom Adapters: Wann sich ein eigenes Training lohnt

Apples Adapter-Dokumentation steckt den Pfad eng ab: Verwenden Sie das Basis-Systemmodell für die meiste Prompt-Engineering-Arbeit, Guided Generation und Tools; trainieren Sie nur dann einen eigenen Adapter, wenn die Aufgabe eine Spezialisierung der Modellgewichte erfordert und das Team mit Python-basiertem Modelltraining vertraut ist.¹⁴

Apples eigene Dokumentation zum selben Typ zitiert 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, beleuchtete die Schienen, auf denen die meisten Apps fahren sollten. Dieser Beitrag ist die dritte Schiene: der operative Lebenszyklus von Training, Paketierung und Auslieferung eines eigenen Adapters – und Apples ausdrückliche Hinweise dazu, wann man darauf verzichten sollte.

TL;DR

• Apples Toolkit identifiziert die Trainingsmethode als LoRA: Die Basisgewichte bleiben eingefroren, während die Adapter-Gewichte trainiert werden.²
• Jeder Adapter ist an eine einzelne Systemmodellversion gebunden. Wenn Apple das Basismodell aktualisiert, trainieren Sie den Adapter neu.³
• Apples Empfehlung im Wortlaut: „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-Dateien sind groß, sollten nicht im Haupt-App-Bundle ausgeliefert werden und werden bei Bedarf über gehostete Asset Packs und Background Assets bereitgestellt.²³
• Apple sagt, Adapter sollten erst dann in Betracht gezogen werden, wenn Prompt Engineering oder Tool Calling die Aufgabe nicht erfüllen, oder wenn ein bestehender, feinabgestimmter Server-LLM, fachliche Expertise, Stil-/Format-/Richtlinientreue oder ein Latenzziel die Kosten rechtfertigt.²

Was ein Adapter tatsächlich ist

SystemLanguageModel.Adapter ist ein struct, verfügbar auf iOS, iPadOS, Mac Catalyst, macOS und visionOS, jeweils 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-Trainings-Leitfaden formuliert 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 veröffentlichter Paper-Historie.⁵ Apples dokumentierte Oberfläche umfasst das Toolkit, den .fmadapter-Export, das Asset-Pack-Bundling, die Auslieferung über Background Assets und das Laden zur Laufzeit über SystemLanguageModel.Adapter.²³⁴

Die API-Oberfläche des Typs

Apple listet diese Adapter-Oberfläche:⁴

• init(fileURL: URL) throws: „Creates an adapter from the file URL.”
• init(name: String) throws: „Creates an adapter downloaded from the background assets framework.”
• 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]: „Values read from the creator defined field of the adapter’s metadata.”
• static func removeObsoleteAdapters() throws: „Remove all obsolete adapters that are no longer compatible with current system models.”
• static func compatibleAdapterIdentifiers(name: String) -> [String]: „Get all compatible adapter identifiers compatible with current system models.”
• enum AssetError: Fehlertyp für asset-bezogene Fehlschläge.

SystemLanguageModel verfügt über einen passenden Initializer 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 ausschließlich für die Auslieferung vorgesehene Entitlement-Schlü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.”⁶ Sie benötigen ihn weder für das Training noch für lokale Tests in Xcode; vor der Auslieferung in den App Store benötigen Sie ihn jedoch.³

Apples Rubrik „Wann ein Adapter zu erwägen ist”

Die Toolkit-Seite legt konkrete Adoptionssignale dar:²

• „You have a dataset suitable for use with an LLM” oder Sie verwenden bereits ein feinabgestimmtes serverbasiertes LLM und wünschen sich On-Device-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 damit übernehmen:²

• Ein Datensatz aus Prompt-Antwort-Paaren, der Ihre Zielfähigkeit demonstriert.
• Ein Prozess zur Bewertung der Qualität Ihrer Adapter.
• Ein Prozess, um Ihre Adapter aus einem Server in Ihre App zu laden.

Und die Speicherabgabe: „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 verschiedenen Stellen wiederholt, lautet: standardmäßig auf Prompt Engineering plus Tool Calling setzen und nur dann zu Adaptern greifen, wenn die obige Rubrik passt.

Training, in Apples Form

Apple sagt, das Toolkit enthält Python-Beispielcode, Modell-Assets für eine bestimmte Systemmodellversion, .fmadapter-Exportwerkzeuge und Asset-Pack-Bundling-Werkzeuge.²

Datensatzanforderungen sind jsonl-Prompt-/Antwort-Paare, etwa 100 bis 1.000 Samples für einfache Aufgaben und 5.000+ für komplexe Aufgaben. Schema.md deckt Guided Generation und KI-Sicherheitsfelder ab.²

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

Apples Datenqualitätsregel ist einfach: Qualität schlägt Quantität.²

Das Training wird über den train_adapter-Einstiegspunkt 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 Training des Adapters ein passendes Draft-Modell trainieren.² Ein Draft-Modell ist eine kleinere Version des System-Basismodells, das Speculative Decoding ermöglicht – eine veröffentlichte Technik zur Beschleunigung der Inferenz.⁷ Apples Formulierung: „If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.”²

Die Einzelversions-Beschränkung

Die operativ folgenreichste Tatsache zu Adaptern ist die Bindung an eine bestimmte Systemmodellversion:³

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

Abgerufen am 4. Mai 2026 listet Apples Toolkit-Tabelle Beta 0.1.0 und Beta 0.2.0 als entfernt und 26.0.0 als erste vollwertige Toolkit-Version. Apples Kadenzregel lautet: ein Toolkit pro Systemmodell-Update.² Vollständige Aussage: „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-Update-Lebenszyklus, der nach Apples Kadenz läuft. Jeder Sprung des Basismodells ist ein erzwingender Anlass für Neutraining, Neubewertung und Neuveröffentlichung.

Paketierung als Asset Packs

Apples Regel: Adapter-Dateien sind zu groß für das App-Bundle; hosten Sie sie über App Store Connect oder Ihren Server, und laden Sie dann den geräteseitig kompatiblen Adapter bei Bedarf herunter.³

Das Toolkit erzeugt .fmadapter-Pakete, die das Toolkit auch als Background-Assets-Asset-Packs bündelt. Das ba-package-Kommandozeilenwerkzeug aus Xcode 16 oder neuer übernimmt das Bundling; das Toolkit ruft es auf.³

Hosting-Optionen:³

• Apple-Hosted, Managed. Apple hostet das Asset; das OS verwaltet den Download-Lebenszyklus.
• Self-Hosted, Managed. Sie hosten auf Ihrem Server; das OS 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 BackgroundDownloadHandler.swift der Asset-Downloader-Extension generiert wird, verdrahtet Xcode einen shouldDownload(_:)-Callback. Apples Beispielimplementierung für Adapter-Assets:³

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

Apples Beispiel ist die einzige dokumentierte Laufzeitprüfung. Der Ausdruck SystemLanguageModel.Adapter.isCompatible(assetPack) ist das, was das Beispiel für Adapter-Asset-Packs zurückgibt; behandeln Sie den Aufruf als undurchsichtig, soweit das Beispiel nichts anderes zeigt.³

Downloads laden und verfolgen

Sobald sich das Asset auf dem Gerät befindet, lautet der Ladepfad:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

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

Die Konstruktion stößt einen Download an, falls auf dem Gerät kein kompatibler Adapter zwischengespeichert ist. 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 Statussequenz kommt vom 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, weil Apple in zukünftigen SDK-Versionen 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-Modell und sein Rate Limit

Wenn Ihr Adapter mit einem Draft-Modell ausgeliefert wurde, bereitet ein Aufruf von adapter.compile() es zur Verwendung 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.”

Das Rate Limit schließt macOS aus; auf anderen Plattformen ist die neue Draft-Modell-Kompilierung auf drei Kompilierungen pro App pro Tag beschränkt.³ Apple empfiehlt, die Kompilierung in einer über Background Tasks geplanten Aufgabe auszuführen, damit die Arbeit den App-Start nicht blockiert.³

Apples Warnung zum Testen in Xcode: Ein Start über Xcode ändert die App-UUID, sodass bei jedem Start eine vollständige Kompilierung läuft, was das Rate Limit auslösen kann.³

Tests und die Simulator-Beschränkung

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

Für lokale Tests in Xcode initialisieren Sie aus einer Datei-URL anstelle eines Namens:³

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

Für die Veröffentlichung sagt Apple, Adapter-Dateien nur für lokale Tests zu importieren, sie dann vor der Veröffentlichung zu entfernen und Adapter bei Bedarf herunterzuladen.³

Was Sie dieser Pfad operativ kostet

Wenn man den Lebenszyklus zusammensetzt, verpflichtet sich eine App, die einen eigenen Adapter ausliefert, zu Folgendem:

1. Python-Trainingsinfrastruktur. Mindestens ein Mac mit Apple Silicon und 32 GB Arbeitsspeicher oder eine Linux-GPU-Maschine.²
2. Eine Neutraining-Kadenz nach Apples Takt. Jedes Systemmodell-Update bedeutet einen frischen Adapter und eine frische Toolkit-Version.³
3. Ein Auslieferungsstack. 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 Basismodellversionen im Feld bedeuten mehrere gehostete Adapter, wobei das Gerät den passenden zieht.³
5. Ein Entitlement-Tor. Der Account Holder Ihrer Apple-Developer-Program-Mitgliedschaft beantragt es; ohne Genehmigung können Sie nicht ausliefern.²
6. Die 160-MB-Abgabe pro Adapter-Version. Nicht im App-Bundle, aber auf dem Gerät des Benutzers nach dem Download.²
7. Tests auf physischem Gerät. Der Simulator führt keine Adapter aus.³

Das sind die operativen Kosten in klarer Form. Der Nutzen, wenn die Adoptionssignale passen, ist: Das On-Device-Modell wird mit minimalem Prompting und niedrigerer Latenz auf die Aufgabe spezialisiert. Für Apps, die bereits für feinabgestimmte serverseitige Inferenz zahlen und sich On-Device-Parität wünschen, ist das der Tausch in klaren Worten.

Erkenntnisse

1. Adapter sind LoRA, nach Apples dokumentierter Technik. Eingefrorene Basisgewichte, kleine trainierbare Matrizen durch das Modellnetz, beim Training werden nur die Adapter-Gewichte aktualisiert.²
2. Ein Adapter pro Systemmodellversion, ohne Ausnahme. Planen Sie das Neutraining gekoppelt an OS-Releases.³
3. Der .fmadapter-Workflow ist durchgängig. Trainieren Sie in Python, paketieren Sie mit dem Toolkit, hosten Sie als Background-Assets-Asset-Pack, laden Sie in Ihrer App per Namen und kompilieren Sie das Draft-Modell in einer Hintergrundaufgabe.
4. Apple selbst empfiehlt, dass die meisten Apps diesen Pfad nicht 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 Sessions auf physischen Geräten und den Kompilierungsslot des Background Tasks-Frameworks.

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 übergeordnete Routing-Frage. Der Hub liegt in der Apple Ecosystem Series. Für breiteren Kontext zu iOS mit KI-Agenten siehe den iOS Agent Development Guide.

FAQ

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

Apple empfiehlt das Basismodell für die meisten Prompt-Engineering-Aufgaben, Guided Generation und Tools, und der Toolkit-Leitfaden besagt, dass Adapter steile Trainings- und Neutrainingsanforderungen mit sich bringen. Die Standardantwort ist nein – es sei denn, Apples Adapter-Signale treffen zu.²⁴

Was begrenzt das Entitlement tatsächlich?

Apple dokumentiert das Entitlement als erforderlich beim Ausliefern von Adaptern, nicht für Training oder lokale Tests.²³

Wie groß sind Adapter und wo liegen sie?

Apples dokumentierte Zahl: „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 weiter, 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?

Wenn Apple das Basismodell aktualisiert, trainieren Sie einen kompatiblen Adapter für diese Modellversion; andernfalls kann die App auf einem Gerät ohne kompatiblen Adapter zur Laufzeit fehlschlagen.²³

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

.contentTagging wird von Apple verwaltet und ist ins Framework eingebaut: ein intern spezialisierter Anwendungsfall, nicht der formale Adapter-Typ, den ein Entwickler trainiert. Der formale Typ ist das, was dieser Beitrag behandelt; die Anwendungsfälle werden im begleitenden Beitrag behandelt.

Muss ich ein Draft-Modell trainieren?

Apple dokumentiert nur diese Konsequenz, wenn man das Draft-Modell-Training überspringt: Speculative Decoding ist für diesen Adapter-Anwendungsfall nicht verfügbar.²

Referenzen