Foundation Models 自訂 Adapter:何時應該訓練一個

Q: 該權限到底管控什麼?

Apple 文件記載該權限在「部署」adapter 時為必要,但訓練或本機測試並不需要。23

Q: Adapter 有多大、放在哪裡?

Apple 文件中的數字:「每個 adapter 約佔用 160 MB 儲存空間。」2Adapter 不存放於 app 套件中。Apple 透過 Background Assets 配送,可選擇 Apple 伺服器託管(由系統管理)或您自家伺服器(由系統管理或自行管理),裝置會下載與其目前系統模型相符的版本。3

Q: Adapter 與 .contentTagging 之間是什麼關係?

.contentTagging 由 Apple 管理且內建於框架中:屬於內部特化的使用情境,而非開發者所訓練的正式 Adapter 型別。本文涵蓋的是正式型別;使用情境則由 系列另一篇文章 涵蓋。

Q: 我必須訓練 draft model 嗎?

Apple 僅文件化跳過 draft model 訓練的單一後果:該 adapter 使用情境將無法使用推測式解碼。2

4分鐘閱讀

Apple 的 adapter 文件對使用路徑定義得非常狹窄:大多數情境下,提示工程、引導式生成與工具皆應使用基礎系統模型,只有當任務需要模型權重特化、且團隊熟悉Python模型訓練時,才考慮訓練自訂 Adapter。¹⁴

Apple 自家文件中針對同一型別的原文寫道:「Adapter 會佔用大量儲存空間,不建議大多數應用程式使用。」¹本系列前一篇文章 Foundation Models 使用情境,涵蓋了大多數應用程式應該走的主軌道。本文則是第三條軌道:訓練、封裝與發佈自訂 adapter 的營運生命週期,以及 Apple 對於何時不該採用此路徑的明確指引。

TL;DR

Apple 工具套件將訓練方法定位為 LoRA:基礎權重維持凍結,僅訓練 adapter 權重。²
每個 adapter 都綁定於單一系統模型版本。當 Apple 更新基礎模型時,您必須重新訓練 adapter。³
Apple 的建議,以其原文表述為:「大多數情境下,提示工程、引導式生成與工具皆應使用基礎系統模型。若您需要對模型進行特化,則訓練自訂 Adapter……唯有當您熟悉以Python訓練 foundation 模型時,才使用自訂 adapter。」¹
Adapter 檔案龐大,不應隨主應用程式套件一併發佈,而是透過託管的資源套件與 Background Assets 按需配送。²³
Apple 表示,只有在提示工程或工具呼叫無法達成任務、或既有的微調伺服器LLM、領域專業知識、風格/格式/政策遵循、或延遲目標足以justify成本時,才應考慮 adapter。²

Adapter 究竟是什麼

SystemLanguageModel.Adapter 是一個 struct,可在 iOS、iPadOS、Mac Catalyst、macOS 與 visionOS 上使用,皆為 26.0 以上版本。⁴Apple 對該型別的描述:

「大多數情境下,提示工程、引導式生成與工具皆應使用基礎系統模型。若您需要對模型進行特化,則訓練自訂 Adapter 以變更系統模型權重,並針對您的自訂任務進行最佳化。唯有當您熟悉以Python訓練 foundation 模型時,才使用自訂 adapter。」⁴

該機制有正式文件記載。Apple 的 adapter 訓練指南直接陳述:²

「系統模型採用稱為 LoRA(Low-Rank Adaptation)的參數高效微調(PEFT)方法。在 LoRA 中,原始模型權重維持凍結,而稱為『adapter』的小型可訓練權重矩陣則嵌入於模型網路中。訓練期間,僅 adapter 權重會更新,大幅減少需訓練的參數數量。」

LoRA 是一項公開技術,有發表的論文歷史。⁵Apple 文件化的範圍是:工具套件、.fmadapter 匯出、資源套件封裝、Background Assets 配送,以及透過 SystemLanguageModel.Adapter 進行的執行階段載入。²³⁴

該型別的API表面

Apple 列出以下 Adapter 表面:⁴

init(fileURL: URL) throws:「從檔案 URL 建立 adapter。」
init(name: String) throws:「建立由 background assets framework 下載的 adapter。」
func compile() async throws:「在搭配 LanguageModelSession 使用前,先準備 adapter。若您的 adapter 包含 draft model,應呼叫此方法。」
var creatorDefinedMetadata: [String : Any]:「從 adapter metadata 的 creator defined 欄位讀取的值。」
static func removeObsoleteAdapters() throws:「移除所有與目前系統模型不再相容的過時 adapter。」
static func compatibleAdapterIdentifiers(name: String) -> [String]:「取得所有與目前系統模型相容的 adapter 識別碼。」
enum AssetError:資源相關失敗的錯誤型別。

SystemLanguageModel 為 adapter 提供配對的初始化方法:convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails),描述為「使用 adapter 建立基礎版本的模型」。⁶

僅供部署使用的權限 key 為 com.apple.developer.foundation-model-adapter:「一個 Boolean 值,指出該 app 是否可為 Foundation Models 框架啟用自訂 adapter。」⁶您在訓練或本機 Xcode 測試時不需要它;但在發佈至 App Store 之前必須取得。³

Apple 的「何時應考慮 adapter」評估準則

工具套件頁面列出具體的採用訊號:²

「您擁有適合搭配LLM使用的資料集」,或您已使用微調的伺服器端LLM,並希望在裝置端達到對等表現。
「您需要模型成為特定領域的專家。」
「您需要模型遵循特定風格、格式或政策。」
「提示工程無法達成您任務所需的準確度或一致性。」
「您希望在推論時降低延遲。若您的提示工程方案在每次呼叫時都需要冗長的提示與範例,則針對該任務特化的 adapter 可大幅減少提示需求。」

同一份指南也列出您必須承擔的成本:²

一份能展現目標技能的提示與回應配對資料集。
一套評估 adapter 品質的流程。
一套從伺服器將 adapter 載入應用程式的流程。

以及儲存空間的代價:「每個 adapter 約佔用 160 MB 的儲存空間。如同其他大型資源,adapter 不應屬於應用程式的主套件,因為當您的 app 含多個 adapter 版本時,將會大到使用者難以安裝。」²

該框架的建議,Apple 在兩個不同的位置都重複表述,即預設應採用提示工程加上工具呼叫,只有在上述評估準則通過時才訴諸 adapter。

訓練,以 Apple 的方式

Apple 表示工具套件包含Python範例程式碼、針對特定系統模型版本的模型資源、.fmadapter 匯出工具,以及資源套件封裝工具。²

資料集要求為 jsonl 格式的 prompt/response 配對,基本任務約 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/

訓練 adapter 之後,您也可選擇訓練一個對應的 draft model。²Draft model 是系統基礎模型的較小版本,可啟用推測式解碼(speculative decoding),這是已發表的推論加速技術。⁷Apple 的說法:「若您選擇不訓練 draft model,則您的 adapter 使用情境將無法使用推測式解碼。」²

單一版本約束

關於 adapter,在營運上影響最深遠的事實,就是它與特定系統模型版本的綁定:³

「每個 adapter 僅與單一特定系統模型版本相容。每當有新的基礎模型版本,您都必須訓練新的 adapter。若您的 app 在使用者裝置上執行時沒有相容的 adapter,將發生執行階段錯誤。」

擷取於 2026 年 5 月 4 日,Apple 的工具套件表格列出 Beta 0.1.0 與 Beta 0.2.0 已被移除,而 26.0.0 是首個完整工具套件版本。Apple 的節奏規則為:每次系統模型更新對應一個工具套件。²完整原文:「每次系統模型更新都會發佈新的工具套件。系統模型在 iOS、macOS 與 visionOS 之間共享,系統模型更新會隨這些平台的 OS 更新一併發生(雖然並非每次 OS 更新都會包含模型更新)。」²

營運層面的意涵:發佈 adapter 的應用程式團隊,等於訂閱了一套以 Apple 節奏運轉的模型更新生命週期。每一次基礎模型更新都會迫使團隊重新訓練、重新評估與重新發佈。

以資源套件方式封裝

Apple 的規則:adapter 檔案對 app 套件而言過於龐大;請透過 App Store Connect 或您自己的伺服器託管,然後按需下載與裝置相容的 adapter。³

工具套件會產出 .fmadapter 套件,工具套件也會將其封裝為 Background Assets 資源套件。Xcode 16 或更新版本的 ba-package 命令列工具負責封裝工作;工具套件會呼叫該工具。³

託管選項:³

Apple 託管,由系統管理。 Apple 託管資源;OS 管理下載生命週期。
自行託管,由系統管理。 您託管於自家伺服器;OS 管理下載生命週期。
自行託管,自行管理。 您自行託管並自行管理生命週期。

所需的 Info.plist key 因託管選項而異:³Apple 託管且由系統管理需要 BAHasManagedAssetPacks、BAAppGroupID 與 BAUsesAppleHosting;自行託管由系統管理需要前兩者;自行託管自行管理則皆不需。每條路徑也都會由 Xcode 產生對應的 asset-downloader 擴充功能 target。

在執行階段選擇正確的 adapter

當 asset-downloader 擴充功能的 BackgroundDownloadHandler.swift 產生後,Xcode 會接好 shouldDownload(_:) callback。Apple 針對 adapter 資源的範例實作:³

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

Apple 的範例是唯一文件化的執行階段檢查方式。SystemLanguageModel.Adapter.isCompatible(assetPack) 這段運算式正是該範例對 adapter 資源套件的回傳值;除了範例所示之外,請將該呼叫視為不透明。³

載入與追蹤下載

當資源已位於裝置上,載入路徑為:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

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

若裝置尚未快取相容的 adapter,建構過程會啟動下載。Apple 對 UX 的提示:「由於 adapter 資料量可能相當大,下載可能需要一些時間,尤其當使用者連線於 Wi-Fi 或行動網路時。若使用者沒有網路連線,將無法立即使用您的 adapter。」³

狀態序列來自 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: ...
        }
    }
}

DownloadStatusUpdate 文件化的五種 case:.began、.paused、.downloading、.finished、.failed。³框架的 @unknown default 分支是強制的,因為 Apple 可能在未來的SDK版本新增 case。

當狀態到達 .finished 後,即可將 adapter 接入 session:

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

Draft Model 與其速率限制

若您的 adapter 隨附 draft model,呼叫 adapter.compile() 即可準備使用。Apple 文件特別點出此為一個獨立、運算成本高昂的步驟:³

「裝置首次下載您 adapter 的新版本時,呼叫 compile() 會完整編譯您的 draft model 並儲存至裝置。在後續啟動您的 app 時,呼叫 compile() 會檢查是否有已儲存的編譯後 draft model,若存在則立即回傳。」

存在已公布的速率限制:³

「速率限制保護所有 app 與行程之間共享的裝置資源。若框架判定需要進行新的編譯,則會在所有平台(macOS 除外)對編譯流程實施速率限制,每個 app 每天至多三次 draft model 編譯。」

該速率限制不適用於 macOS;在其他平台上,新的 draft model 編譯每個 app 每天最多三次。³Apple 建議將編譯放入由 Background Tasks 排程的任務中執行,使該工作不會阻塞 app 啟動。³

Apple 對 Xcode 測試的警告:透過 Xcode 啟動會更動 app 的 UUID,因此每次啟動都會執行完整編譯,有可能觸發速率限制。³

測試與 Simulator 限制

Adapter 測試需要實體裝置。Apple 的說法很明確:「測試 adapter 需要實體裝置,Simulator 不支援。」³

於 Xcode 進行本機測試時,您應使用檔案 URL 而非名稱進行初始化:³

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

至於發佈,Apple 表示僅應為了本機測試而匯入 adapter 檔案,接著在發佈前移除,並改為按需下載 adapter。³

此路徑在營運層面的代價

將整個生命週期合在一起,發佈自訂 adapter 的 app 等於簽下:

Python訓練基礎設施。 至少一台搭載 Apple silicon 與 32 GB 記憶體的 Mac,或一台 Linux GPU 機器。²
依 Apple 節奏的重新訓練週期。 每次系統模型更新都意味著新的 adapter 與新的工具套件版本。³
服務堆疊。 透過 App Store Connect 託管的 Apple 資源套件,或執行 asset-downloader 整合的自家伺服器。³
每版本一個 adapter 的儲存負擔。 多個基礎模型版本同時在外流通,意味著託管多個 adapter,並由裝置拉取相符的版本。³
權限關卡。 須由您 Apple Developer Program 會籍的 Account Holder 提出申請;未獲核准前無法發佈。²
每個 adapter 版本 160 MB 的儲存代價。 雖然不在 app 套件內,但下載後會留在使用者裝置上。²
實體裝置測試。 Simulator 不執行 adapter。³

這就是營運成本的真實樣貌。當採用訊號通過時,所獲得的好處是:裝置端模型針對該任務變得特化,提示需求最少且延遲較低。對於已為微調伺服器端推論付費、並希望在裝置端達到對等表現的 app 而言,這是明確的取捨。

重點摘要

Adapter 即 LoRA,依 Apple 文件化的技術。 凍結基礎權重,於模型網路中嵌入小型可訓練矩陣,訓練期間僅 adapter 權重會更新。²
每個系統模型版本對應一個 adapter,沒有例外。 計畫必須以 OS 釋出為單位安排重新訓練。³
.fmadapter 流程是端到端的。 以Python訓練、用工具套件封裝、託管為 Background Assets 資源套件、在 app 中以名稱載入、並在背景任務中編譯 draft model。
Apple 自身建議大多數 app 不要走這條路。 兩份不同的 Apple 文件頁面對大多數使用情境皆不鼓勵採用。¹請閱讀工具套件頁面上的評估準則;預設答案是「不」。
在硬體上測試。 Simulator 不執行 adapter。請以實體裝置 session 與 Background Tasks 框架的編譯時段來規劃測試計畫。

完整 Apple 生態系列:內建特化的決策準則;位居框架核心的 Tool 協定;代理式工作流在 in-app 與 tooling LLM 之間的分工;以及更廣的路由問題:App Intents 對比 MCP。系列入口在 Apple 生態系列。若需更廣的 iOS 與 AI agent 結合脈絡,請參閱 iOS Agent 開發指南。

FAQ

我如何判斷自家 app 是否真的需要自訂 adapter?

Apple 建議大多數提示工程、引導式生成與工具情境採用基礎模型,且工具套件指南指出 adapter 的訓練與重新訓練要求都相當高。預設答案為「不需要」,除非 Apple 列出的 adapter 訊號適用於您。²⁴

該權限到底管控什麼?

Apple 文件記載該權限在「部署」adapter 時為必要,但訓練或本機測試並不需要。²³

Adapter 有多大、放在哪裡?

Apple 文件中的數字:「每個 adapter 約佔用 160 MB 儲存空間。」²Adapter 不存放於 app 套件中。Apple 透過 Background Assets 配送,可選擇 Apple 伺服器託管(由系統管理)或您自家伺服器(由系統管理或自行管理),裝置會下載與其目前系統模型相符的版本。³

Apple 更新基礎模型時會發生什麼事?

當 Apple 更新基礎模型,您必須為該模型版本訓練相容的 adapter;否則 app 在沒有相容 adapter 的裝置上可能會遭遇執行階段錯誤。²³

Adapter 與 `.contentTagging` 之間是什麼關係?

.contentTagging 由 Apple 管理且內建於框架中:屬於內部特化的使用情境,而非開發者所訓練的正式 Adapter 型別。本文涵蓋的是正式型別;使用情境則由系列另一篇文章涵蓋。

我必須訓練 draft model 嗎?

Apple 僅文件化跳過 draft model 訓練的單一後果:該 adapter 使用情境將無法使用推測式解碼。²

參考資料

Apple Developer,「SystemLanguageModel.Adapter」。型別描述、不建議大多數 app 使用的建議、「唯有當您熟悉以Python訓練 foundation 模型時,才使用自訂 adapter。」擷取於 2026-05-04。 ↩↩↩↩
Apple Developer,「Get started with Foundation Models adapter training」。工具套件概述、LoRA 機制、硬體要求、資料集規格、訓練CLI、draft model 選項、工具套件版本表、權限申請流程。擷取於 2026-05-04。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩
Apple Developer,「Loading and using a custom adapter with Foundation Models」。資源套件託管、Info.plist key、shouldDownload(_:) 範例、狀態序列、速率限制、Simulator 排除、單一版本相容性約束。擷取於 2026-05-04。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩
Apple Developer,「SystemLanguageModel.Adapter」。Struct API 表面:init(fileURL:)、init(name:)、compile()、creatorDefinedMetadata、removeObsoleteAdapters()、compatibleAdapterIdentifiers(name:)、AssetError。擷取於 2026-05-04。 ↩↩↩↩↩↩
Hu et al.,「LoRA: Low-Rank Adaptation of Large Language Models」,arXiv:2106.09685。Apple 所採用技術的原始 LoRA 論文。 ↩
Apple Developer,「SystemLanguageModel」。init(adapter:guardrails:) 便利初始化方法,以及 com.apple.developer.foundation-model-adapter 權限描述。擷取於 2026-05-04。 ↩↩
Leviathan et al.,「Fast Inference from Transformers via Speculative Decoding」,arXiv:2211.17192;以及 Chen et al.,「Accelerating Large Language Model Decoding with Speculative Sampling」,arXiv:2302.01318。Apple draft model 所採用的推測式解碼技術,adapter 訓練指南直接引用。 ↩