米克斯
- 作者仓库星标 33
- 许可证 MIT
- 作者仓库 mlx-LLM-cheatsheet
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @cavit99 · MIT
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export MLX_SKILL="$CODEX_HOME/skills/mlx"
# MLX
Use this skill for MLX or MLX-LM engineering work where correctness depends on
current upstream behavior, not model memory.
## When to Use
- Auditing or patching MLX or MLX-LM repos
- Fact-checking "latest" MLX or MLX-LM behavior
- Porting PyTorch or JAX code to MLX
- Debugging MLX indexing, lazy evaluation, compilation, or stream behavior
- Deciding when to use stock ops, `mx.fast.*`, `mx.fast.metal_kernel(...)`, or a deeper extension path
- Profiling or debugging MLX GPU execution with Metal capture hooks
- Profiling MLX memory usage or allocator/cache behavior on Apple silicon
- Reviewing MLX-LM model load, cache, prompt-cache, quantization, or generation code
- Validating local MLX model paths on Apple silicon
## Core Rules
- If the user asks for current or latest MLX facts, verify releases and source first.
- Prefer upstream docs/source plus runtime checks over memory.
- Treat undocumented runtime behavior as unstable.
- Distinguish documented contracts from observed caveats.
- Keep MLX-LM inference checks local and minimal: `lazy=True`, short prompts, small
`max_tokens`.
## Quick Start
Set the skill path once:
```bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export MLX_SKILL="$CODEX_HOME/skills/mlx"
```
Check latest upstream releases:
```bash
"$MLX_SKILL/scripts/mlx_release_info.sh"
```
Run the bundled runtime probe:
```bash
"$MLX_SKILL/scripts/mlx_probe.sh"
```
The launcher checks both `python3` and `python` and picks one that can import
`mlx`.
Run the probe with a local MLX model:
```bash
MLX_LM_LOCAL_MODEL=/path/to/model "$MLX_SKILL/scripts/mlx_probe.sh"
```
## Workflow
### 1. Classify the task
- **Current facts**: verify latest `mlx` / `mlx-lm` releases, then inspect source
- **Repo validation**: run the repo's own validator if it exists; otherwise use the bundled probe
- **Porting or debugging**: check the current facts reference, then validate the specific behavior locally
- **Local model inference**: use a local MLX model path and keep decode checks short
### 2. For current upstream facts
Use authenticated GitHub workflows when possible:
```bash
"$MLX_SKILL/scripts/mlx_release_info.sh"
gh repo clone ml-explore/mlx /tmp/mlx-upstream -- --depth 1
gh repo clone ml-explore/mlx-lm /tmp/mlx-lm-upstream -- --depth 1
```
Inspect only the files relevant to the question. Typical targets:
- MLX: `docs/src/usage/indexing.rst`, `lazy_evaluation.rst`, `compile.rst`,
`numpy.rst`, `python/data_types.rst`, `python/memory_management.rst`,
`python/mlx/nn/layers/convolution.py`,
`docs/src/dev/custom_metal_kernels.rst`, `docs/src/dev/metal_debugger.rst`,
`docs/src/dev/extensions.rst`
- MLX-LM: `mlx_lm/generate.py`, `mlx_lm/utils.py`, `mlx_lm/models/base.py`,
`mlx_lm/models/cache.py`
### 3. For runtime validation
If the repo already has an MLX validator, prefer that first.
Otherwise run:
```bash
"$MLX_SKILL/scripts/mlx_probe.sh"
```
The bundled probe checks high-signal MLX and MLX-LM behavior:
- indexing and mask limitations
- slice-copy vs aliasing
- compile and retracing rules
- training flow and optimizer semantics
- channels-last inputs
- stream APIs
- custom Metal kernel and capture-hook surface
- MLX-LM API surface, attention mask, caches, prompt-cache roundtrip
- AutoAWQ/GPTQ transform helpers
### 4. For local model checks
Use a local MLX model path when load/generate behavior matters:
```bash
MLX_LM_LOCAL_MODEL=/path/to/model "$MLX_SKILL/scripts/mlx_probe.sh"
```
This adds:
- real `load(..., lazy=True)`
- one-step `generate(...)`
- `stream_generate(...)` response validation
- prompt-cache save/load on the actual model cache
- generation-stream / `async_eval` / `clear_cache` checks
### 5. For porting or reviews
Check [current-facts.md](./references/current-facts.md) first.
Then use [porting-checklist.md](./references/porting-checklist.md) for the
common MLX-specific failure modes:
- boolean mask selection unsupported
- slices are copies, not views
- no tensor `backward()` pattern
- explicit `mx.eval(...)` required in training and timing
- channels-last activations
- stream-aware benchmarking
- MLX-LM cache and generation API differences
## Kernel Escalation Path
- Start with stock MLX ops.
- If there is already a tuned kernel in `mx.fast.*`, prefer that first.
- Use `mx.fast.metal_kernel(...)` for Apple-only fused hot paths when the stock
op graph is the bottleneck.
- Be explicit about contiguity: `ensure_row_contiguous=True` can hide copies.
- Use `@mx.custom_function` when the custom kernel also needs custom gradient
logic.
- Move to C++ `Primitive` extensions only when Python-level Metal kernels are
not enough.
- For serious GPU profiling, capture a `.gputrace` with
`mx.metal.start_capture(...)` / `mx.metal.stop_capture()` and inspect it in
Xcode.
## High-Signal MLX Differences
- Training is `nn.value_and_grad(...)` plus `optimizer.update(...)` plus
`mx.eval(model.parameters(), optimizer.state)`.
- Module parameters are created lazily; explicit `mx.eval(model.parameters())`
matters before timing and export.
- Conv inputs are channels-last: `NLC`, `NHWC`, `NDHWC`.
- `mx.compile(...)` retraces on dtype, rank, and input-arity changes.
- `shapeless=True` avoids shape-only retracing but can break shape-dependent code.
- Streams are first-class, and timing without `mx.eval(...)` or
`mx.synchronize(...)` is often wrong.
- Memory profiling should use the top-level `mx.get_*_memory()` helpers and
`mx.device_info()`, not deprecated `mx.metal.*` aliases.
- MLX has a real Python-level fused-kernel escape hatch in
`mx.fast.metal_kernel(...)`.
## High-Signal MLX-LM Differences
- `generate(...)` and `stream_generate(...)` accept strings or token IDs.
- `batch_generate(...)` expects token ID lists, not raw strings.
- `stream_generate(...)` yields `GenerationResponse` objects.
- Prompt caches are not always pure KV caches; hybrid models can mix
`ArraysCache` and `KVCache`.
- Current `mlx-lm==0.31.0` caveat: `batch_generate(..., max_tokens=1)` can hit a
`ZeroDivisionError`.
## References
- Current validated facts and caveats: [current-facts.md](./references/current-facts.md)
- Porting and review checklist: [porting-checklist.md](./references/porting-checklist.md)
## Helpers
- Release helper: [scripts/mlx_release_info.sh](./scripts/mlx_release_info.sh)
- Runtime probe launcher: [scripts/mlx_probe.sh](./scripts/mlx_probe.sh)
- Runtime probe implementation: [scripts/mlx_probe.py](./scripts/mlx_probe.py)
章节与文件索引
按说明文件中的顺序排列。
何时使用
核心规则
快速入门
1. 任务分类
2. 对于当前上游事实
文件/命令 -> mx.fast.* · mx.fast.metal_kernel(...) · lazy=True · max_tokens · python3 · python · mlx · mlx-lm
内容校验值 -> bf7804f900e7
当前原文的自动摘译,尚未人工审校。
何时使用
审核或修补 MLX 或 MLX-LM 存储库 事实检查“最新”MLX 或 MLX-LM 行为 将 PyTorch 或 JAX 代码移植到 MLX 调试 MLX 索引、惰性求值、编译或流行为 决定何时使用库存操作、
mx.fast.*、mx.fast.metal_kernel(...)或更深层的扩展路径核心规则
如果用户询问当前或最新的 MLX 事实,请首先验证版本和来源。优先选择上游文档/源代码以及运行时检查而不是内存。将未记录的运行时行为视为不稳定。区分书面合同和观察到的警告。保持 MLX-LM 推理检查本地化且最小化:
lazy=True、短提示、小快速入门
设置技能路径一次: 检查最新的上游版本: 运行捆绑的运行时探针: 启动器检查
python3和python并选择一个可以导入mlx。1. 任务分类
当前事实:验证最新的
mlx/mlx-lm版本,然后检查源存储库验证:运行存储库自己的验证器(如果存在);否则使用捆绑探针 移植或调试:检查当前事实参考,然后在本地验证特定行为 本地模型推理:使用本地 MLX 模型路径并保持解码检查简短2. 对于当前上游事实
尽可能使用经过身份验证的 GitHub 工作流程:仅检查与问题相关的文件。典型目标:MLX:
docs/src/usage/indexing.rst、lazy_evaluation.rst、compile.rst、numpy.rst、python/data_types.rst、python/memory_management.rst、python/mlx/nn/layers/convolution.py、