Laya‑MLX – 在 Apple Silicon 上實現快速、類型化決策推論

是什麼 – 一個 Python 套件，可在 macOS Apple Silicon（M 系列）GPU 上完全本地運行 Laya 決策語言模型系列。該庫將原始 Convai Innovations 檢查點移植到 MLX（Apple 的 Metal 加速張量庫），從而無需 PyTorch、🤗 Transformers 或雲端呼叫，即可對單個簡短問題實現低於 15ms 的延遲。支援類型化輸出（選擇、評分、二元「noul」），避免逐 token 解碼，實現確定性、低延遲回應。

---

核心理念

概念	Laya‑MLX 的實現方式
類型化決策	不生成自由文本，而是透過一次前向傳播返回結構化答案（選擇、評分或二元「noul」）。避免逐 token 解碼，實現確定性、低延遲輸出。
雙向編碼器	輸入（狀態 + 問題）使用 ModernBERT-large 或 mmBERT-base 主幹網絡編碼，然後專用頭部生成請求類型的概率。
本地運行，無執行時依賴	所有推論均在 MLX 中執行；分詞使用 Hugging Face 的 Rust 分詞器，已編譯進 wheel 包。無需 PyTorch/Transformers 二進制文件。
Apple Silicon 優化	可選 compile=True、前綴快取和填充技巧在 M3 Max 上可提升約 6% 速度；庫還提供預轉換的 FP16 檢查點以供 GPU 使用。

---

快速開始（30 秒）

pip install laya-mlx            # 核心庫
pip install 'laya-mlx[demo]'    # 可選的示範工具

import laya_mlx as laya
agent = laya.load("aac6fef/laya-mlx")   # 首次使用時下載 FP16 檢查點
result = agent.predict(
    "I was billed twice. Please refund the duplicate.",
    {
        "department": {
            "type": "choice",
            "instructions": "Who should handle this?",
            "criteria": ["billing", "technical", "sales"]
        }
    },
)
print(result["answers"]["department"])   # → "billing"

支援 macOS 14+、Python 3.11+ 和任意 Apple Silicon GPU（M1–M3）。首次呼叫會下載模型；後續呼叫完全離線。

---

可用檢查點

模型 ID（載入）	編碼器	參數量	上下文長度	語言
aac6fef/laya-mlx	ModernBERT-large	421 M	512	英語
aac6fef/laya-multilingual-mlx	mmBERT-base	322 M	1 024	多語言
aac6fef/laya-typed-decisions-mlx	ModernBERT-large	421 M	1 024	英語（類型化決策工作流程）

以上三個均為上游 Convai Innovations 權重的精確 FP16 轉換版本，托管於 Hugging Face。您也可將 laya.load 指向原始 Hub ID（如 convaiinnovations/laya 等），庫會自動下載並轉換。

---

性能（M3 Max，FP16）

指標	英語（Laya 421M）	多語言（Laya-multilingual 322M）
單個簡短問題的中位延遲	13.4 ms	7.4 ms
95 百分位延遲	13.9 ms	7.8 ms
50 問題批量（批量大小 64）吞吐量	146 q/s	395 q/s
每請求峰值 GPU 內存	944 MiB	688 MiB
優化版 laya‑snake --optimize --max‑speed	75.4 moves/s（比 eager 快約 6.5%）

數值包含分詞、張量準備、推論、校準和結果格式化；不包含模型載入時間。

---

主要 API 接口

agent = laya.load(
    checkpoint,          # HF 倉儲 ID 或本地路徑
    dtype="float16",   # 或 "float32", "bfloat16"
    batch_size=16,       # 單次前向傳播最大問題數
    device="gpu",       # "cpu" 也支援（慢得多）
    compile=False,       # 啟用 MLX 編譯以提升速度
    cache_prompts=False, # 保留分詞後的提示以複用
)

# 預測 – `system_one` 是別名
answers = agent.predict(state, questions)

*state 可為普通字串、JSON 字典或歷史訊息列表。questions 為字典，每個條目描述期望的回答類型（choice, score, noul）。回傳值包含：

• answers（結構化結果）
• action.act_probability（原始頭部機率）
• token 使用統計
• 四捨五入至小數點後四位（與上游模型一致）。

路由器輔助工具

適用於需要自動選擇語言特定檢查點的應用：

router = laya.Router(dtype="float16", max_loaded=2)
out = router.predict(state, triage_questions())
print(out["routing"])   # 例如："multilingual"

路由器最多可常駐 max_loaded 個模型，也可透過 Router(preload=True) 預載入。

---

命令列工具

命令	用途
laya-mlx predict …	從 JSON 檔案或內聯字串執行單次推論。
laya-mlx convert …	將 Hugging Face 檢查點轉換為 MLX 兼容目錄（safetensors + config）。
laya-snake	互動式終端示範，運行經典貪吃蛇遊戲，每步調用模型。使用 --optimize 可啟用編譯後的快速路徑。

所有 CLI 均接受與 laya.load 相同的 --model 參數。

---

開發與測試

• 依賴項：專案使用 uv 實現可重現環境。執行 uv sync --extra dev 可拉取測試、基準測試和參考擴展。
• 測試：單元測試將 MLX 實現與原始 Transformers 頭部在小型隨機模型上進行對比；完整檢查點驗證涵蓋分詞、校準機率、確定性重複和記憶體增長。
• 基準測試：benchmarks/run 測量延遲/吞吐量；結果儲存於 benchmarks/results，並在 BENCHMARKS.md 中總結。
• 研究：docs/ 檔案夾包含關於性能瓶頸的深度報告及 10 倍加速的構想（數學、工程、實作層面）。腳本位於 experiments/。

---

許可與署名

• 程式碼 – Apache-2.0（見 LICENSE）。
• 權重 – 原始 Laya 權重版權歸 Convai Innovations 所有；透過上述 Hugging Face 倉儲以相同許可證重新分發。
• 移植 – MLX 重實作及周邊工具由 mizorewww 編寫，並借鑒了上游 NandhaKishorM/laya 倉儲的部分內容（NOTICE 中有 MIT 風格署名）。

---

誰會使用它？

• 產品團隊：需要在裝置端實現確定性、低延遲路由或分類（如工單分診、緊急程度評分、二元策略檢查）。
• 開發者：建構僅限 macOS 的 AI 助手或邊緣服務，不希望將資料傳送至雲端。
• 研究人員：希望在 Apple GPU 上對比 MLX 與 PyTorch/Transformers 性能，或探索進一步加速技術。

---

TL;DR – Laya‑MLX 為 Apple Silicon 上的 Laya 決策模型提供即開即用的高性能推理庫，擁有簡潔的 Python API、終端貪吃蛇示範，以及完整的轉換、基準測試和模型卡發佈工具鏈。