Foundation Models カスタムアダプター：いつトレーニングすべきか

Apple のアダプタードキュメントは、その用途を狭く定義しています。ほとんどのプロンプトエンジニアリング、ガイド付き生成、ツール利用にはベースとなるシステムモデルを使い、カスタム Adapter をトレーニングするのは、タスクがモデルウェイトの特化を必要とし、かつチームが Python でのモデルトレーニングに習熟している場合に限られます。¹⁴

Apple 自身が同じ型のドキュメント内で、こう明言しています。「アダプターは大量のストレージ容量を消費するため、ほとんどのアプリには推奨されません」¹。このクラスター内の以前の投稿、Foundation Models ユースケースでは、ほとんどのアプリが進むべき王道を取り上げました。本記事は第三のレール、すなわちカスタムアダプターのトレーニング・パッケージング・配信という運用上のライフサイクルと、いつ採用すべきでないかについての Apple の明示的なガイダンスを扱います。

TL;DR

• Apple のツールキットは、トレーニング手法を LoRA と特定しています。ベースウェイトは凍結され、アダプターウェイトのみがトレーニングされます。²
• 各アダプターは特定のシステムモデルバージョン1つに紐づきます。Apple がベースモデルを更新するたびに、アダプターを再トレーニングする必要があります。³
• Apple の推奨は、彼ら自身の言葉で次の通りです。「ほとんどのプロンプトエンジニアリング、ガイド付き生成、ツール利用にはベースのシステムモデルを使ってください。モデルを特化させる必要がある場合は、カスタム Adapter をトレーニングしてください…カスタムアダプターは、Python で foundation モデルをトレーニングすることに習熟している場合にのみ使用してください」¹
• アダプターファイルは大きく、メインのアプリバンドルに同梱すべきではなく、ホストされたアセットパックと Background Assets を通じてオンデマンドで配信されます。²³
• Apple は、プロンプトエンジニアリングやツール呼び出しでタスクが達成できない場合、または既存のファインチューニング済みサーバー LLM、専門知識、スタイル/フォーマット/ポリシー遵守、レイテンシー目標などがコストを正当化する場合にのみ、アダプターを検討するよう述べています。²

アダプターとは実際に何か

SystemLanguageModel.Adapter は struct で、iOS、iPadOS、Mac Catalyst、macOS、visionOS のいずれも 26.0 以降で利用可能です。⁴ Apple によるこの型の説明は次の通りです。

「ほとんどのプロンプトエンジニアリング、ガイド付き生成、ツール利用にはベースのシステムモデルを使ってください。モデルを特化させる必要がある場合は、カスタム Adapter をトレーニングしてシステムモデルのウェイトを変更し、カスタムタスク向けに最適化してください。カスタムアダプターは、Python で foundation モデルをトレーニングすることに習熟している場合にのみ使用してください」⁴

そのメカニズムは文書化されています。Apple のアダプタートレーニングガイドはこう明記しています。²

「システムモデルは、LoRA（Low-Rank Adaptation）として知られる parameter-efficient fine-tuning（PEFT）手法を採用しています。LoRA では、元のモデルウェイトは凍結され、『adapters』と呼ばれる小さなトレーニング可能なウェイトマトリクスがモデルのネットワーク内に埋め込まれます。トレーニング中は、アダプターウェイトのみが更新されるため、トレーニングするパラメーター数が大幅に削減されます」

LoRA は公開された論文の歴史を持つパブリックな手法です。⁵ Apple がドキュメント化している表面は、ツールキット、.fmadapter エクスポート、アセットパックのバンドル、Background Assets による配信、そして SystemLanguageModel.Adapter を通じた実行時の読み込みです。²³⁴

この型の API サーフェス

Apple は次の Adapter サーフェスを記載しています。⁴

• init(fileURL: URL) throws：「ファイル URL からアダプターを作成します」
• init(name: String) throws：「Background Assets フレームワークからダウンロードされたアダプターを作成します」
• func compile() async throws：「LanguageModelSession で使用される前にアダプターを準備します。アダプターに draft モデルがある場合は、これを呼び出してください」
• var creatorDefinedMetadata: [String : Any]：「アダプターのメタデータの creator defined フィールドから読み取った値です」
• static func removeObsoleteAdapters() throws：「現在のシステムモデルと互換性がなくなったすべての obsolete アダプターを削除します」
• static func compatibleAdapterIdentifiers(name: String) -> [String]：「現在のシステムモデルと互換性のあるすべてのアダプター識別子を取得します」
• enum AssetError：アセット関連の失敗のエラー型です。

SystemLanguageModel には、アダプター用の対応するイニシャライザがあります。convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails) で、説明は「アダプター付きのモデルのベースバージョンを作成します」となっています。⁶

デプロイメント専用の entitlement キーは com.apple.developer.foundation-model-adapter で、「アプリが Foundation Models フレームワークでカスタムアダプターを有効にできるかどうかを示すブール値」です。⁶ トレーニングや Xcode でのローカルテストには不要ですが、App Store に出荷する前には必要となります。³

Apple の「アダプターを検討すべきとき」の評価基準

ツールキットページには、具体的な採用シグナルが示されています。²

• 「LLM での使用に適したデータセットがある」、または既にファインチューニング済みのサーバーベース LLM を使用しており、オンデバイスで同等の挙動を実現したい場合。
• 「モデルに専門知識を持たせる必要がある」場合。
• 「モデルに特定のスタイル、フォーマット、ポリシーを遵守させる必要がある」場合。
• 「プロンプトエンジニアリングではタスクに必要な精度や一貫性を達成できない」場合。
• 「推論時のレイテンシーを下げたい。プロンプトエンジニアリングによる解決策が、すべての呼び出しごとに例を含む長いプロンプトを必要とする場合、そのタスクに特化したアダプターは最小限のプロンプトで済みます」

同じガイドには、引き受けるべきコストも列挙されています。²

• 目標スキルを示すプロンプトとレスポンスのペアからなるデータセット。
• アダプターの品質を評価するプロセス。
• サーバーからアプリにアダプターを読み込むためのプロセス。

そしてストレージ税です。「各アダプターはアプリ内で約 160 MB のストレージ容量を占有します。他の大きなアセットと同様、アダプターは複数のアダプターバージョンを持つとアプリがインストールするには大きすぎるサイズになるため、アプリのメインバンドルの一部にすべきではありません」²

このフレームワークの推奨は、Apple が二つの別々の場所で繰り返し述べている通り、デフォルトではプロンプトエンジニアリングとツール呼び出しを採用し、上記の評価基準を満たす場合にのみアダプターに手を伸ばすというものです。

トレーニング、Apple の流儀で

Apple は、ツールキットには Python サンプルコード、特定のシステムモデルバージョン用のモデルアセット、.fmadapter エクスポートユーティリティ、アセットパックのバンドルユーティリティが含まれていると述べています。²

データセット要件は jsonl 形式のプロンプト/レスポンスペアで、基本的なタスクではおおよそ 100 〜 1,000 サンプル、複雑なタスクでは 5,000 以上が必要です。Schema.md はガイド付き生成と AI 安全性フィールドをカバーしています。²

ハードウェア要件は次の通りです。「Apple silicon を搭載し、最低 32GB のメモリを持つ Mac、または Linux GPU マシン」。Python 3.11 以降が必要です。²

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/

オプションとして、アダプターをトレーニングした後、対応する draft モデルをトレーニングできます。² draft モデルとは、システムベースモデルの小型版であり、speculative decoding（公開された推論加速手法）を可能にするものです。⁷ Apple の表現はこうです。「draft モデルをトレーニングしないことを選択した場合、アダプターのユースケースで speculative decoding は利用できません」²

単一バージョン制約

アダプターについて運用上最も重要な事実は、特定のシステムモデルバージョンに紐づくということです。³

「各アダプターは、特定の単一のシステムモデルバージョンと互換性があります。新しいベースモデルバージョンごとに新しいアダプターをトレーニングする必要があります。互換性のあるアダプターなしにアプリがユーザーのデバイスで実行されると、ランタイムエラーが発生します」

2026年5月4日に取得した時点で、Apple のツールキット表には Beta 0.1.0 と Beta 0.2.0 が削除済みとして、26.0.0 が最初の正式なツールキットバージョンとして記載されています。Apple のリリース頻度ルールは、システムモデル更新ごとに1ツールキットです。² 全文は次の通りです。「すべてのシステムモデル更新ごとに新しいツールキットがリリースされます。システムモデルは iOS、macOS、visionOS で共有されており、システムモデルの更新はそれらのプラットフォームの OS 更新の一部として行われます（ただし、すべての OS 更新でモデル更新があるわけではありません）」²

運用上の含意としては、アダプターを出荷するアプリチームは、Apple のリリース頻度に合わせたモデル更新ライフサイクルにサブスクライブすることになります。各ベースモデルのアップデートは、再トレーニング、再評価、再公開の強制関数として働きます。

アセットパックとしてのパッケージング

Apple のルールはこうです。アダプターファイルはアプリバンドルには大きすぎるため、App Store Connect またはご自身のサーバーを通じてホストし、デバイスと互換性のあるアダプターをオンデマンドでダウンロードしてください。³

ツールキットは .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 には最初の2つが必要です。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)
}

Apple のサンプルが、文書化された唯一のランタイムチェックです。SystemLanguageModel.Adapter.isCompatible(assetPack) という式は、アダプターアセットパックに対してサンプルが返すものであり、サンプルが示す範囲を超えてはこの呼び出しを不透明なものとして扱うべきです。³

読み込みとダウンロードの追跡

アセットがデバイス上に届いた後の読み込みパスは次の通りです。³

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: ...
        }
    }
}

文書化された5つの DownloadStatusUpdate ケース：.began、.paused、.downloading、.finished、.failed です。³ フレームワークの @unknown default 分岐は必須です。Apple が将来の SDK バージョンでケースを追加する可能性があるためです。

ステータスが .finished に到達した後、アダプターはセッションに接続できる状態になります。

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

draft モデルとそのレート制限

アダプターが draft モデル付きで出荷された場合、adapter.compile() を呼び出すことで使用準備が整います。Apple のドキュメントは、これを別の計算コストの高いステップとして強調しています。³

「デバイスがアダプターの新しいバージョンを最初にダウンロードした際、compile() の呼び出しは draft モデルを完全にコンパイルし、デバイスに保存します。それ以降のアプリの起動では、compile() の呼び出しは保存されたコンパイル済みの draft モデルをチェックし、存在する場合はすぐに返します」

公開されたレート制限があります。³

「レート制限は、すべてのアプリとプロセス間で共有されているデバイスリソースを保護します。フレームワークが新しいコンパイルが必要と判断した場合、macOS を除くすべてのプラットフォームで、コンパイルプロセスをアプリごと、1日あたり3つの draft モデルコンパイルにレート制限します」

レート制限は macOS を除外しています。他のプラットフォームでは、新しい draft モデルコンパイルはアプリごと1日3回に制限されます。³ Apple は、コンパイルがアプリの起動をブロックしないよう、Background Tasks でスケジュールされたタスク内で実行することを推奨しています。³

Apple の Xcode テストに関する警告：Xcode から起動するとアプリの UUID が変わるため、毎回起動時に完全なコンパイルが実行され、レート制限に引っかかる可能性があります。³

テストと Simulator 制約

アダプターのテストには物理デバイスが必要です。Apple は明言しています。「アダプターのテストには物理デバイスが必要であり、Simulator ではサポートされません」³

Xcode でのローカルテストでは、名前ではなくファイル URL から初期化します。³

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

公開時には、アダプターファイルはローカルテスト目的でのみインポートし、リリース前に削除してアダプターをオンデマンドでダウンロードするよう Apple は指示しています。³

このパスが運用面で課すコスト

ライフサイクルをまとめると、カスタムアダプターを出荷するアプリは以下を引き受けることになります。

1. Python トレーニングインフラ。 最低でも Apple silicon と 32 GB のメモリを搭載した Mac、または Linux GPU マシン。²
2. Apple のリリース頻度に合わせた再トレーニングサイクル。 システムモデルの更新ごとに、新しいアダプターと新しいツールキットバージョンが必要となります。³
3. 配信スタック。 App Store Connect 経由の Apple ホスト型アセットパック、またはアセットダウンローダー統合を実行するご自身のサーバー。³
4. バージョンごとのアダプターストレージ。 複数のベースモデルバージョンが世に出回ると、複数のアダプターをホストし、デバイスがマッチするものを取得することになります。³
5. Entitlement ゲート。 Apple Developer Program メンバーシップの Account Holder が申請するもので、承認なしには出荷できません。²
6. アダプターバージョンごとの 160 MB 税。 アプリバンドル内ではなく、ダウンロード後のユーザーのデバイス上に存在します。²
7. 物理デバイスでのテスト。 Simulator ではアダプターは動作しません。³

それが運用上のコストを率直な形で表したものです。採用シグナルが満たされた場合の利点は、オンデバイスモデルが最小限のプロンプトと低レイテンシーで、そのタスクに特化したものになることです。既にファインチューニング済みのサーバーサイド推論にコストを払い、オンデバイスで同等の挙動を望むアプリにとっては、それが率直な形でのトレードオフとなります。

要点

1. アダプターは LoRA で、Apple の文書化された手法による。 ベースウェイトは凍結され、モデルのネットワーク全体に小さなトレーニング可能なマトリクスが配置され、トレーニング中はアダプターウェイトのみが更新されます。²
2. システムモデルバージョンごとに1つのアダプター、例外なし。 OS リリースに連動した再トレーニングを計画してください。³
3. .fmadapter フローはエンドツーエンドで完結している。 Python でトレーニングし、ツールキットでパッケージし、Background Assets のアセットパックとしてホストし、アプリ内で名前で読み込み、draft モデルをバックグラウンドタスクでコンパイルします。
4. Apple 自身が、ほとんどのアプリにこのパスを採用しないよう推奨している。 Apple のドキュメントの2つの別々のページが、ほとんどのユースケースに対してこれを推奨しないと述べています。¹ ツールキットページの評価基準を読んでください。デフォルトの答えは「いいえ」です。
5. ハードウェアでテストする。 Simulator ではアダプターは動作しません。物理デバイスのセッションと Background Tasks フレームワークのコンパイルスロットを中心にテスト計画を立ててください。

Apple Ecosystem クラスター全体：組み込みの特化のための判断基準、フレームワークの中核にある Tool プロトコル、アプリ内とツール LLM 間のエージェント的ワークフローの分割、より広いルーティングの問題についての App Intents vs MCP。ハブは Apple Ecosystem シリーズにあります。AI エージェント付き iOS のより広い文脈については、iOS Agent Development ガイドをご覧ください。

FAQ

自分のアプリが本当にカスタムアダプターを必要としているかどうか、どう判断すればよいですか？

Apple は、ほとんどのプロンプトエンジニアリング、ガイド付き生成、ツール利用に対してベースモデルを推奨しており、ツールキットガイドはアダプターには急峻なトレーニングと再トレーニングの要件があると述べています。Apple のアダプターシグナルが当てはまらない限り、デフォルトの答えは「いいえ」です。²⁴

この entitlement は実際何をゲートしていますか？

Apple は、entitlement をアダプターのデプロイ時に必要なものとして文書化しており、トレーニングやローカルテストには必要ありません。²³

アダプターのサイズはどれくらいで、どこに配置されますか？

Apple が文書化している数字は次の通りです。「各アダプターはアプリ内で約 160 MB のストレージ容量を占有します」² アダプターはアプリバンドル内には存在しません。Apple は、Apple サーバー（managed）またはご自身のサーバー（managed または unmanaged）でホストされる Background Assets を通じてアダプターをルーティングし、デバイスは現在のシステムモデルに合致するバージョンをダウンロードします。³

Apple がベースモデルを更新するとどうなりますか？

Apple がベースモデルを更新する際、そのモデルバージョンと互換性のあるアダプターをトレーニングしてください。さもなければ、互換性のあるアダプターのないデバイス上でアプリがランタイムエラーに遭遇する可能性があります。²³

アダプターと .contentTagging の関係はどうなっていますか？

.contentTagging は Apple 管理であり、フレームワークに組み込まれています。内部的に特化されたユースケースであり、開発者がトレーニングする正式な Adapter 型ではありません。本記事が扱うのは正式な型であり、ユースケースはコンパニオン投稿で扱われています。

draft モデルをトレーニングする必要がありますか？

Apple が文書化している draft モデルトレーニングをスキップする結果は、これだけです。そのアダプターのユースケースで speculative decoding が利用できなくなる、というものです。²

参考文献