在 M1 Max 上运行 2.8T 参数的 Kimi K3：Deltafin 项目实现 0.0687 token/s 推理

在单台 Apple Silicon Mac 上运行 Kimi K3（2.8T 参数）的实验

Deltafin 是一个小型研究项目，它运行着一个远超所在机器规模的混合专家模型。目前，在我们 64 GB 的 M1 Max 上，精确路径中位数为 0.0687 token/秒（14.6 秒/token）。迄今为止，所有已发布的运行都来自那台第一代机器——而非更新的 Max 或 Ultra——并且，基于能力限制的路径加上自动内存预算管理，使得同一引擎能够延续到更新的 Apple Silicon Mac 上。

安装

三条命令，然后你就可以开始生成了。唯一需要真正做决定的是第三步。

# 1. environment (Python 3.12+, and Xcode CLT for clang) python3 -m venv venv ./venv/bin/pip install torch numpy safetensors tiktoken ml_dtypes blobfile \ "transformers==4.56.2" einops tokenizers

# 2. build the fused MXFP4 kernel clang -O3 -mcpu=native -shared -DNO_MAIN -o tools/libmxfp4gemv.dylib tools/fused_gemv.c

# 3. download the model (see the two modes below) ./venv/bin/python tools/setup_k3.py --full

两种模式

--full（推荐） --stream

所需磁盘空间 约 1.7 TB 约 215 GB

下载时间 5–10 小时，可断点续传 约 30 分钟

后续速度 在我们的 M1 Max 上，中位数为 14.6 秒/token 对于任何尚未缓存的内容，约 3 分钟以上/token

推理时的网络需求 无 持续连接

每个 token 需要读取 16 个专家 × 92 层 = 25.8 GB 的专家数据。从本地磁盘读取大约需要 4 秒；通过网络则需要几分钟。这一事实就是两列之间全部差异所在。

运行 `setup_k3.py` 时不加任何标志，当磁盘空间允许时它会选择 `--full` 模式，否则会回退到流式模式，并准确告知你需要释放多少空间。

从流式模式开始，后续升级

流式模式是尝试 Deltafin 的好方法，无需预先投入 1.7 TB 的磁盘空间。无论何时你想要更快的速度，一条命令即可完成升级——无需重新安装，无需重新配置，并且它会利用所有已缓存的内容：

./venv/bin/python tools/fetch_experts_all.py # resumable, run anytime ./venv/bin/python tools/fetch_experts_all.py --dry-run # just show the numbers ./venv/bin/python tools/fetch_experts_all.py --layers 1-40 # partial is fine too

对于流式安装，空闲时的预热器可以根据记录的路由器轨迹来识别缺失的专家。其默认是一个只读方案；网络获取是显式进行的，并且它可以原子地将旧的 `.npz` 条目转换为原始的快速格式：

./venv/bin/python tools/warm_expert_cache.py ./venv/bin/python tools/warm_expert_cache.py --convert-npz --fetch 128

每当 Deltafin 仍处于流式模式时，它会在启动时打印一条提醒——无论是对于 CLI 还是 API 服务器——显示当前本地已缓存的专家池比例以及完成全部缓存所需的代价。

可选：int8 脊柱网络

将非专家权重的每 token I/O 减半，在我们的检查中未发现明显的质量变化。只需几分钟：

./venv/bin/python tools/convert_spine_int8.py

使用方式

# ask a question; generates until the model finishes its answer ./venv/bin/python tools/kimi_run.py --chat --prompt "What are the three largest moons of Saturn?"

# raw completion (no chat template); runs until you press Ctrl-C, or cap it ./venv/bin/python tools/kimi_run.py --prompt "The capital of France is" --max-new 16

Token 会边生成边打印，因此你始终能看到文本实时呈现。按 Ctrl-C 可在任意位置干净地中断并输出已生成的结果；`--max-new N` 参数可限制生成长度。一个诚实的提醒：K3 在回答前会进行思考，大约每分钟生成 4.1 个 token，因此一次完整的聊天回答可能需要一段时间——观看其流式输出本身就是体验的一部分。

设置 `K3_TRACE=buffered` 可将路由选择记录到 `router_trace.jsonl` 文件中，供离线分析使用。性能测试运行时请关闭追踪功能。

兼容 OpenAI 的服务器

Deltafin 可提供标准的 OpenAI API 服务，因此聊天界面、openai SDK 以及编程智能体只需修改基础 URL 即可使用：

./venv/bin/python tools/serve_openai.py --port 8000

curl http://127.0.0.1:8000/v1/chat/completions -H 'Content-Type: application/json' \ -d '{"model": "deltafin-kimi-k3", "messages": [{"role": "user", "content": "Hello!"}]}'

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="none") r = client.chat.completions.create( model="deltafin-kimi-k3", messages=[{"role": "user", "content": "Hello!"}])

print(r.choices[0].message.content) # the answer print(r.choices[0].message.reasoning_content) # K3's thinking, when present

已实现 `/v1/chat/completions`、`/v1/completions` 和 `/v1/models` 接口，流式传输（`"stream": true`）功能也可正常工作。大多数读取 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY` 的工具，只需将地址指向该服务器即可运行。

在将任何自动化工具指向该服务器之前，请先阅读以下注意事项：

时间。回答会在准备好时返回——请将客户端的超时时间设置为小时级别，而非秒级。省略 `max_tokens` 参数可让模型完成整个回答（推荐）；原始补全（raw completions）默认不会自行终止，其默认值为 256。运维人员可通过 `K3_SERVER_MAX_TOKENS` 设置硬性上限。

流式安装在此处的速度要慢得多。一个聊天模板提示词至少需要 60 个 token，且预填充阶段会触及每层的多个专家，因此在缓存部分填充的情况下，一次聊天请求可能需要数小时来获取结果。使用完整安装时，则只是正常的（慢速）推理。当处于流式模式时，服务器会在启动时打印一条警告信息。

仅支持贪婪解码。`temperature` 和 `top_p` 参数虽被接收但会被忽略，且一次只处理一个请求（第二个并发请求将收到 429 状态码）。

智能体目前仅作为探索性功能，并非正式工作流程。编程助手在理论上可以工作，但其冗长的系统提示词会导致预填充成本高昂。

配置

所有功能无需配置即可运行：Deltafin 会在有 GPU 时自动选择 GPU，在 int8 骨干网络已构建时自动选择该网络，并在启动时告知其选择结果。以下变量可用于覆盖默认设置：

变量 默认值 含义

K3_DEV auto 可用时使用 GPU（mps），否则使用 CPU

K3_SPINE auto 已构建时使用 int8（推荐），否则使用 bf16

K3_INT8_LM_HEAD 1 在支持时使用打包的 MPS int8 输出头；精确的密集回退方案仍然可用

K3_SPEC 1 n-gram 推测（无损）

K3_TEMPLATES 1 模板层缓冲区复用

K3_PRELOAD / K3_PREFETCH 1 后台层加载 / 专家预取

K3_METAL_POSITION_BATCH 0 精确的主动启用 T>1 位置主序 Metal MoE；实测接受推测通过率提升 +2.0%，需按每台 Mac 重新调优

K3_MOE_TOP_K 16 明确的质量/速度调节旋钮；减少路由专家数可降低专家数据量并可能改变输出

K3_CPU_MOE_BATCH 自动 精确的持久化 CPU MXFP4 工作线程环；填充计数器在八线程下实测提升 +3.6%

K3_ASYNC_CACHE_WRITE 0 主动启用的缓存未命中写入重叠；K3_CACHE_WRITE_QUEUE（4）限制未完成缓冲区数量，K3_CACHE_WRITE_WORKERS（1）可按每台 Mac 重新调优

K3_APPROX 0 fp16 数值计算；在接近平局时不可复现

K3_RAM_GB / K3_PIN_LAYERS 自动 覆盖 RAM 预算

K3_PROFILE 0 每次推理的逐阶段计时

K3_TRACE 关闭 缓冲写入：每次推理一个路由器追踪块；立即同步写入每一层

DELTAFIN_ROOT 仓库根目录 缓存和权重存放的位置

K3_HF_HOST / K3_HF_PATH Hugging Face 将专家获取指向镜像

K3_SERVER_MAX_TOKENS 无限制 可选的服务器生成硬上限

K3_RESPONSE_MEMO_ENTRIES 32 精确的进程内重放缓存，用于相同的确定性 API 请求；设为 0 则禁用

系统要求

一台 Apple Silicon Mac。所有已发布的数据均来自同一台初代 M1 Max（64 GB）——这是迄今为止唯一经过基准测试的 Mac。更多 RAM 会被自动利用（128 GB 的机器可固定数倍于当前模型的层数），而更新的芯片能带来更高的内存带宽、更多的 GPU 资源和更快的存储。详见《为什么更新的 Mac 应该更快》。

Xcode 命令行工具，用于 clang（xcode-select --install）。

Python 3.12 或更新版本。

磁盘空间：完整安装约需 1.7 TB，流式模式约需 215 GB（详见安装说明）。

可访问 Hugging Face 的网络连接。

工作原理

K3 的权重总计约 1.56 TB，超过了这台机器的可用磁盘空间，更不用说 RAM 了。然而，本地推理之所以仍然可行，关键在于混合专家模型每个 token 只触及自身的一小部分。

常驻主干（约 114 GB：注意力层、共享专家、潜在投影、嵌入向量）一次性下载完成，每个 token 从本地 NVMe 逐层读取，量化为 int8 后在 GPU 上计算。

82,432 个路由专家（约 1.45 TB）。对于每个 token，K3 的路由器为每层选取 16 个专家，并且只读取这些专家。如果条件允许，建议在本地全部安装；否则，Deltafin 会按需从 Hugging Face 获取它们——每个专家一个 HTTP 范围请求——存入不断增长的磁盘缓存中。

前向传播运行的是 Moonshot 自身的建模代码，未经修改。一个纯 PyTorch 的小型垫片替代了其所需的仅支持 CUDA 的 fla 内核。

flowchart LR subgraph HF["Hugging Face CDN"] W[("96 safetensors shards<br/>1.56 TB · MXFP4")] end subgraph MAC["MacBook (M1 Max, 64 GB)"] subgraph DISK["NVMe"] SP[("resident spine<br/>114 GB bf16 → 60 GB int8")] EC[("expert cache<br/>raw shard spans")] end subgraph TOK["per token"] R{"router<br/>top-16 of 896<br/>× 92 layers"} L["93 decoder layers<br/>2 shared GPU templates"] K["fused MXFP4 GEMV<br/>NEON"] end end W -- "one range request<br/>per missing expert" --> EC SP -- "double-buffered<br/>layer loader" --> L EC -- "mmap" --> K R -- "selected experts" --> K K --> L L -- "logits" --> R

预期表现

以下所有当前数据均在一台 M1 Max（10 核 CPU、32 核 GPU、64 GB 内存、内置 NVMe）上测得，模型完整安装在本地，采用 int8 驻留权重和输出头、Metal MoE、精确 fp32 数值计算、贪婪解码，并禁用了追踪功能。

当前列汇集了来自平衡的 ABBA/BAAB 测试序列的六次精确全模型运行结果。每次运行使用五个 token 的提示词 The capital of France is，验证了三个 token 的补全结果 Paris. The，并在报告稳定吞吐量之前丢弃了第一个解码步骤。数值为中位数；范围显示了即使在同一台空闲机器上，这个 I/O 密集型工作负载的波动幅度。

指标 首个可用版本 当前 M1 Max 基准测试 变化

预填充 / 首个 token（5 token 提示词） 2,429 秒 28.0 秒中位数（24.9–37.9 秒） 约 87 倍

稳定解码，专家本地化 约 20 分钟/token 0.0687 token/秒（14.6 秒/token）；运行范围 0.0503–0.0779 token/秒 约 82 倍

精确的三 token 生成，模型时间 — 56.5 秒中位数 —

同次运行的新进程墙钟时间 — 64.1 秒中位数 —

解码，专家流式传输 约 20 分钟/token 约 3 分钟/token 受网络限制

这就是“不起眼的 M1”的结果：一台老化的第一代 M1 Max，而非更新的 Max 或 Ultra。这是一个保守的参考点，并非跨 Mac 的基准测试。我们预计更新、带宽更高、内存更大的系统表现会更好，但在有人测量出这些数据之前，我们会单独标注那些数值。

近期精确路径的改进

以下最新的测量结果是在同一台 M1 Max 上进行的平衡 A/B 测试。每次全模型运行都检查了 token 预言机。

变化 测量结果 发布时的行为

打包的 MPS int8 输出头 稳定解码中位数提升 +17.3%，预填充提升 +23.1%，墙钟吞吐量提升 +26.8%；驻留输出头存储从 4.7 GB 降至 1.17 GB 在算子与 int8 权重均可用时启用，并带有异常保护的密集回退机制。

仅作参考的推测性快照。 0.001 毫秒而非 3.56 毫秒，且无需约 475 MB 的状态克隆。 默认启用；重放与部分接受测试可保留精确的未来序列。

面向已接受草稿的按位置主序 Metal MoE。 在真实 T=2 层上提升 +4.7%，全模型吞吐量汇总提升 +2.0%。 通过 `K3_METAL_POSITION_BATCH=1` 精确选择加入，待按每台 Mac 进行调优。

128 字节对齐的 CPU 工作线程计数器。 四线程时提升 +0.2%，八线程时提升 +3.6%。 在持久化 CPU 回退中自动生效。

中位数约为每分钟 4.1 个 token。一个典型的 M1 Max 性能画像主要由以下部分组成：

等待驻留主干读取（53 GB） 约 5 秒

读取每层选定的 16 个专家（25.8 GB） 约 4.3 秒

应用主干（传输 + 反量化） 约 3 秒

注意力机制与归一化（93 层） 约 2 秒

MoE 专家矩阵乘法 约 1 秒

解码阶段现在受限于驻留主干的磁盘带宽。这 53 GB 数据在每个 token 生成时都会被重新读取，而在此访问模式所能维持的约 7 GB/s 速率下，这大约占用了 14.6 秒中位数中的 7.5 秒——除非拥有更多 RAM（足以容纳主干而不挤占专家读取所需的页缓存），或者采用更小的主干，否则无法避免。

为何新款 Mac 应该更快

上述每一行都受限于 Apple Silicon 各代芯片间变化的硬件。M1 的结果并未完全阻断任何路径，但这里测量到了若干回退值；新款机器应根据自身的能力、运行时环境、内存和存储特征重新调优这些参数：

内存带宽。M1 Max 为 400 GB/s。M3/M4 Max 显著更高，而 Ultra 型号则大致翻倍——这直接影响主干加载和专家矩阵乘法。

GPU。更多核心能以更快速度执行相同的 Metal 内核；反量化着色器和注意力路径均随核心数扩展。

SSD。专家读取是占比最大的单一环节，其速度取决于内置硬盘的性能。后续 Mac 机型配备了更快的 NVMe。

内存。这是最重要的因素。53GB 的主干模型无法与其它所有内容一起放入一台 64GB 的机器中，因此每生成一个 token 都需要从磁盘重新读取——这大约占总耗时的一半。在 128GB 的机器上，它可以直接留在页面缓存中，这部分开销基本消失。Deltafin 也会自动将更多模型固定在那里，无需任何标志位。

运行时选择基于 Metal 特性族和算子能力检查，而非芯片名称字符串。这使得更新的系列（包括 M5）能够执行 M1 无法运行的路径，同时每个可选的本地路径都保留了精确的回退方案。

我们仅在这台 M1 Max 上进行了基准测试。如果你在 M3、M4 或 M5、Ultra 芯片，或者 128GB 及以上内存的机器上尝试，我们非常希望看到你的数据——请提交一个 issue，附上 `K3_PROFILE=1` 的输出和你的芯片型号。

当 n-gram 推测解码接受一个草稿时，一次前向传播会输出两个 token，因此重复文本的运行速度会成比例地加快。推测解码是无损的：被接受的草稿会精确复现参考序列，而被拒绝的草稿则会逐比特恢复模型状态。

两行解码结果之间的差距，正是完整安装（见上文）的全部意义所在：当专家模型在本地时，每个提示词都以第一行的速度运行，而不仅仅是那些专家恰好被缓存的提示词。

输出是贪婪且可复现的：相同的提示词每次运行都会产生相同的 token。

法国的首都是 → 巴黎。埃菲尔铁塔位于巴黎。卢浮宫博物馆也在巴黎。卢浮宫有……

需要明确其局限性：这是一个研究原型，而非实用的聊天配置。14.6 秒的中位数 token 生成速度距离交互式体验还很遥远，且长提示词成本高昂，因为预填充阶段会触及许多专家模型。我们认为它主要作为存在性证明和流式推理技术的测试平台而有趣。

技术方法

以下每种技术在保留之前，都已在真实权重上进行了测量。这些技术本身大多并非新颖；其中大部分是将下文致谢项目中提出的思路适配到 K3 的特定形态上。

输入/输出与流式处理

合并专家数据获取。每个专家的六个张量在分片文件中恰好是连续的（我们检查了全部 82,432 个分片），因此整个专家只需通过少量保持连接的连接池发起一次 17.55 MB 的范围请求。实测速度比逐个获取张量快约 6.4 倍。

原始字节磁盘缓存。缓存文件直接存储分片的原始字节——无容器格式，无解析过程。

并行专家读取。一个层中的 16 个选定专家由线程池使用带 `F_NOCACHE` 标志的 `pread` 系统调用同时读取，而非在内核计算时逐页按需缺页中断。实测冷启动数据：缺页中断方式为 0.87 GB/s，而读取方式为 6.85 GB/s。这使读取路径上每个 token 的处理时间从 40 秒降至 4.3 秒，并且 `F_NOCACHE` 能防止每 token 25 GB 的专家数据流量驱逐主干网络所需的页缓存。

双层缓冲加载。当前层计算时，工作线程同时读取下一层的主干数据。

前序 token 预取。在去重后的保留测试集上，连续 token 约有 31% 的专家选择会重复，因此每个 token 的专家集合会在后台为下一个 token 预先获取。

计算

融合 MXFP4 反量化与 GEMV 运算（`tools/fused_gemv.c`）——一个 NEON 内核，通过 16 条目查表一次性完成反量化与乘法，其中 e8m0 缩放因子以整数运算形式应用于 fp32 指数。该实现与参考实现逐位匹配，取代了原先慢得多的“先反量化再矩阵乘”路径。Metal 版本已作为验证原型存在。

模板层缓冲区复用。全部 69 个 KDA 层共享一组张量形状，全部 24 个 MLA 层共享另一组，因此两个持久驻留 GPU 的“模板”层可通过 `copy_()` 操作接收各层的权重。这避免了性能分析显示占每 token 处理时间很大比例的内存分配器开销。

int8 驻留主干网络。将每 token 的驻留 I/O 量减半。在我们的检查中，前 5 个候选下一 token 的顺序保持不变，最高 logit 值仅变动 0.07%。

自定义 Metal 反量化内核。加载主干层的大部分时间都花在行广播乘法上，MPS 对此操作的运行速度为 43 GB/s，而相同字节的纯拷贝速度可达 334 GB/s。一个融合了 int8→fp32 转换、行缩放和拷贝操作的简短 compile_shader 内核，速度达到了 297 GB/s；通过使用持久化暂存缓冲区并将传输操作从调度之间提升出来，每层加载时间从 118 毫秒降至 21 毫秒。逐位精确：每个张量上的 max|diff| = 0。

打包的 int8 输出头。内置的 MPS 仅权重量化矩阵乘法直接使用现有的行 int8 检查点，避免了 4.7 GB 的 fp32 头及其反量化操作。能力检查和一个捕获到的密集回退机制，确保了在多个 PyTorch 版本和 Apple GPU 系列上的兼容性。

纯 PyTorch KDA 适配层（tools/fla/）—— Kimi Delta Attention 的循环、短卷积和门控归一化，从 fla-core 的语义移植而来。分块执行和逐步执行的结果差异约为 1e-9。在解码阶段，循环在 CPU 上运行，其小状态比在 GPU 上执行一系列调度更适合放在 CPU 上。

解码

N-gram 推测。草稿通过对已生成文本进行后缀匹配而免费获得，并在一个共享固定成本的双位置批次中进行验证。这在此处是有价值的，正是因为常驻 I/O 和计算（而非专家提取）主导了热 token 的处理。在我们的测试中，接受的草稿精确复现了参考序列。回滚操作保留旧的不可变状态对象，而不是克隆约 475 MB 的数据，然后在常数时间内恢复它们；重放测试则保证了未来序列的精确一致性。

sequenceDiagram participant D as n-gram draft participant M as model (one T=2 pass) participant S as state snapshot D->>M: [last_token, draft] M->>M: 93 layers, shared cost alt draft verified M-->>D: 2 tokens accepted else draft wrong S-->>M: state restored (bit-exact) M-->>D: 1 token, nothing lost end

随 RAM 扩展

在启动时，Deltafin 为操作系统预留内存（max(10 GB, 18%)），并将尽可能多的常驻层固定在剩余内存允许的范围内。一台 128 GB 的机器无需任何配置就能固定比 64 GB 机器多几倍的层，并且专家缓存还能额外受益于任何空闲的页面缓存。

未来方向

大致按优先级排序：Metal 专家内核（已原型化）、一个合适的质量评估框架（针对官方 API 的平均负对数似然），以便可以测量而非争论有损的速度/质量权衡、更智能的专家预取，以及最终一个遵循 ds4 精神的原生引擎，届时大部分剩余开销应该会消失。

致谢

Deltafin 大量借鉴了他人公开发布的研究成果。按影响力大致排序如下：

colibri（JustVugg，Apache-2.0 许可）—— 展示了 744B 参数的 MoE 模型可在 25 GB 内存中运行，我们从中学习了路由器预取、专家固定技术、macOS 上的 F_NOCACHE 和 F_RDADVISE 策略，以及逐分片转换模式。其 M5 Max 性能报告 —— CPU 自旋等待会抢占共享功耗预算导致 GPU 饥饿 —— 改变了我们的任务调度方式。

ds4 / DwarfStar（Salvatore Sanfilippo，MIT 许可）—— 我们研究过的最清晰的专家流式传输设计：零拷贝专家缓冲区、掩码分发、基于选择的缓存淘汰、会话持久化，以及我们直接采用的质量评估方法（与官方 API 输出的平均负对数似然对比）。其核心理念 —— 正确性优先于速度，用计算掩盖 I/O —— 非常合理，我们努力遵循了这一原则。

月之暗面（Moonshot AI）—— 感谢他们公开了 K3 的权重并附带了可读的建模代码（Deltafin 直接运行该代码），以及 Kimi Delta Attention 设计，其小型循环状态使得在笔记本电脑上实现长上下文成为可能。

flash-linear-attention（fla-org，MIT 许可）—— 我们的 KDA 适配层移植了其内核和参考实现的语义。

llama.cpp / ggml —— 内核内反量化与 MXFP4 处理的先前技术，也是本地推理社区大部分知识的基础。

PyTorch、Transformers、ml_dtypes（我们用于 e2m1 的位精确性参考）以及 tiktoken。

许可协议

Deltafin 自身的代码采用 MIT 许可。本仓库中有两项内容不属于我们：

tools/fla/ 是 flash-linear-attention（MIT 许可，© 2023–2026 Songlin Yang, Yu Zhang, Zhiyuan Li）语义的纯 PyTorch 移植。该署名已在文件头部和 LICENSE 文件中重复声明。

Kimi K3 的权重和建模代码归月之暗面所有，并依据月之暗面自身的许可协议分发。这些文件在设置时下载，从未在此处进行供应商化 —— 使用前请阅读该许可协议。

Deltafin 是一个独立项目，与月之暗面无任何关联。