MLX 模型移植與最佳化

任務

產出正確、可複現、架構感知的 MLX 實作。正確性優先於速度。任何關於速度或記憶體的宣稱都必須指明硬體、軟體版本、工作負載、基線與品質門檻。

不可協商的規則

在接取階段切勿執行未受信任的模型程式碼。 靜態檢查 JSON、safetensors 標頭、原始碼與授權。將 auto_map、自訂模組、安裝鉤子與 trust_remote_code 視為審查關卡。
鎖定來源。 記錄倉庫、修訂版、模型檔案、分詞器/處理器修訂版、授權以及校驗和或工件清單。
在移植前建立來源 Oracle。 凍結確定性測試夾具（fixtures），並在有意義的邊界處擷取中間張量。
優先移植最小的急切執行路徑。 在基礎正確性核對通過之前，不得進行量化、編譯、自訂核心、批次處理或推測性解碼。
一次僅改變一個最佳化維度。 保留量測與回退記錄。
優先使用原生 MLX 操作。 在撰寫自訂 Metal 核心前，先嘗試內建的融合操作、佈局變更、快取設計與 mx.compile。
不要機械化地翻譯 CUDA 的慣例。 CUDA 技術僅在證明其 Metal/MLX 瓶頸與實作方式後，才成為研究候選。
切勿以吞吐量隱藏品質退化。 對於音訊、語言、視覺與生成模型，除張量誤差容許範圍外，還應使用任務特定的品質檢查。
未經授權與來源檢查，不得發布轉換後的權重。 保留原始模型卡、歸屬資訊、生成設定、分詞器/處理器檔案以及轉換配方。
每日研究自動化僅供審閱。 可收集與排序候選項目，但不得靜默改寫操作手冊或合併建議。

工作流程

1. 檢查與分類

執行：

python3 scripts/inspect_model.py MODEL_OR_DIRECTORY --output inspection.json
python3 scripts/make_port_plan.py inspection.json --output PORT_PLAN.md
python3 scripts/recommend_optimizations.py inspection.json --markdown OPTIMIZATIONS.md

閱讀接取與路由。確認：

任務與模型領域；
架構家族與遞迴/快取狀態；
來源框架與自訂操作；
參數數量、資料類型、繫結/共享權重、分片與適配器；
前處理、分詞、取樣與後處理；
授權與遠端程式碼風險；
目標 Mac、記憶體預算、延遲/吞吐量目標與品質目標。

若架構、來源修訂版或評估目標仍不明確，請勿開始實作。將不確定性記錄在 PORT_PLAN.md 中，而非進行猜測。

2. 選擇最接近且經過驗證的 MLX 參考

查閱模型支援對應表與 assets/architectures.yaml。

使用此優先順序：

官方 MLX / MLX-LM 實作；
活躍的 MLX-VLM 或 MLX-Audio 實作並附測試；
活躍的第三方 MLX 實作；
上游來源實作加上架構論文；
需要全新 MLX 實作的研究原型。

重用架構模式，而非複製假設。根據已鎖定的來源驗證設定語意與張量佈局。

3. 建立來源 Oracle

遵循並行性與測試：

設定確定性隨機種子與推論模式；
在前處理後保存確切的輸入；
在嵌入/前端、每個區塊組、瓶頸、快取更新、logits/潛在變數以及解碼器/聲碼器輸出處，擷取形狀/資料類型/統計量以及選定的張量；
將來源輸出保存為可攜帶的 .npz、.json 或 .wav 測試夾具（fixtures）；
按資料類型與操作記錄誤差容許範圍；
至少包含一個最小案例、一個一般案例與一個邊界案例。

4. 實作最小的急切執行 MLX 圖形

閱讀核心移植方法與匹配的架構操作手冊：

初始實作限制：

僅使用浮點權重；
批次大小為一，除非批次處理為固有行為；
不使用編譯裝飾器；
不使用自訂核心；
使用明確的狀態與快取物件；
在每個非平凡轉換處加入形狀斷言；
可逆的權重映射清單。

5. 確定性地轉換權重

建立包含來源鍵、目標鍵、來源形狀、目標形狀、轉換方式、資料類型以及繫結/共享規則的權重映射。驗證它：

python3 scripts/validate_weight_map.py   --source source-manifest.json   --target target-manifest.json   --mapping WEIGHT_MAP.json

切勿依賴載入時的 strict=False 來隱藏遺失或多餘的權重。將每個例外分類為：故意忽略、生成、共享或不支援。

6. 通過正確性階梯

使用 scripts/compare_tensors.py，並依序通過：

設定與前處理正確性；
權重覆蓋率與轉換後形狀正確性；
單一基本元素/區塊正確性；
階段式中間結果正確性；
端到端確定性正確性；
任務品質正確性；
快取/狀態與增量生成正確性；
邊界、長輸入、串流與批次正確性。

當正確性失敗時，使用失敗分析。不要對失敗的圖形進行最佳化。

7. 在選擇最佳化前先進行效能分析

閱讀基準測試。分離：

預填充/編碼器/前端時間；
每 token 或每幀解碼時間；
編解碼器/聲碼器/後處理時間；
編譯與首次執行成本；
峰值與穩定記憶體；
資料移動、同步與 Python 開銷。

使用：

python3 scripts/benchmark_command.py --warmup 2 --runs 8 --output benchmark.json -- COMMAND ...

8. 套用最佳化階梯

查閱 assets/optimization_guidance.yaml、assets/recommendation-taxonomy.yaml、assets/techniques.yaml，並僅載入相關指南：

預設順序：

移除非預期的求值與主機傳輸；
修正資料類型與張量佈局；
使用原生融合操作與快速 SDPA；
減少配置並使狀態/快取更新明確化；
編譯穩定區域並控制重新編譯；
在架構允許時對預填充/前端進行分塊或串流處理；
最佳化 KV/快取策略與批次處理；
量化權重，若有正當理由則進一步量化 KV/狀態；
僅對相容的自迴歸路徑添加推測性或多 token 解碼；
僅在效能分析證明存在剩餘核心瓶頸時，才撰寫自訂 Metal 核心。

對於每項變更，記錄假設、差異、正確性結果、基準測試結果、記憶體結果、品質結果，以及保留/回退決定。

9. 封裝與發布

遵循封裝與發布。包含：

已鎖定的來源與轉換命令；
相容的 MLX 與函式庫版本；
模型/設定/分詞器/處理器檔案；
精確的量化配方與排除項；
確定性冒煙測試；
基準測試協定與原始結果；
已知限制；
原始授權與歸屬；
無未經支援的「更快」或「無損」等措辭。

10. 產出工程報告

最終回應必須總結：

架構與選定的操作手冊；
來源修訂版與證據參考；
實作與權重映射狀態；
正確性矩陣；
基線與最佳化指標；
接受與拒絕的最佳化；
剩餘風險與不支援的路徑；
可複現的命令與工件位置。

使用 assets/ 中的範本。

何時停止

在以下情況應停止並回報，而非臨場發揮：

來源授權禁止所要求的散布形式；
所需來源行為僅存在於未經審查的遠端程式碼中；
經過階段式檢查後仍無法定位正確性問題；
某項最佳化改善了微基準測試，但惡化了端到端延遲、記憶體或品質；
自訂核心缺少可攜帶的備用方案或充分的測試；
硬體、MLX 版本、工作負載或品質目標在效能宣稱中缺失。

維護

關於來源審查、安全性與每日候選管線，請閱讀維護與來源。在散布此技能前，執行 scripts/audit_skill.py 與 scripts/validate_sources.py。

MLX 模型移植與最佳化技術代理