Adaptateurs personnalisés Foundation Models : quand en entraîner un

La documentation d’Apple sur les adaptateurs définit la voie de manière étroite : utilisez le modèle système de base pour la majeure partie de l’ingénierie de prompts, de la génération guidée et des outils, et n’entraînez un Adapter personnalisé que lorsque la tâche nécessite une spécialisation des poids du modèle et que l’équipe est à l’aise avec l’entraînement de modèles Python.¹⁴

La documentation d’Apple elle-même sur ce même type cite textuellement : « Les adaptateurs consomment une grande quantité d’espace de stockage et ne sont pas recommandés pour la plupart des applications. »¹ L’article précédent de ce cluster, Foundation Models Use Cases, couvrait les rails que la plupart des applications devraient emprunter. Cet article est le troisième rail : le cycle de vie opérationnel de l’entraînement, du packaging et de la livraison d’un adaptateur personnalisé, ainsi que les recommandations explicites d’Apple sur les cas où il ne faut pas le faire.

TL;DR

• Le toolkit d’Apple identifie la méthode d’entraînement comme étant LoRA : les poids de base restent gelés tandis que les poids de l’adaptateur sont entraînés.²
• Chaque adaptateur est lié à une seule version de modèle système. Lorsque Apple met à jour le modèle de base, vous devez réentraîner l’adaptateur.³
• La recommandation d’Apple, dans ses propres mots : « Utilisez le modèle système de base pour la majeure partie de l’ingénierie de prompts, de la génération guidée et des outils. Si vous devez spécialiser le modèle, entraînez un Adapter personnalisé… N’utilisez les adaptateurs personnalisés que si vous êtes à l’aise avec l’entraînement de modèles de fondation en Python. »¹
• Les fichiers d’adaptateurs sont volumineux, ne devraient pas être livrés dans le bundle principal de l’application et sont distribués à la demande via des asset packs hébergés et Background Assets.²³
• Apple recommande de n’envisager les adaptateurs qu’après l’échec de l’ingénierie de prompts ou de l’appel d’outils sur la tâche, ou lorsqu’un LLM serveur fine-tuné existant, une expertise spécifique au domaine, le respect du style/format/politique ou un objectif de latence justifient le coût.²

Ce qu’est réellement un adaptateur

SystemLanguageModel.Adapter est une struct, disponible sur iOS, iPadOS, Mac Catalyst, macOS et visionOS, tous en version 26.0+.⁴ Description du type par Apple :

« Utilisez le modèle système de base pour la majeure partie de l’ingénierie de prompts, de la génération guidée et des outils. Si vous devez spécialiser le modèle, entraînez un Adapter personnalisé pour modifier les poids du modèle système et l’optimiser pour votre tâche personnalisée. N’utilisez les adaptateurs personnalisés que si vous êtes à l’aise avec l’entraînement de modèles de fondation en Python. »⁴

Le mécanisme est documenté. Le guide d’entraînement d’adaptateurs d’Apple le formule directement :²

« Le modèle système utilise une approche de fine-tuning à paramètres efficaces (PEFT) connue sous le nom de LoRA (Low-Rank Adaptation). Avec LoRA, les poids du modèle d’origine sont gelés, et de petites matrices de poids entraînables appelées “adaptateurs” sont intégrées dans le réseau du modèle. Pendant l’entraînement, seuls les poids de l’adaptateur sont mis à jour, ce qui réduit considérablement le nombre de paramètres à entraîner. »

LoRA est une technique publique avec un historique de publications.⁵ La surface documentée par Apple est le toolkit, l’export .fmadapter, le bundling en asset packs, la livraison via Background Assets et le chargement à l’exécution via SystemLanguageModel.Adapter.²³⁴

La surface API du type

Apple liste la surface suivante pour Adapter :⁴

• init(fileURL: URL) throws : « Crée un adaptateur à partir de l’URL du fichier. »
• init(name: String) throws : « Crée un adaptateur téléchargé depuis le framework background assets. »
• func compile() async throws : « Prépare un adaptateur avant son utilisation avec une LanguageModelSession. Vous devez l’appeler si votre adaptateur a un draft model. »
• var creatorDefinedMetadata: [String : Any] : « Valeurs lues depuis le champ creator defined des métadonnées de l’adaptateur. »
• static func removeObsoleteAdapters() throws : « Supprime tous les adaptateurs obsolètes qui ne sont plus compatibles avec les modèles système actuels. »
• static func compatibleAdapterIdentifiers(name: String) -> [String] : « Récupère tous les identifiants d’adaptateurs compatibles avec les modèles système actuels. »
• enum AssetError : type d’erreur pour les défaillances liées aux assets.

SystemLanguageModel dispose d’un initialiseur jumelé pour les adaptateurs : convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails), avec la description « Crée la version de base du modèle avec un adaptateur. »⁶

La clé d’entitlement réservée au déploiement est com.apple.developer.foundation-model-adapter : « Une valeur booléenne qui indique si l’application peut activer des adaptateurs personnalisés pour le framework Foundation Models. »⁶ Vous n’en avez pas besoin pour l’entraînement ni pour les tests locaux dans Xcode ; vous en avez besoin avant de publier sur l’App Store.³

Le critère d’Apple « quand envisager un adaptateur »

La page du toolkit énonce des signaux d’adoption concrets :²

• « Vous avez un dataset adapté à l’utilisation avec un LLM » ou vous utilisez déjà un LLM serveur fine-tuné et souhaitez la parité on-device.
• « Vous avez besoin que le modèle devienne un expert du domaine. »
• « Vous avez besoin que le modèle adhère à un style, un format ou une politique spécifique. »
• « L’ingénierie de prompts n’atteint pas la précision ou la cohérence requise pour votre tâche. »
• « Vous voulez une latence inférieure à l’inférence. Si vos solutions basées sur l’ingénierie de prompts nécessitent de longs prompts avec des exemples pour chaque appel, un adaptateur spécialisé pour cette tâche offre une saisie minimale. »

Le même guide énumère également les coûts que vous endossez :²

• Un dataset de paires prompt-réponse qui démontrent votre compétence cible.
• Un processus d’évaluation de la qualité de vos adaptateurs.
• Un processus pour charger vos adaptateurs dans votre application depuis un serveur.

Et la taxe de stockage : « Chaque adaptateur occupera environ 160 Mo d’espace de stockage dans votre application. Comme les autres gros assets, les adaptateurs ne doivent pas faire partie du bundle principal de votre application, car avec plusieurs versions d’adaptateurs, votre application deviendra trop volumineuse pour que les utilisateurs puissent l’installer. »²

La recommandation du framework, reformulée par Apple à deux endroits distincts, est de privilégier par défaut l’ingénierie de prompts associée à l’appel d’outils, et de n’envisager les adaptateurs que lorsque le critère ci-dessus est franchi.

L’entraînement, à la manière d’Apple

Apple indique que le toolkit contient du code d’exemple Python, des assets de modèles pour une version spécifique du modèle système, des utilitaires d’export .fmadapter et des utilitaires de bundling en asset packs.²

Les exigences du dataset sont des paires prompt/réponse au format jsonl, environ 100 à 1 000 échantillons pour les tâches basiques et 5 000+ pour les tâches complexes. Schema.md couvre la génération guidée et les champs de sécurité IA.²

Exigences matérielles : « Mac avec Apple silicon et au moins 32 Go de mémoire, ou machines Linux GPU. » Python 3.11 ou ultérieur.²

La règle d’Apple sur la qualité des données est simple : la qualité prime sur la quantité.²

L’entraînement est invoqué depuis le point d’entrée train_adapter du toolkit :

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/

Optionnellement, après l’entraînement de l’adaptateur, vous pouvez entraîner un draft model assorti.² Un draft model est une version plus petite du modèle de base système qui permet le speculative decoding, une technique d’accélération d’inférence publiée.⁷ La formulation d’Apple : « Si vous choisissez de ne pas entraîner le draft model, le speculative decoding ne sera pas disponible pour le cas d’usage de votre adaptateur. »²

La contrainte de version unique

Le fait le plus opérationnellement déterminant à propos des adaptateurs est leur liaison à une version spécifique du modèle système :³

« Chaque adaptateur est compatible avec une seule version spécifique du modèle système. Vous devez entraîner un nouvel adaptateur pour chaque nouvelle version du modèle de base. Une erreur d’exécution se produit si votre application s’exécute sur l’appareil d’une personne sans adaptateur compatible. »

Récupéré le 4 mai 2026, le tableau du toolkit d’Apple liste Beta 0.1.0 et Beta 0.2.0 comme supprimées, et 26.0.0 comme la première version complète du toolkit. La règle de cadence d’Apple est d’un toolkit par mise à jour du modèle système.² Énoncé complet : « Un nouveau toolkit sera publié pour chaque mise à jour du modèle système. Le modèle système est partagé entre iOS, macOS et visionOS, et les mises à jour du modèle système se produiront dans le cadre des mises à jour OS de ces plateformes (bien que toutes les mises à jour OS n’auront pas une mise à jour de modèle). »²

L’implication opérationnelle : les équipes d’application qui livrent des adaptateurs s’abonnent à un cycle de vie de mise à jour de modèle qui suit la cadence d’Apple. Chaque évolution du modèle de base est une fonction de forçage pour le réentraînement, la réévaluation et la republication.

Packaging en asset packs

La règle d’Apple : les fichiers d’adaptateurs sont trop volumineux pour le bundle d’application ; hébergez-les via App Store Connect ou votre serveur, puis téléchargez l’adaptateur compatible avec l’appareil à la demande.³

Le toolkit produit des paquets .fmadapter, que le toolkit empaquette également comme asset packs Background Assets. L’outil en ligne de commande ba-package de Xcode 16 ou ultérieur effectue le travail de bundling ; le toolkit l’invoque.³

Choix d’hébergement :³

• Apple-Hosted, Managed. Apple héberge l’asset ; l’OS gère le cycle de vie du téléchargement.
• Self-Hosted, Managed. Vous hébergez sur votre serveur ; l’OS gère le cycle de vie du téléchargement.
• Self-Hosted, Unmanaged. Vous hébergez et gérez vous-même le cycle de vie.

Les clés Info.plist requises diffèrent selon le choix d’hébergement :³ Apple-Hosted Managed nécessite BAHasManagedAssetPacks, BAAppGroupID et BAUsesAppleHosting ; Self-Hosted Managed nécessite les deux premières ; Self-Hosted Unmanaged n’en nécessite aucune. Chaque voie a également une cible d’extension d’asset-downloader que Xcode génère.

Choisir le bon adaptateur à l’exécution

Lorsque le BackgroundDownloadHandler.swift de l’extension d’asset-downloader est généré, Xcode câble un callback shouldDownload(_:). Le corps d’exemple d’Apple pour les assets d’adaptateur :³

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

L’exemple d’Apple est la seule vérification à l’exécution documentée. L’expression SystemLanguageModel.Adapter.isCompatible(assetPack) est ce que l’exemple retourne pour les asset packs d’adaptateurs ; traitez l’appel comme opaque au-delà de ce que l’exemple montre.³

Chargement et suivi des téléchargements

Une fois l’asset sur l’appareil, le chemin de chargement est :³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

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

La construction lance un téléchargement si l’appareil n’a pas d’adaptateur compatible en cache. La note d’Apple sur l’UX : « Comme les adaptateurs peuvent avoir une grande taille de données, leur téléchargement peut prendre un certain temps, surtout si une personne est en Wi-Fi ou sur un réseau cellulaire. Si une personne n’a pas de connexion réseau, elle ne peut pas utiliser votre adaptateur immédiatement. »³

La séquence d’état provient de 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: ...
        }
    }
}

Les cinq cas DownloadStatusUpdate documentés : .began, .paused, .downloading, .finished, .failed.³ La branche @unknown default du framework est obligatoire car Apple peut ajouter des cas dans les futures versions SDK.

Une fois que le statut atteint .finished, l’adaptateur est prêt à être branché à une session :

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

Le draft model et sa limitation de débit

Si votre adaptateur est livré avec un draft model, l’appel à adapter.compile() le prépare à l’usage. La documentation d’Apple le signale comme une étape distincte et coûteuse en calcul :³

« La première fois qu’un appareil télécharge une nouvelle version de votre adaptateur, un appel à compile() compile entièrement votre draft model et l’enregistre sur l’appareil. Lors des lancements ultérieurs de votre application, un appel à compile() vérifie l’existence d’un draft model compilé sauvegardé et le retourne immédiatement s’il existe. »

Il existe une limitation de débit publiée :³

« La limitation de débit protège les ressources de l’appareil partagées entre toutes les applications et processus. Si le framework détermine qu’une nouvelle compilation est nécessaire, il limite le processus de compilation sur toutes les plateformes, à l’exclusion de macOS, à trois compilations de draft model par application et par jour. »

La limitation de débit exclut macOS ; sur les autres plateformes, la nouvelle compilation de draft model est limitée à trois compilations par application et par jour.³ Apple recommande d’exécuter la compilation à l’intérieur d’une tâche planifiée par Background Tasks afin que le travail ne bloque pas le lancement de l’application.³

L’avertissement d’Apple sur les tests Xcode : le lancement via Xcode change l’UUID de l’application, donc la compilation complète s’exécute à chaque lancement et peut déclencher la limitation de débit.³

Tests et la contrainte du Simulateur

Les tests d’adaptateurs nécessitent un appareil physique. Apple est explicite : « Les tests d’adaptateurs nécessitent un appareil physique et ne sont pas pris en charge sur le Simulateur. »³

Pour les tests locaux dans Xcode, vous initialisez à partir d’une URL de fichier plutôt que d’un nom :³

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

Pour la publication, Apple indique de n’importer les fichiers d’adaptateurs que pour les tests locaux, puis de les supprimer avant la sortie et de télécharger les adaptateurs à la demande.³

Ce que cette voie vous coûte en termes opérationnels

En réunissant le cycle de vie, une application qui livre un adaptateur personnalisé s’engage pour :

1. Une infrastructure d’entraînement Python. Un Mac avec Apple silicon et 32 Go de mémoire au minimum, ou une machine Linux GPU.²
2. Une cadence de réentraînement à l’horloge d’Apple. Chaque mise à jour de modèle système signifie un nouvel adaptateur et une nouvelle version du toolkit.³
3. Une stack de service. Soit des asset packs hébergés par Apple via App Store Connect, soit votre propre serveur exécutant une intégration d’asset-downloader.³
4. Des adaptateurs par version en stockage. Plusieurs versions de modèles de base dans la nature signifient plusieurs adaptateurs hébergés, l’appareil tirant celui correspondant.³
5. Une porte d’entitlement. L’Account Holder de votre adhésion Apple Developer Program le demande ; vous ne pouvez pas livrer sans approbation.²
6. La taxe de 160 Mo par version d’adaptateur. Pas dans le bundle d’application, mais sur l’appareil de l’utilisateur après téléchargement.²
7. Tests sur appareil physique. Le Simulateur n’exécute pas les adaptateurs.³

Voilà le coût opérationnel sous une forme simple. Le bénéfice, lorsque les signaux d’adoption se confirment, est : le modèle on-device devient spécialisé pour la tâche avec un prompting minimal et une latence inférieure. Pour les applications qui paient déjà pour de l’inférence côté serveur fine-tunée et veulent la parité on-device, c’est le compromis en termes simples.

À retenir

1. Les adaptateurs sont du LoRA, selon la technique documentée par Apple. Poids de base gelés, petites matrices entraînables à travers le réseau du modèle, seuls les poids de l’adaptateur sont mis à jour pendant l’entraînement.²
2. Un adaptateur par version de modèle système, sans exception. Planifiez le réentraînement lié aux versions de l’OS.³
3. Le flux .fmadapter est de bout en bout. Entraînez en Python, packagez avec le toolkit, hébergez en tant qu’asset pack Background Assets, chargez par nom dans votre application, compilez le draft model dans une tâche en arrière-plan.
4. Apple elle-même recommande à la plupart des applications de ne pas emprunter cette voie. Deux pages distinctes de la documentation d’Apple le déconseillent pour la plupart des cas d’usage.¹ Lisez le critère sur la page du toolkit ; la réponse est « non » par défaut.
5. Testez sur du matériel. Le Simulateur n’exécute pas les adaptateurs. Construisez le plan de test autour de sessions sur appareil physique et du créneau de compilation du framework Background Tasks.

Le cluster Apple Ecosystem complet : le critère de décision pour la spécialisation intégrée ; le protocole Tool au cœur du framework ; la séparation des workflows agentiques entre les LLMs in-app et de tooling ; App Intents vs MCP pour la question de routage plus large. Le hub se trouve dans la Apple Ecosystem Series. Pour un contexte plus large iOS-avec-agents-IA, consultez le guide iOS Agent Development.

FAQ

Comment savoir si mon application a réellement besoin d’un adaptateur personnalisé ?

Apple recommande le modèle de base pour la majeure partie de l’ingénierie de prompts, de la génération guidée et des outils, et le guide du toolkit indique que les adaptateurs ont des exigences d’entraînement et de réentraînement importantes. La réponse par défaut est non, sauf si les signaux d’adaptateur d’Apple s’appliquent.²⁴

Que verrouille réellement l’entitlement ?

Apple documente l’entitlement comme requis lors du déploiement des adaptateurs, et non pour l’entraînement ou les tests locaux.²³

Quelle est la taille des adaptateurs et où vivent-ils ?

Le chiffre documenté par Apple : « Chaque adaptateur occupera environ 160 Mo d’espace de stockage dans votre application. »² Les adaptateurs ne vivent pas dans le bundle d’application. Apple les achemine via Background Assets, hébergés soit sur les serveurs Apple (managed), soit sur votre propre serveur (managed ou unmanaged), et l’appareil télécharge la version correspondant à son modèle système actuel.³

Que se passe-t-il quand Apple met à jour le modèle de base ?

Quand Apple met à jour le modèle de base, entraînez un adaptateur compatible pour cette version de modèle ; sinon, l’application peut rencontrer une erreur d’exécution sur un appareil sans adaptateur compatible.²³

Quelle est la relation entre les adaptateurs et .contentTagging ?

.contentTagging est géré par Apple et intégré au framework : un cas d’usage spécialisé en interne, et non le type formel Adapter qu’un développeur entraîne. Le type formel est ce que cet article couvre ; les cas d’usage sont couverts dans l’article compagnon.

Dois-je obligatoirement entraîner un draft model ?

Apple ne documente que cette conséquence du fait de sauter l’entraînement du draft model : le speculative decoding est indisponible pour ce cas d’usage d’adaptateur.²

Références