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。