Foundation Models 自訂 Adapter:Apple 不建議的生命週期

SystemLanguageModel.Adapter 型別讓應用程式能將自訂訓練的權重載入 Apple 的裝置端語言模型。¹ 框架支援這項功能。Apple 提供訓練工具組,有完整文件記載的權利描述檔、.fmadapter 套件格式,以及 Background Assets 整合,可將正確的 adapter 下載到正確的裝置上。

Apple 自家針對同一型別的文件也直接寫道(原文照錄):「Adapters consume a large amount of storage space and isn’t recommended for most apps.」¹ 本系列前一篇文章 Foundation Models 使用情境,涵蓋了大多數應用程式應該走的軌道。本篇談的是第三軌:訓練、打包、出貨自訂 adapter 的營運生命週期,以及 Apple 明確指出何時不該走這條路的指引。

TL;DR

• 自訂 adapter 是一組 LoRA 訓練的權重矩陣,疊加在裝置端系統語言模型之上。² Apple 的工具組明確以此名稱確認該技術。
• 每一個 adapter 都綁定到單一系統模型版本。當 Apple 更新基礎模型時,您必須重新訓練 adapter。³
• Apple 的建議,引用其原文:「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 資產體積龐大(約 160 MB),透過 Background Assets 派送,並由權利描述檔(com.apple.developer.foundation-model-adapter)把關;此權利描述檔需由 Apple Developer Program 會員的 Account Holder 為部署用途申請。³
• 此路徑對少數特定應用程式合理:那些想在裝置端複製伺服器端微調 LLM 的應用程式、對風格/格式/政策有嚴格遵循需求的應用程式,或在目標任務上已記錄到提示工程瓶頸的應用程式。²

Adapter 究竟是什麼

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

「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.」⁴

機制有完整文件記載。Apple 的 adapter 訓練指南直接這麼寫:²

「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 是公開的技術,並有已發表的論文。⁵ Apple 的貢獻在於工具組、.fmadapter 套件格式、載入 adapter 的裝置端執行階段,以及透過 Background Assets 出貨 adapter 的生命週期管線。

此型別的 API 表面

Adapter struct 暴露的介面範圍不大:⁴

• init(fileURL: URL) throws:「Creates an adapter from the file URL.」用於本地 Xcode 測試。
• 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]:來自中繼資料 creator-defined 欄位的值。
• static func removeObsoleteAdapters() throws:清除不再對應目前系統模型的 adapter。
• static func compatibleAdapterIdentifiers(name: String) -> [String]:擷取相容 adapter 資產包的 ID。
• enum AssetError:資產相關失敗的錯誤型別。

SystemLanguageModel 為 adapter 配備了對應的初始化器:convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails),描述為「Creates the base version of the model with an adapter.」⁶

僅供部署使用的權利描述檔金鑰是 com.apple.developer.foundation-model-adapter:「A Boolean value that indicates whether the app can enable custom adapters for the Foundation Models framework.」⁶ 您不需要它來進行訓練或本地 Xcode 測試;但在出貨到 App Store 之前必須取得。³

Apple 的「何時該考慮 Adapter」評估標準

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

• 「You have a dataset suitable for use with an LLM」,或您已使用伺服器端微調 LLM 並希望在裝置端達到一致表現。
• 「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.」

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

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

還有儲存空間的代價:「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.」²

框架的建議,Apple 在兩個獨立的地方都重申過:預設使用提示工程加上工具呼叫,只有在上述評估標準通過時才動用 adapter。

依 Apple 規範進行訓練

訓練管線使用 Python。Apple 的工具組附帶範例程式碼、與特定系統模型版本對應的模型資產、資料集工具,以及產出 .fmadapter 套件的匯出步驟。²

硬體需求:「Mac with Apple silicon and at least 32GB memory, or Linux GPU machines.」Python 3.11 或更新版本。²

資料集格式:²

• 格式為 jsonl,包含 role("user" 或 "assistant")和 content 欄位。
• 基本任務 100 至 1,000 筆樣本。
• 複雜任務 5,000 筆以上樣本。
• 工具組中的 Schema.md 涵蓋完整綱要,包含引導生成與 AI 安全鉤點的欄位。

Apple 對資料品質的提醒值得引用:「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.」²

訓練從工具組的 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 的說法:「If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.」²

單一版本綁定的限制

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

「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.」

工具組與模型同步版本管理。截至撰寫本文時,Apple 已釋出兩個 beta 工具組版本(Beta 0.1.0 與 Beta 0.2.0,皆已下架)以及一個正式版本:26.0.0。² Apple 的釋出節奏聲明:「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).」²

營運上的意涵:出貨 adapter 的應用程式團隊,等於訂閱了一個按 Apple 節奏運行的模型更新生命週期。每一次基礎模型升級,都會強制觸發重新訓練、重新評估與重新發佈。

以 Asset Pack 形式打包

Adapter 檔案大到把它打包進應用程式被明確勸阻。Apple 透過 Background Assets 派送 adapter。³

工具組產出 .fmadapter 套件,並同時將其打包為 Background Assets 資產包。Xcode 16 以上版本的 ba-package 命令列工具負責打包工作;工具組會呼叫它。³

託管選項:³

• Apple-Hosted, Managed. Apple 託管資產;作業系統管理下載生命週期。
• Self-Hosted, Managed. 您在自己的伺服器上託管;作業系統管理下載生命週期。
• Self-Hosted, Unmanaged. 您自行託管並管理生命週期。

所需的 Info.plist 金鑰因託管選項而異:³ Apple-Hosted Managed 需要 BAHasManagedAssetPacks、BAAppGroupID 與 BAUsesAppleHosting;Self-Hosted Managed 需要前兩者;Self-Hosted Unmanaged 不需要。每一條路徑也都搭配 Xcode 產生的資產下載器擴充目標。

在執行階段選擇正確的 Adapter

當資產下載器擴充的 BackgroundDownloadHandler.swift 產生時,Xcode 會接好 shouldDownload(_:) 回呼。Apple 為 adapter 資產提供的範例內容:³

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

SystemLanguageModel.Adapter.isCompatible(_:) 對於其 adapter 與目前系統模型相符的資產包傳回 true。同一個回呼也可以放行您應用程式所需的非 adapter 資產。

載入與追蹤下載

當資產到達裝置後,載入路徑為:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

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

若裝置尚未快取相容 adapter,建構過程會啟動下載。Apple 對使用者體驗的提醒:「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.」³

狀態序列由 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 案例:.began、.paused、.downloading、.finished、.failed。³ 框架的 @unknown default 分支是必要的,因為 Apple 可能在未來的 SDK 版本中新增案例。

當狀態到達 .finished 後,adapter 就可以接入 session:

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

Draft Model 與其速率限制

如果您的 adapter 隨附 draft model,呼叫 adapter.compile() 可為其準備使用。Apple 的文件將其視為一個獨立、計算成本高昂的步驟:³

「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.」

文件中明訂的速率限制:³

「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.」

macOS 排除規則值得注意;此限制適用於 iOS、iPadOS 與 visionOS。Apple 建議在 Background Tasks 排程的任務中執行編譯,讓這項工作不會阻塞應用程式啟動。³

開發時的陷阱:「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.」³

測試與模擬器的限制

Adapter 測試需要實機。Apple 講得很明白:「Testing adapters requires a physical device and isn’t supported on Simulator.」³

在 Xcode 中進行本地測試時,您要從檔案 URL 而非名稱進行初始化:³

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

Apple 的模式是:匯入本地檔案做測試,然後在發佈應用程式之前將其從專案中移除,因為 adapter 檔案太大不適合打包。³

此路徑在營運層面的成本

把生命週期串起來看,出貨自訂 adapter 的應用程式必須承擔:

1. Python 訓練基礎設施。 至少需要一台搭載 Apple silicon、32 GB 記憶體的 Mac,或一台 Linux GPU 機器。²
2. 依 Apple 時鐘的重新訓練節奏。 每一次系統模型更新都意味著一個新的 adapter 與新的工具組版本。³
3. 服務基礎架構。 透過 App Store Connect 走 Apple 託管的資產包,或在自家伺服器上跑資產下載器整合。³
4. 每個版本的 adapter 都佔用儲存空間。 多個基礎模型版本同時在外流通,意味著同時託管多個 adapter,由裝置自行拉取相符版本。³
5. 權利描述檔關卡。 您的 Apple Developer Program 會員 Account Holder 必須提出申請;未獲核准無法出貨。²
6. 每個 adapter 版本的 160 MB 代價。 不在應用程式套件中,而是下載後存在使用者裝置上。²
7. 實機測試。 模擬器不執行 adapter。³

這就是營運成本的真實樣貌。當採用訊號通過時的好處是:裝置端模型針對您的任務專業化、極簡提示、低延遲、無需付費的逐次 API 呼叫,以及完整的資料在地化。對於那些已經在為伺服器端微調推論付費、又希望在裝置端達到一致表現的應用程式而言,這就是平實的取捨。

重點摘要

1. Adapter 即 LoRA,Apple 已明文記載這項技術。 凍結基礎權重、在模型網路中嵌入小型可訓練矩陣,訓練期間只更新 adapter 權重。²
2. 每個系統模型版本對應一個 adapter,沒有例外。 重新訓練的計畫必須與 OS 釋出綁定。³
3. .fmadapter 流程是端對端的。 在 Python 中訓練,以工具組打包,以 Background Assets 資產包託管,在應用程式中以名稱載入,在背景任務中編譯 draft model。
4. Apple 自己建議大多數應用程式不要走這條路。 兩份不同的 Apple 文件頁面都對大多數使用情境表達勸退。¹ 詳閱工具組頁面的評估標準;預設答案是「不」。
5. 在硬體上測試。 模擬器不執行 adapter。測試計畫應圍繞實機測試與 Background Tasks 框架的編譯時段建構。

完整的 Apple 生態系列:內建專業化的決策框架;框架核心的 Tool 協定;應用程式內外與工具型 LLM 之間的代理工作流分工;App Intents vs MCP 處理更廣的路由問題。系列入口在 Apple 生態系列。如需更廣的 iOS 與 AI 代理脈絡,請參閱 iOS Agent Development 指南。

FAQ

如何判斷我的應用程式是否真的需要自訂 adapter?

請閱讀 Apple 工具組指南中的「When to consider an adapter」章節。² 訊號包括:已存在希望在裝置端鏡像的伺服器端微調 LLM、有文件佐證的提示工程準確度天花板、對特定風格/格式/政策遵循的嚴格要求,或是提示工程單獨無法達成的延遲目標。大多數應用程式以上條件都不滿足,Apple 也明白這麼說。

權利描述檔究竟把守的是什麼?

把守部署,而不是訓練。Apple 文件明確寫道:「You don’t need this entitlement to train or locally test adapters.」³ 您的 Apple Developer Program 會員 Account Holder 從 Foundation Models Framework Adapter Entitlement 頁面申請 com.apple.developer.foundation-model-adapter,該權利描述檔才會打通通往 App Store 出貨的路徑。²

Adapter 有多大?它們存在哪裡?

Apple 文件中的數字是:「Each adapter will take approximately 160 MB of storage space in your app.」² Adapter 不存在於應用程式套件中。Apple 透過 Background Assets 派送,可由 Apple 伺服器(managed)或您自家伺服器(managed 或 unmanaged)託管,裝置會下載與目前系統模型對應的版本。³

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

您必須重新訓練。文件原文:「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.」³ 實務上,您的服務基礎架構會同時託管多個 adapter 版本,裝置會根據 isCompatible(_:) 拉取正確的那一個。

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

.contentTagging 是 Apple 提供的兩個 SystemLanguageModel.UseCase 靜態屬性之一,本系列的 姊妹篇 已詳述。它是 Apple 託管的專業化方案,不需權利描述檔,隨框架附贈。自訂 Adapter 是開發者託管的對應品,適用於 Apple 使用情境未涵蓋的任務。Apple 的文件在描述 .contentTagging 的內部運作時使用了「adapted」一詞,但這與正式的 Adapter 型別並不相同。本篇文章涵蓋的是這個正式型別。

我必須訓練 draft model 嗎?

不必。Apple 的文件:「If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.」² Adapter 仍可載入並提供服務;您只是無法享有推測式解碼帶來的推論加速。Draft model 是選擇性的第二輪訓練。

參考資料