SwiftLM：Apple Silicon 原生 MLX Swift 大型語言模型推理伺服器

我們會認真閱讀每一則回饋並重視您的意見。

欲查看所有可用的限定詞，請參考我們的文件。

載入時發生錯誤，請重新整理此頁面。

SwiftLM 是一款極速的原生 Swift 推理伺服器，能以嚴格的 OpenAI 兼容 API 提供 MLX 模型服務。

無需 Python 執行環境，無全域直譯器鎖（GIL），也無不必要的記憶體複製。它直接以 Apple Silicon 裸機效能編譯成單一二進位檔。

請從 Releases 頁面下載最新版本壓縮包。該檔案為自包含格式，mlx.metallib 與二進位檔一同打包。

建置腳本會自動處理子模組、cmake、Metal 核心編譯及 Swift 建置。

啟動伺服器後（若模型未快取則會自動下載）：

（執行大型 MoE 模型時，加入 --stream-experts 參數可繞過 macOS 虛擬記憶體交換，直接從 NVMe SSD 流式讀取專家層。）

我們以 gemma-4-26b-a4b-it-4bit 模型在 512 / 40K / 100K 代幣上下文中測試三種配置。

* 時間加權平均：total_tokens / sum(60/TPS) — 正確反映實際時間的平均值。

您可執行 python3 -u scripts/profiling/profile_runner.py --model gemma-4-26b-a4b-it-4bit --contexts "512,40000,100000" 在您的裝置上重現測試。

以下為 gemma-4-26b-a4b-it-4bit（26B MoE，4-bit）在 M5 Pro 64 GB 上的基準測試結果。

數值以生成速度 · GPU 記憶體使用量表示。

您也可執行 ./run_benchmark.sh 在自己的裝置上產生這些指標（詳見下方基準測試與測試章節）。

M1 Ultra 上全 RAM（無 SSD 流式）MoE 推理的基準結果。相較早期版本，mlx-swift-lm 中 needsMoeFlush 門控帶來約 3.4 倍的性能提升（詳見 SwiftLM #84）。此門控避免了全 RAM 路徑中每層 GPU 同步障礙無條件觸發，從而防止 MLX 核心批次管線被沖刷。

硬體：Apple M1 Ultra，64 GB 統一記憶體，macOS 26.x。模型約 20 GB 磁碟大小，運行時約 21.6 GB 常駐權重 + 2.1 GB KV 快取。參數：--repeat-penalty 1.1 --max-tokens 2000，溫度 0.6，單流 /v1/chat/completions。未啟用 needsMoeFlush 門控的基準為 19.2 / 18.1 / 18.3 tok/s。

⚠️ 目前此模型的 DFlash 不適合生產環境。DFlash 採用純貪婪（argMax）解碼，無視溫度設定，導致在 Qwen3.6-35B-A3B 及其草稿模型中陷入低熵吸引子（如「and and and...」、「**UMA** **UMA**...」）。先前 70 tok/s 的 DFlash 數據為退化輸出，因草稿與目標均鎖定同一詞元而獲得高接受率。重複懲罰在部分提示有效，但在其他情況下降低接受率。正確解決方案為採用 Leviathan/Chen 所定義的隨機後驗採樣與拒絕接受機制，這是 DFlash 架構變更，詳見 z-lab/dflash#91。

模型：Thump604/DeepSeek-V4-Flash-MLX-Q3-mixed-gs128-affine

Dense/Vanilla 與 TurboQuant（非 SSD）配置會自動跳過，因為 126 GB 模型超出實體 RAM。

數值以生成速度 · 峰值實體 RAM 使用量表示（於預填充與生成期間每 0.5 秒取樣）。126 GB 模型其餘部分從 NVMe SSD 流式讀取。

SwiftLM 動態映射 Apple MLX 原語至標準 HuggingFace 架構，實現最新開放權重模型的原生 Metal 推理。

可加上 --audio 參數執行。僅 gemma-4-e4b 變體包含音訊模組。

提供原生 iPhone 與 iPad 伴隨應用程式，直接從 HuggingFace 下載 MLX 模型，並透過 MLX Swift 在裝置端執行推理。

📱 已於 iPhone 13 Pro（6 GB）實機運行 — 無需 Python、伺服器或 GIL，純裝置端 MLX 推理透過 Metal GPU 實現。

貢獻者注意：.xcodeproj 檔案被 git 忽略（含個人 Team ID）。克隆後請執行 generate_xcodeproj.py 以本地重新生成。您的 Team ID 不會被提交。

SwiftLM 實作混合 V2+V3 TurboQuant 架構，實時壓縮 KV 快取。整體約 3.6 位元／座標，KV 快取相較 FP16 壓縮約 3.5 倍，且幾乎無精度損失。

近期 TurboQuant 演算法重現（如 turboquant-mlx）揭示兩條不同路徑：

我們打造了「聖杯」混合方案：將 V3 非線性 Lloyd-Max 編碼表直接移植至原生 C++ 編碼路徑，並在融合 Metal（bggml-metal）著色器中原生處理解量化。此方案達成 V3 品質與 V2 速度，完全擺脫 Python 開銷。

K-Cache（3-bit PolarQuant + 1-bit QJL）= 4.25 位元／維度

V-Cache（3-bit PolarQuant）= 3.125 位元／維度

因 V-cache 矩陣不參與內積注意力評分，QJL 誤差修正無效益。我們乾淨地禁用 V-cache 的 QJL，額外節省 25% 記憶體且不犧牲品質。

參考實作：turboquant-mlx | turboquant_plus | 論文：TurboQuant, Google 2504.19874

SwiftLM 實作重新設計的 SSD 專家流式管線（由 Eric Lake 工程設計），在記憶體受限的 Apple Silicon 上為大型 Mixture of Experts（MoE）模型帶來 10 倍生成速度提升。此技術允許在 64 GB Mac 上運行如 Qwen3.5-122B（69.6 GB）與 Qwen3.5-397B（209 GB）等模型，透過 NVMe SSD 流式讀取專家權重。

記憶體穩定於約 10.6 GB 常駐，無交換活動。測試超過 200 代幣生成。

此架構一大創新是雙模型推測解碼模式：小型草稿模型（如 Qwen3.5-9B，73 tok/s）完全在 RAM 運行，大型 MoE 模型（如 122B）則從 SSD 流式讀取專家。草稿模型高速產生候選詞元，主模型批量驗證，大幅減少 SSD 綁定的生成輪數。

性能提示：結合 --stream-experts 與 --draft-model 需謹慎。驗證階段同時送出 N+1 個詞元，每個詞元路由至不同專家，SSD I/O 隨所有位置專家選擇的聯集擴大。預設 --num-draft-tokens 4 時，造成 5 倍 I/O 擴散，導致吞吐量低於單獨 SSD 流式。

自動上限策略（Issue #72 修正）：當兩參數同時啟用時，SwiftLM 自動將 --num-draft-tokens 限制為 1。此時驗證階段僅覆蓋 2 個位置（2 倍擴散）。若草稿模型接受率≥50%（同族模型常見），淨吞吐量仍為正，儘管有 2 倍 I/O 負擔。啟動時會顯示提醒。

最高吞吐量建議：僅使用 --stream-experts（不搭配草稿模型）。

SwiftLM 支援兩種推測解碼方式以加速 RAM 內推理：

1. 同時載入小型草稿模型與大型主模型。草稿模型高速產生候選詞元，主模型批量驗證。需同時傳入 --model 與 --draft-model。

2. 對於原生 MTP 頭訓練的模型（如 Qwen3 系列），SwiftLM 自動利用隱藏 MTP 層於單次前向傳播中草擬未來詞元，完全免除載入獨立草稿模型。

算法等價性（Leviathan 等人）：SwiftLM 在 MTPTokenIterator 中實作嚴謹的概率拒絕採樣（依 Leviathan 等人定義），確保在非零溫度下輸出與目標模型真實分布數學等價，正確評估 $P_{target} / P_{draft}$ 並於拒絕時重新採樣修正分布。

MTP 嚴格為計算綁定優化。我們成功驗證算法等價性並在完全適配 64GB VRAM 的密集 Qwen/Qwen3.6-27B 模型上達成 15% 以上 TPS 加速。

然而，在 64GB Mac 上對大型 MoE 模型（如 Qwen3.6-35B-A3B）執行 MTP 需搭配 --stream-experts 從 NVMe SSD 讀取 MoE 權重。因 MTP 會平行評估多個草稿詞元，驗證階段造成大量 I/O 擴散，嘗試同時從 SSD 讀取多達 3 倍獨特專家，飽和 NVMe 頻寬，導致 GPU 停滯並完全抵消 MTP 加速。若使用 64GB Mac，35B 以上 MoE 模型執行 MTP 反而比基線慢。

（社群協助需求：我們積極尋找優化方案以在 MTP 驗證期間批次預取專家，期望在 64GB 統一記憶體限制下實現可行性！）

為達成 SSD 專家流式與推測解碼的極致記憶體效率與速度，SwiftLM 依賴繞過標準統一記憶體限制的自訂 C++ 原語。

我們維護自訂分支（SharpAI/mlx 與 SharpAI/mlx-c），支援離核心記憶體映射執行，透過自訂 Metal 核心（ssd_streamer.mm 與 fence.air）直接從 SSD（NVMe）流式傳輸張量區塊至 GPU。官方 ml-explore 倉庫尚未原生支援此功能。

欲深入了解倉庫架構、上游同步、特定自訂補丁及何時可安全回歸 Apple 原生上游，請詳閱完整文件：👉 上游 MLX 同步與 SSD 流式維護

可透過互動式腳本執行自動化基準測試套件：

腳本提供互動選單，可選擇任一模型並執行兩種自動化測試套件之一：

1. 測試生成速度（TPS）與 Apple Metal GPU 記憶體分配，涵蓋極端上下文長度（如 512、40000、100000 代幣）。

2. 驗證引擎 KV 提示快取在交錯長上下文與滑動窗口注意力範圍時的穩定性。

測試方式為在標準對話評估（--prefill-size 512）下精確生成 20 個詞元，以捕捉精確的詞元生成速度（TPS）與 Apple Metal 記憶體使用上限。

欲在您的機器上執行此自動化套件，請執行：

🧠 運作原理：SwiftLM 實作分塊預填充（由 --prefill-size 控制，預設 512），功能等同 llama.cpp 的 --batch-size 參數，並模仿 mlx-lm Python 函式庫防止在大序列解析時 $O(N^2)$ 統一記憶體過度分配的參考實作。

⚠️ 量化聲明：雖然更重的量化可縮小記憶體需求，4-bit 量化仍為 MoE 模型的嚴格生產標準。我們的指標顯示激進的 2-bit 量化嚴重破壞 JSON 語法，經常產生錯誤鍵如 \name\ 取代 "name"，系統性破壞 OpenAI 兼容的工具調用。

完全相容標準 OpenAI HTTP 用戶端：

欲執行視覺模型（如 mlx-community/Qwen2-VL-2B-Instruct-4bit），啟動 SwiftLM 時加入 --vision 參數：

您可直接傳送標準 OpenAI base64 編碼影像，SwiftLM 會原生透過 Metal 處理硬體空間映射。

除標準 OpenAI 欄位（temperature、top_p、max_tokens 等）外，SwiftLM 在 POST /v1/chat/completions 接受以下特定欄位。

「2+2=4」的頓悟時刻：開發過程中，我們遇到嚴重的「靜默失敗」，模型成功載入並高速評估所有 32 層，但生成內容全為無限空白。模型 logits 顯示形狀正確但幅度錯誤。

突破點在於發現缺少嵌入縮放。Gemma 架構要求將嵌入輸出乘以 sqrt(hidden_size)。對於隱藏層大小 2816，缺少此步驟意味網路中每個激活值約小 53 倍！加入單一數學運算：h = h * MLXArray(Float(config.hiddenSize).squareRoot())

模型立即從「耳語」空白中甦醒，成功回答「2+2 等於多少？」為「2 + 2 等於 4。」證明從 Swift 到 Metal 的整個龐大結構管線運作正常。

SwiftLM 依賴強大的 Apple MLX 社群基礎，並大量借助開源生態系統。雖然自訂 C++ 實作、Metal 優化與高效能管線架構為本引擎原生設計，我們仍感謝以下專案與貢獻者提供不可或缺的參考資料與底層協議。

⚡ Apple Silicon 原生 MLX Swift 大型語言模型推理伺服器，具備 OpenAI 兼容 API、百億參數以上 MoE 模型 SSD 流式傳輸、TurboQuant KV 快取壓縮，支援 macOS 與 iOS iPhone 應用程式。