Core ML Snake：即時機率，本地推理

終端演示在每一步都執行一個真實的 Laya 模型。左面板顯示棋盤、分數和蛇長；右面板顯示方向機率、估計的死路風險、食物可達性、實測預測時間、引擎、零輸出 token 和離線推理狀態。

在 Apple Silicon Mac 上啟動

pip install 'laya-coreml[demo]'
hf download aac6fef/laya-multilingual-coreml-ane --local-dir models/snake
laya-coreml-snake --model ./models/snake --fps 12

使用至少 104 列 × 35 行、等寬字型並支援 truecolor 的終端。模型載入和初始 Core ML 編譯在遊戲開始前進行，首次執行可能需要幾十秒。每秒十二次決策是一個清晰可讀的呈現速度，不是硬體上限。

在顯式下載之後，模型路徑完全在本地。用未快取的 Hub ID 啟動遊戲會帶著說明失敗，而不是在顯示 OFFLINE 的同時去下載。執行時不需要 MLX、PyTorch 或 Transformers。

終端太小時 UI 會等待。--no-alt-screen 把最後一幀留在回滾緩衝裡；--headless 在沒有顯示的情況下運行同樣的模型/遊戲。

兩種部署選擇

預設的 ANE 包批大小為一、長度為 96。每個遊戲步依次回答三個問題。它的 單問題約 5 ms 基準不是完整的遊戲幀時間。普通的 Snake GPU 包使用 B3/L64/K4，並批處理這三個問題：

hf download aac6fef/laya-multilingual-coreml-snake --local-dir models/snake-gpu
laya-coreml-snake --model ./models/snake-gpu --fps 12

引擎標籤描述所選用的 Core ML 計算單元。專用 ANE 圖有單獨的執行計劃和硬體 trace 證據，見 ANE 報告；CPU+ANE 仍然允許主機端工作。

模型控制什麼

程式碼計算合法移動、沿哈密頓環的安全推進，以及食物是否能通過空格到達。Laya 接收這些特徵，返回方向機率和布林機率。顯示的風險是 1 - P(safe route)；它是模型估計，不是下一步死亡經過校準的機率。

預設的安全護盾把執行的移動限制為迴圈安全的推進。UI 保持原始模型機率可見，顯示建議方向和執行方向，並在二者不同時遞增一個可見的干預計數器。--unassisted 在沒有該護盾的情況下執行原始模型的 top-1。帶護盾的零死亡不能證明無輔助的 Snake 智慧或無限期存活。

錄製一次真實執行並匯出可分享的媒體

laya-coreml-snake --model ./models/snake --fps 12 --seed 7 \
  --duration 75 --record snake.jsonl

# Requires ffmpeg: brew install ffmpeg
laya-coreml-snake export snake.jsonl --start 45 --seconds 20 \
  --output snake.mp4 --gif snake.gif --gif-seconds 15
laya-coreml-snake export snake.jsonl --start 55 --output snake.png

錄製包含模型來源、每個動作宣佈之前的棋盤、真實機率、推理延遲、經過的時間戳和一份最終摘要。匯出器複用即時終端的合成，並保留 1× 牆鍾計時。螢幕上的 RECORDED RUN · 1× 標識這是一次回放。sidecar 記錄源和渲染器的雜湊。影片 FPS 對錄製進行取樣；它不改變模型決策的數量，也不加速播放。

輸出檔案必須是新路徑。--max-speed 關閉限速，並在移動前等待每次新鮮預測。它不會跳過模型呼叫：

laya-coreml-snake --model ./models/snake --max-speed \
  --duration 20 --record snake-fast.jsonl

測量穩定的決策速率

laya-coreml-snake benchmark --model ./models/snake \
  --rates 20,30,40,50,60 --sweep-steps 120 --soak-steps 600 \
  --seeds 101,102,103 --raw-steps 200 --output snake-benchmark.json

基準先測量無護盾行為和不受限執行，然後掃描目標速率，再在更長的回合上用多個種子測試通過的速率。通過要求零死亡、輸出有限、保持迴圈順序和食物推進，並且最多 1% 的 tick 超出活動計算預算。

計時包含模型預測、規劃器工作、truecolor Rich 合成、ANSI 序列化和遊戲更新。限速測試包含真實的 sleep。終端模擬器繪製不計入這個記憶體中的渲染測試。結果是在本機和這些種子下通過的最高被測速率，不是普適的上限。釋出執行見 SNAKE_BENCHMARKS.md。