huggingface/AnyLanguageModel

AnyLanguageModel – 多種 LLM 後端的 Swift 首選抽象層

是什麼

• 一個 Swift 套件，以統一的 Apple 風格 API 取代 Apple 的 FoundationModels 導入，支援多種 LLM 提供商（Apple、Core ML、MLX、llama.cpp、Ollama、Anthropic、OpenAI、Gemini 等）。
• 你只需將匯入語句從 import FoundationModels 改為 import AnyLanguageModel，其餘程式碼保持不變即可使用。

核心概念

• LanguageModelSession – 持有模型實例和可選的 工具（模型可呼叫的函數）清單的物件。所有互動皆透過 session.respond { … } 進行。
• 引導生成 – 使用 @Generable 和 @Guide 屬性包裝器，讓模型產生強型別的 Swift 結構體，而非解析原始文字。
• 工具呼叫 – 定義一個符合 Tool 協定的型別（例如天氣查詢），讓模型自行決定何時呼叫。可透過 ToolExecutionDelegate 觀察或批准每次呼叫。
• 特性（Traits） – Swift Package Manager 的 特性 允許你僅啟用所需的重型後端（CoreML、MLX、Llama），從而保持二進位檔案體積小。

支援的提供方（README 中的核取方塊表示已實作）

• Apple Foundation Models（iOS 26/macOS 26+ 上的系統模型）
• Core ML（裝置端的 .mlmodelc 檔案）
• MLX（透過 mlx-swift 實現 Apple Silicon 加速模型）
• llama.cpp（GGUF 量化模型）
• Ollama HTTP API（本地或遠端 Ollama 伺服器）
• Anthropic Messages API
• Google Gemini API
• OpenAI Chat Completions & Responses API
• Open Responses（任何與 OpenAI 回應格式相容的端點）

安裝

// Package.swift
dependencies: [
    .package(url: "https://github.com/huggingface/AnyLanguageModel", from: "0.11.0")
]

若需特定後端，啟用其特性：

.package(
    url: "https://github.com/huggingface/AnyLanguageModel",
    from: "0.11.0",
    traits: ["CoreML", "MLX"]
)

使用特性時，還需加入底層套件（CoreML → huggingface/swift-transformers，MLX → ml-explore/mlx-swift-lm，Llama → mattt/llama.swift）。README 提供了無法直接宣告特性的專案所用的完整 Xcode 模擬工作流程。

典型用法

import AnyLanguageModel

let model = SystemLanguageModel.default          // 或 CoreMLLanguageModel(...), MLXLanguageModel(...), 等
let session = LanguageModelSession(model: model)

// 簡單提示
let resp = try await session.respond { Prompt("用一句話解釋量子計算") }
print(resp.content)

引導生成範例

@Generable(description: "關於一隻貓的基本資訊")
struct CatProfile {
    var name: String
    @Guide(description: "貓的年齡", .range(0...20))
    var age: Int
    @Guide(description: "一句話的性格描述")
    var profile: String
}

let profile = try await session.respond(
    to: "生成一隻可愛的救援貓的資料",
    generating: CatProfile.self
).content

模型直接回傳一個 CatProfile 實例。

工具呼叫

struct WeatherTool: Tool {
    let name = "getWeather"
    let description = "取得某城市的最新天氣資訊"

    @Generable
    struct Arguments { @Guide var city: String }

    func call(arguments: Arguments) async throws -> String {
        "The weather in \(arguments.city) is sunny and 72°F"
    }
}

let session = LanguageModelSession(model: model, tools: [WeatherTool()])
let answer = try await session.respond { Prompt("Cupertino 的天氣怎麼樣？") }
print(answer.content)

可附加代理以觀察或批准工具呼叫。

影像輸入 許多雲端提供方（OpenAI、Anthropic、Gemini、Open Responses）和部分本地後端（MLX、Ollama）支援影像輸入：

let resp = try await session.respond(
    to: "描述你看到的內容",
    images: [.init(url: URL(string: "https://example.com/photo.jpg")!)]
)

README 中的表格列出了哪些提供方支援影像。

安全建議 README 強調 切勿硬編碼 API 金鑰。推薦兩種生產環境模式：

1. 自帶金鑰（Bring-Your-Own-Key） – 將使用者提供的金鑰儲存在系統 Keychain 中，並直接發送給提供方。
2. 代理伺服器 – 將提供方金鑰保留在你控制的後端，向 App 公開一個短期金鑰，並轉發請求。 兩種方法均附有優缺點說明。

為何要使用它

• 一次撰寫，到處執行：相同的 Swift 程式碼可在裝置端（Core ML、MLX、llama.cpp）和雲端（OpenAI、Anthropic、Gemini、Ollama）運行。
• 透過引導生成實現強型別輸出，減少脆弱的字串解析。
• 內建工具呼叫支援，可建構代理式應用（如能取得天氣、查詢資料或執行自訂程式碼的助手）。
• 基於特性的相依性管理，使最終應用輕量化。

目前限制

• Apple Foundation Models 需要 iOS/macOS 26，撰寫時仍為未來作業系統版本。
• llama.cpp 不支援工具呼叫。
• v0.11 版本因建置問題移除了 LiteRT 後端。

進一步學習

• README 提供了 Apple 的 Guided Generation 文件、各提供方 API 以及範例 Xcode 專案（chat-ui-swift）的連結。
• 問題 #15 和 #135 討論了已知的 Xcode/SwiftPM 問題及變通方案。

---

總結：AnyLanguageModel 是一個真正的、生產就緒的 Swift 庫，抽象了廣泛的語言模型提供方，增加了第一類工具呼叫和類型化生成功能，並利用 Swift Package Manager 特性保持二進位檔案小巧。它面向希望在裝置端和雲端 LLM 上使用統一 API 的 iOS/macOS/visionOS 開發者。