AnyLanguageModel 1.0：苹果平台一套API切换本地与云端模型

原文要点

Hugging Face 发布 AnyLanguageModel 1.0（配套 swift-huggingface 1.0、swift-xet 1.0）：它是苹果 Foundation Models 框架的 drop-in 替代，把 import FoundationModels 换成 import AnyLanguageModel 后，同一套会话代码可切换系统模型、llama.cpp/MLX/Core ML 本地开源权重模型，以及 OpenAI、Anthropic、Gemini、Ollama、OpenRouter、Hugging Face Inference Providers 等托管服务。1.0 补齐各服务商的工具调用、引导生成（含嵌套 @Generable）、图片输入、推理过程记录；API 密钥改为闭包返回，便于服务器签发短期令牌；并支持 Linux 服务端。文中举例模型体积：Gemma 4 E2B GGUF Q4_0 约 3.4 GB、LFM2.5 2.6B GGUF Q4_K_M 约 1.7 GB（均可上 iPhone）、MLX 版 Qwen3.8 27B 4bit 约 16 GB（需 32 GB 内存 Mac）。

这次做成什么

在一个已有（或新建）的 Swift 应用里完成三件事：接入 AnyLanguageModel 1.0、用一行代码切到本地 MLX 模型、再用同一套会话代码切到 Hugging Face Inference Providers 上的托管大模型。练习方案：先在 Mac 上跑通本地小模型，再切换托管端点对比输出。

准备什么

• 安装 Xcode 的 Mac（本地 MLX 27B 模型需 32 GB 及以上内存；小模型要求更低）
• Swift 5.x 项目，可用 Swift Package Manager 添加依赖
• Hugging Face 账号及 HF_TOKEN 环境变量（仅在用 Inference Providers 时需要）
• 若目标是 iPhone 真机，需开发者证书与足够的设备存储空间放 GGUF 模型

具体怎么做

1. 添加 1.0 包依赖

   在 Package.swift 的 dependencies 中加入材料一的条目：仓库 https://github.com/huggingface/AnyLanguageModel，from: "1.0.0"，并按需声明 traits（如 ["MLX"] 启用 MLX 后端）。若从旧版升级，先读 AnyLanguageModel、swift-huggingface、swift-xet 三个仓库的 release notes 迁移指南再改代码。

2. 一行替换导入并复用会话代码

   把源文件顶部 import FoundationModels 改成 import AnyLanguageModel。原文称同一套 Foundation Models 风格的会话代码即可继续工作，因此原有会话、prompt、响应处理逻辑不必重写，这也是该库的核心卖点。

3. 选择本地模型

   在 Mac 上用一行 let model = MLXLanguageModel(modelId: "mlx-community/Qwen3.8-27B-4bit") 选用 MLX 模型（约 16 GB，需 32 GB 内存）；想在 iPhone 上跑则选 GGUF 小模型，如 Gemma 4 E2B（Q4_0 约 3.4 GB）或 LFM2.5 2.6B（Q4_K_M 约 1.7 GB），通过 llama.cpp 后端加载，首次使用会经 swift-huggingface/swift-xet 从 Hub 加速下载权重。

4. 切换托管大模型

   本地跑不动的大模型用 OpenAILanguageModel 指向 OpenAI 兼容端点，见材料二：baseURL 设为 https://router.huggingface.co/v1/，model 例如 "openai/gpt-oss-120b"。1.0 起 apiKey 参数是闭包而非字符串，应让闭包从环境变量或你自己的令牌服务取短期令牌，不要把长期密钥硬编码进 App。

5. 验证切换的一致性

   用同一段会话代码分别连本地 MLX 模型与托管模型，发同一个测试 prompt（见示例），确认两侧都能返回文本、工具调用与引导生成在两侧行为一致。切换服务商时推理记录块会在新服务商不支持时自动省略，无需手工清理。

可直接复制的材料

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

import AnyLanguageModel

let model = OpenAILanguageModel(
    baseURL: URL(string: "https://router.huggingface.co/v1/")!,
    apiKey: ProcessInfo.processInfo.environment["HF_TOKEN"]!,
    model: "openai/gpt-oss-120b",
    apiVariant: .chatCompletions
)

let model = MLXLanguageModel(modelId: "mlx-community/Qwen3.8-27B-4bit")

输入与输出示例

本站虚构演示，未实际编译运行；返回文案为示意，两次调用文本不会逐字相同。

输入

在 32 GB 内存的 Mac 上，用同一会话代码发送 prompt："用一句中文解释什么是量化"，先连 MLXLanguageModel（Qwen3.8-27B-4bit 本地），再改成 OpenAILanguageModel（router.huggingface.co 上的 gpt-oss-120b）。

对应输出

本地 MLX 返回示例："量化是把模型权重从高精度数字压缩成低精度数字，用更小体积换取可接受的精度损失。" 切到托管模型后，同一行会话调用返回含义相近的另一句话；除 model 初始化那几行外，其余代码没有改动。

做完检查这些

• Package.swift 解析依赖成功，import AnyLanguageModel 编译通过
• 本地 MLX 模型能下载权重并对测试 prompt 返回中文文本
• 仅改模型初始化、不动会话代码即可切到托管端点并拿到响应
• apiKey 以闭包/环境变量方式提供，源码中检索不到硬编码的长期密钥

容易卡住的地方

• 27B 4bit 模型约 16 GB，16 GB 内存 Mac 上会失败，先按内存选模型再选后端
• 1.0 的 apiKey 由字符串改为闭包，旧代码直接传字符串会编译报错，需按迁移指南改写
• 门类型号或 Inference Providers 需要有效 HF_TOKEN，缺失时在请求阶段报鉴权错误
• 引导生成、工具调用虽宣称全服务商支持，但各服务商能力上限不同，复杂嵌套 @Generable 仍需逐个验证
• iPhone 上跑 GGUF 模型需预留数 GB 存储，下载前确认设备空间
• Linux 支持面向服务端场景，苹果系统模型与 Core AI 模型仅在苹果 OS 27 上可用