FitLLM

FitLLM Engine

FitLLM 是一款开源、零依赖的引擎，通过感知架构的内存计算，检查本地 LLM 是否能在 GPU 或 Apple Silicon Mac 上运行。

在线体验：https://fitllm.run · 双语 · 免费 · 无广告 · 无需登录

开源引擎： fitllm-engine（MIT · npm fitllm-engine · npx fitllm）

零依赖。一个易读的文件：engine.js。通过一致性向量测试。MIT。

安装

# self-contained binary — no Node required
curl -fsSL https://fitllm.run/install.sh | sh

# Homebrew (tap) — the trust line is required for any third-party tap
brew tap click6067-ship-it/fitllm
brew trust click6067-ship-it/fitllm
brew install fitllm

# Windows (Scoop)
scoop install https://raw.githubusercontent.com/click6067-ship-it/fitllm-engine/master/packaging/fitllm.json

# already have Node? nothing to install
npx fitllm "Gemma 4 12b" --gpu "RTX 4090"

每个 release 都附有适用于 macOS（arm64/x64）、Linux（x64/arm64，glibc 和 musl）以及 Windows x64 的二进制文件，每个文件旁边都有一个 .sha256 文件；install.sh 会验证校验和，如果校验不匹配，则不会安装任何内容。

有两点我们会直接说明，而不是藏着不提：每个二进制文件都嵌入了 JavaScript 运行时，因此大小为 60–94 MB——远大于功能相当的 Rust 或 Go 工具，这是不把引擎用第二种语言重新实现所付出的代价。其次，这是一个 Homebrew tap（click6067-ship-it/homebrew-fitllm），而不是 homebrew-core：对于自行提交的项目，core 的门槛是 225 颗星 / 90 个 fork / 90 个 watcher，而本项目目前尚未达到。

快速开始

npx fitllm "Gemma 4 12b" --gpu "RTX 4090"     # one line, exit 0 fits / 1 won't — run before you download
npx fitllm --top --gpu 4090                    # what can this hardware run?
npx fitllm --top --detect --json               # detect every supported local GPU; agent-ready JSON
npx fitllm Qwen/Qwen3-32B --detect --json      # public Hugging Face ID or URL; unsupported configs fail closed
npx fitllm "Gemma 4 12b" --detect --json --why # include architecture, evidence, assumptions, and exact memory inputs
npx fitllm scan                                # what you already downloaded — does it fit this machine?
npm install fitllm-engine                      # use the same engine as a library (see Usage)

fitllm scan — 从你已有的内容开始

无需输入模型名称，直接读取磁盘上已有的模型：

$ fitllm scan
Hardware: RTX 4090 (24GB) · quant Q4_K_M · ctx 8,192

ollama (3)
  ✓ FITS  qwen3:0.6b  →  Qwen3-0.6B
          1.2 GB used, 22.8 GB free  (on disk: 0.5 GB · Q4_K_M)
  ?       some-finetune:latest  —  not in the catalog, no verdict  (on disk: 6.7 GB · Q5_K_M)

它通过 loopback API 读取 Ollama，并通过 lms ls --json 读取 LM Studio。两者都只读：不会拉取、加载、写入设置，也不会向任何地方发送数据。若 OLLAMA_HOST 不是 loopback 地址，则会拒绝查询。

对于目录中没有的模型，不会提供估算值——只显示运行时本身报告的大小和量化类型。根据相似名称猜测会把另一个模型的数据提供给你，这比不提供数据更糟。

验证状态在此明确说明：Ollama 路径会在 CI 中通过真实的 Ollama 安装进行端到端测试（verify-install-paths.yml）。LM Studio 路径仅通过 fixture 覆盖——编写本文时使用的机器上没有 LM Studio，因此尚未使用真实 CLI 运行测试。

远程 MCP 服务

将任何 Streamable HTTP MCP 客户端连接到 https://fitllm.run/api/mcp：

{
  "mcpServers": {
    "fitllm": {
      "url": "https://fitllm.run/api/mcp"
    }
  }
}

工具

• check_llm_fit — 检查一个模型是否适用于某个 GPU、多 GPU 设备或 Mac，并返回判定结果、内存明细，以及模型不适用时的解决方法。
• what_fits_on_hardware — 对适用于指定 GPU、多 GPU 设备或 Mac 的受支持本地模型进行排序。
• list_supported — 列出适用于适配检查器的内置模型和硬件名称。

此服务为只读、无状态，且无需身份验证。

npx fitllm "GLM-4.7-Flash" --gpu 4090     # ✓ FITS — 21.9/24 GB, free 2.1 GB
npx fitllm "gpt-oss-120b" --mac 64        # ✗ WON'T FIT → what to change to make it fit
npx fitllm "Qwen 3.6 35B" --gpu "5090 + 3090"   # multi-GPU rig — VRAM pools (56GB), even mixed cards
npx fitllm --top --detect --json          # detect hardware + what fits, for people or agents
npx fitllm "Gemma 4 12b" --detect         # one verdict on this machine

--detect 会读取所有 nvidia-smi 适配器，在 arm64 macOS 上使用 Apple Silicon 统一内存，并可通过 Windows/WSL PowerShell 解析精确匹配的目录 GPU 名称。它不会使用 Win32_VideoController.AdapterRAM、序列号、PNP ID 或完整环境转储。仅有 Intel 显卡、适配器存在歧义或不受支持时，程序会以退出码 2 停止，而不会借用相近 GPU 的内存数据。

为什么要用 CLI？“能不能运行？”这个问题诞生于终端——就在执行 ollama pull 之前的一行命令。无需安装，无需切换标签页；使用 --detect 即可读取你实际的硬件，而不必让你自己知道 VRAM 容量。退出码 0/1 可用作下载前检查：

# in your model-pull script — stop BEFORE the 40 GB download:
npx fitllm "gpt-oss-120b" --detect || { echo "won't fit — aborting pull"; exit 1; }

在下载路径中加入防护

CLI 退出约定可直接与模型运行时配合。只有判定为 FITS 或 TIGHT 时才会执行下载或启动；输入无效时以退出码 2 停止。

npx fitllm "Gemma 4 12b" --detect && ollama pull gemma4:12b
npx fitllm "Llama-3.1-8B-Instruct" --detect && llama-cli -m ./Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf

对于 CI，请使用仓库的复合 Action。它无需密钥，并会将完整的 --json --why 结果作为 steps.preflight.outputs.result 返回：

permissions:
  contents: read
steps:
  - name: Check model memory before download
    id: preflight
    uses: click6067-ship-it/[email protected]
    with:
      model: Gemma 4 12b
      gpu: RTX 4090
      ctx: '8192'

gpu 和 mac 中只能设置一个。该 Action 保留 CLI 约定：退出码 0 表示符合或勉强符合，1 表示无法容纳，2 表示请求无效。输入通过环境变量跨越 GitHub 表达式边界，并以 Bash 参数数组的形式传递给 Node。

Agent 可以收集类型化测量数据，且无需上传任何内容：

npx fitllm measure "Qwen 3.6 27B" --detect --measured 15.3 --kind system_total_peak --unit GiB --runtime "llama.cpp b6400"

该命令会验证条件，并输出一个候选 JSON 对象以及预填好的 GitHub issue URL。是否提交仍由人工决定。

如果你运行 Ollama，就无需自行测量——它已经会报告已加载模型的驻留大小：

ollama run qwen3:0.6b        # in one shell
npx fitllm measure --from-ollama   # in another

此操作通过 loopback 读取 GET /api/ps 和 GET /api/version。它是只读的：不会加载、卸载、拉取或更改任何内容，也不会提交任何内容——你会得到候选数据和 issue 链接，由你自行决定。

它会验证什么，以及不会验证什么。 该数值是 idle_resident：模型已加载且处于空闲状态时，驻留在 VRAM 中的权重和 KV。它不是生成期间的峰值内存，因此它只检查预测的一部分，而非全部，候选数据中也会明确说明这一点。

拒绝处理的情况。 如果 size_vram 与 size 不同，或数值为零，则不会生成候选数据。Ollama 的文档没有说明这些字段不一致时的含义，而部分驻留是此引擎有意不建模的情况——无法解读的数值比没有数值更糟。目录之外的模型也会跳过：没有预测值，就无从比较。对于公开的 Hugging Face ID（org/model），系统会使用有界配置／索引读取器获取数据，并且仅在 parseHfConfig() 支持该架构时接受。

这是 FitLLM 的开放计算核心。计算过程是开放的，你可以审计。

询问大模型“Qwen 3.6 能装进我的 GPU 吗？”，它会根据训练截止日期前的知识进行模式匹配——通常会回答 不能。基于目录的计算器往往落后于新版本。CLI、API 和 MCP 使用固定到官方配置的精选目录。网页计算器还可以实时检查粘贴的 Hugging Face ID 中官方的 config.json，因此受支持的架构从发布首日起即可使用——包括简单公式容易算错的混合式／滑动窗口／MoE 结构。

支持 Apple Silicon 统一内存（M1–M6、Pro/Max/Ultra——最高可达 512GB Mac Studio）、NVIDIA GPU（RTX 20/30/40/50、工作站 RTX 6000 Ada / RTX PRO Blackwell 2000–6000、数据中心 A100/H100/H200/B200）、NVIDIA GB10 统一内存系统（DGX Spark 128GB，以及同规格的 ASUS / Dell / HP / Lenovo / MSI / Acer / GIGABYTE 主机——合作伙伴名称只有与容量组成完整名称时才会匹配，例如 ASUS Ascent GX10 128GB；通过 --count 支持连接的 2× / 4× 集群）、AMD Radeon（RX 7000/9000、PRO W7900）和多 GPU 预设（2×3090、2×4090、4×3090）——GGUF 的 Q-tier 权重量化与 KV-cache 量化分别处理。硬件条目会在 engine.js 中为每个值标注来源 URL；新增条目需要 ≥2 个独立来源（CONTRIBUTING）。

---

为什么大多数大模型内存计算器都不准确

几乎所有“我能运行这个大模型吗？”计算器都会用教科书公式估算 KV 缓存：

KV ≈ 2 × num_layers × num_kv_heads × head_dim × context_length × bytes

这假设 每一层都保留完整上下文的 KV 缓存，且所有层的注意力头形状相同。 对 Llama-1/2 来说确实如此——但对大多数 2025–2026 年的模型来说并非如此：

模型	简单公式忽略了什么	简单公式估算的 KV	FitLLM 估算的 KV	误差倍数
Gemma 4 31B @131K，8-bit	60 层中有 50 层采用滑动窗口（仅保留最后 1024 个 token）；10 个全局层采用不同的注意力头形状（4 个 KV 头 × 512，而非 16 × 256）	~60 GB	~5.4 GB	11×
Qwen 3.6 27B @131K，8-bit	64 层中有 48 层采用线性注意力（Gated DeltaNet）——不会产生不断增长的 KV 缓存	~16 GB	~4 GB	4×
Qwen 3.8 27B @256K，F16 KV	结构相同，属于最新一代：KV 仅存在于 64 层中的 16 层	64.0 GiB	16.0 GiB	4×
GLM-4.7-Flash @128K，bf16	MLA：K/V 被压缩为一个共享潜变量（512+64 维，只缓存一次——而不是按头分别缓存 K 和 V）	~117 GB	~6.6 GB	17.8×
DeepSeek-V4.1-Flash-1017 @1M，bf16	压缩稀疏注意力：40 层中只有 4 层保留缓存（其中 3 层每 2 个 token 保留 1 个条目），其余 36 层保留 128-token 窗口并重复使用	80.0 GiB	3.6 GiB	22×
普通稠密模型（Llama、Mistral……）	无——标准 Transformer	相同	相同	1× ✅

11× 的误差会颠覆判断：简单计算器会说，在长上下文下，Gemma 4 31B 无法装入 64 GB 内存，实际上它却能轻松装入。

它们忽略的六件事

1. 滑动窗口注意力（Gemma 2/3/4、gpt-oss）：大多数层只保留最近的 N 个 token，因此它们的 KV 不会继续增长。只有全局层会随着完整上下文扩展。
2. 混合／线性注意力（Qwen 3.6 / 3.8、许多 2026 年的模型）：线性注意力层使用固定大小的循环状态，而不是不断增长的 KV 缓存。该状态也会单独建模为一个组件（linearState）——它在每个序列中都是常量，因此不会让上下文曲线膨胀。
3. MLA — 多头潜在注意力（GLM-5.2、GLM-5.3、GLM-4.7-Flash、DeepSeek-V2/V3 系列）：缓存是一个由所有头共享的单一低秩潜变量（kv_lora_rank + RoPE 维度）——按每个头套用“2 × heads × head_dim”公式会导致结果高出一个数量级。已根据 DeepSeek-V2 论文（arXiv:2405.04434）和 DeepSeek-V3 官方推理代码进行验证。
4. 异构头维度 + MoE：全局层可以使用不同的 head_dim（Gemma 4：512 与 256）。MoE 会将所有专家保留在内存中，但每个 token 只激活其中少数专家。
5. PLE — 逐层嵌入（Gemma 4 e2b/e4b）：在固定的 llama.cpp/GGUF 路径中，per_layer_token_embd 输入层张量会被分配到 CPU／主机缓冲区，而非加速器内存，因此对于已验证的 Gemma 4 e2b/e4b 条目，只有非 PLE 权重会计入 VRAM。将全部 5.1B 个参数都计入 GPU，会使 e2b 的驻留权重预测值高出约 1.9 倍，并改变小显存卡的判定。此推算仅在该放置方式成立时有效：GPU 判定不会为该张量所需的主机内存预留预算；如果运行时将 PLE 张量加载到加速器上（例如 vLLM），该估算便不成立；未经验证的系列则会将全部权重视为驻留。对于 Apple Silicon 统一内存，仍会计入全部权重。确切的前提及其固定版本的来源列于结构性前提中；欢迎在 issue #7 中提供 Gemma 4 GGUF 的直接测量结果。
6. 压缩稀疏注意力（DeepSeek-V4-Flash / V4-Pro、V4.1-Flash）：每层使用一个共享的 512 维 KV 头，所有位置都采用 128-token 滑动窗口；此外还会使用压缩缓存（每 compress_ratio 个 token 一个条目），而索引器键仅用于压缩自身 KV 的层——V4.1 会在六层或更多层之间共享一个缓存（CSA2）。引擎会统计 DeepSeek 参考推理代码分配的缓存缓冲区，以及有界的索引器预填充工作区；对于 V4.1，应用 DeepSeek 技术报告所述的 FP4 格式后，每 token 缓存的 1,600 个元素为 890 字节。与官方布局不符的配置会直接拒绝处理。

该引擎会对每种层类型分别建模，并根据 HuggingFace 官方 config.json 文件进行验证。

计算内容

Total = Parameters (quantization-adjusted)
      + KV cache (per layer kind: sliding / global / linear / dense)
      + Runtime overhead (quant metadata + KV block padding + activations + fixed)
      + OS reserve (macOS base on Apple Silicon · DGX OS share on GB10 · driver/display reserve on discrete GPUs)

GGUF 权重大小绝不会低于已发布文件。 GGUF 等级（Q4_K_M … F16）是一种按张量制定的配方，而非单一位宽：llama-quantize 会让部分张量使用更高类型（绑定的嵌入层使用输出类型；行数不是 256 的倍数时，则回退到 Q5_0/Q8_0），发布者还会添加自己的覆盖项——ggml-org 会让 Qwen3.5/3.6 系列的注意力和线性注意力张量即使在 Q4_K_M 下也保持为 Q8_0，bartowski 会提高注意力张量的类型并附带 MTP 层，poolside 则会让 Laguna S Q4_K_M 的八个专家层保持为 BF16。因此，同名等级在不同发布者之间的大小最多相差 15%（Qwen3.6-27B Q4_K_M：15.40 / 16.74 / 17.77 GiB）。如果 unsloth、bartowski、ggml-org、lmstudio-community、mradermacher 或模型所属组织发布的同名文件中，最大文件比该等级的平均值大 1% 以上，则权重按该文件的大小计算（ggufFileBytes，每个数值旁的 repository@revision 位于 engine.js）；其他参考文件与估算值的差异均在 1% 以内。2026 年 10 月的检查在目录中的 22 个模型（61 个模型-等级组合）中发现了这类情况——例如 Nex-N2.5-Pro Q5_K_M 从 263.5 → 284.6 GiB，Gemma 4 31B Q4_K_M 从 17.49 → 18.25 GiB，Qwen3-0.6B（大多数 GGUF 会单独存储绑定的 lm_head）增加 27–33%。此下限仅适用于完全匹配的等级，不适用于 Apple MLX 位宽，也不适用于 Gemma 4 PLE 模型中驻留于 GPU 的部分（per_layer_token_embd 张量会留在主机上；所有参考文件中的其余张量都低于估算值）。只有当 Hugging Face 检查点的张量列表与该行完全一致时，才会继承该行的下限。

统一内存（GB10 / DGX Spark）。 设备没有专用 VRAM：DGX OS、CPU 进程和 GPU 共用一个 128 GB LPDDR5x 内存池，因此与 Mac 路径一样，会从同一内存池中扣除 OS 和运行时占用，而不是使用独立显卡环境预设。预留空间由三个有来源或标注的部分组成：OS 无法识别的内存（128 − 121.69 GiB MemTotal，该值等于 DGX OS 7.6 中的 CUDA 总量）、DGX OS 空闲时约 5 GiB 的占用（MemTotal − MemAvailable），以及与 Apple 路径相同的 2 GiB 运行时余量（引擎估算值，并非 GB10 实测值）——总计 13.31 GiB，并为共享内存池保留 Mac 路径采用的 20% 余量。在一台设备上，GGUF 权重按文件大小计算：自 2.21.4 起，不再应用独立 GPU 路径和 Mac 路径增加的 12% 权重开销，因为公开的 GB10 分配日志显示没有此类开销（计算值与公开日志中的实测值对比）。这里绝不会扣除 Gemma 4 PLE（主机缓冲区使用的是同一内存池），且 GB10 系统不能与其他 GPU 合并计算（安全失败）。每个数值的来源 URL 都在 engine.js 中。

GB10 集群（2× / 4× DGX Spark）。 只有在分布式运行时通过 ConnectX-7 将模型切分到多个相同的 GB10 设备上时，这些设备的总容量才会用于计算单个模型——NVIDIA 记录了 vLLM 搭配 Ray，以及 TensorRT-LLM 使用与设备数量相等的张量并行度；两台设备通过 QSFP 线缆直连，四台则通过 RoCE 交换机连接（2026 年 4 月起的 DGX OS）。npx fitllm <model> --gpu "DGX Spark 128GB" --count 2（或 --gpu "2× DGX Spark 128GB"）会分别计算每台设备的预留空间和激活缓冲区；当模型的 KV 头数少于设备数量，或使用 MLA 潜在缓存或 DeepSeek 压缩缓存时，KV 缓存按副本计算（这是 vLLM / TensorRT-LLM 的张量并行行为；按层切分所需空间会更少）。三台设备（环形拓扑）、超过四台设备，或与其他 GPU 混用时，均会安全失败。NVIDIA 所称的“两台设备，最高支持 405B”是仅按 FP4 权重计算的数值；计算器会按你的上下文长度给出结果。

此外，parseHfConfig() 会将经验证、已建模的 Hugging Face 架构系列配置转换为上述模型结构；不支持的结构会安全失败，而不是返回猜测结果。（不预测 token/s——这是刻意设计的：速度取决于运行时和后端，静态模型无法如实给出预测。能否装下是可验证的结论；速度则不是。）

结构性前提

某些判定只有在对制品或运行时路径作出结构性前提的情况下才成立。引擎根据计算所用的同一组规范化模型字段推导出当前适用的前提，并将其作为 structuralAssumptions 附加到受影响的结果中，这是一个 { id, statement } 数组。未受影响的结果（例如普通 GQA 模型）不会包含此键，因此旧版 JSON 结构保持不变。CLI 在文本模式下会将每条当前适用的前提打印为 premise [id]: 行，并在 --json 中包含该数组（--top --json 中也会为每一行包含该数组）；--why 和复合 Action 也会传递同一数组。这里没有运行时选择器、置信度评分或速度声明：前提说明的是内存计算所依据的假设，而不是模型的运行速度。

• mla-compressed-latent-cache — KV 内存假定使用压缩潜变量 MLA 工件或模式；旧版非 MLA GGUF 或明确未压缩的模式会使此估算失效。来源：DeepSeek-V3 推理 model.py · llama.cpp convert_hf_to_gguf.py · llama.cpp llama-kv-cache.cpp。
• ple-llamacpp-non-gpu-residency — GPU 权重内存不包含已验证的 Gemma 4 PLE 张量，仅因为固定版本的 llama.cpp/GGUF 路径会将 per_layer_token_embd 输入层张量分配到 CPU/主机缓冲区，而非加速器内存；此处未将该主机内存计入预算，若运行时将 PLE 加载到加速器上，此估算便会失效。来源：Gemma 4 E2B config.json（文本主体的 model_type 恰为 gemma4_text）· 固定版本 llama.cpp 8b4b3558f1459c13e4aa38d5c94d306a00dc6acd：输入层设备分配 · PER_LAYER_TOKEN_EMBD 作为输入层张量 · Gemma 4 构造 · 加载器头文件 · 加载器实现。此推断仅适用于目录条目 Gemma 4 e2b 和 Gemma 4 e4b（pleOffloadVerified: true），以及文本主体恰为 gemma4_text 且完整配置（层数、hidden_size、intermediate_size 和两个 PLE 维度）与固定版本的官方 E2B/E4B 配置匹配、并且检查点与配置自身的稠密主体相符的已解析配置。其他模型系列中相似的字段、被修改的维度或层数，或不一致的检查点，都会使完整权重保留在 GPU 上，因此未经验证的配置无法将判定从“不适用”翻转为“适用”。
• native-fp4-expert-weights — 附加到发布时专家权重采用 FP4 的模型（gpt-oss-20b / 120b 使用 MXFP4，DeepSeek-V4-Flash / V4-Pro / V4.1-Flash-1017）：每 32 个值包含 4 位 E2M1 值和一个 E8M0 缩放值，共 4.25 位。权重精度高于 4.25 位时，这些张量按发布时的大小计算，只有其他权重遵循所选档位，因为 GGUF 原生支持 MXFP4 类型，公开的 GGUF 在所有级别都保留这些张量。如果已知模型的公开 GGUF 文件（gpt-oss），权重计算值不会低于所选档位中最大的文件——gpt-oss-120b Q4_K_M 为 58.53 GiB、Q8_0 为 59.03 GiB、F16 为 60.88 GiB，而发布版为 60.77 GiB（档位平均值分别为 66.55 / 115.59 / 217.56 GiB）；F16 文件比发布版高 0.18%，因为 GGUF 将偏置和范数存储为 F32。如果没有已知的同档位公开文件（DeepSeek-V4，以及与目录条目不完全逐张量匹配的 Hugging Face 检查点），权重计算值不会低于发布的检查点本身（F16 时这些 F32 副本还会增加 0.25%）。将专家权重重新扩展为 8 位或 16 位的构建版本（一个 MLX 8 位构建版本为 115.6 GiB）会更大，却不会增加精度，因此不在此计算范围内；低于 4.25 位（Mac 4 位）时，专家权重遵循所选精度。FP8（E4M3）权重不属于此类：GGUF 没有 FP8 类型，因此 Q8_0 和 BF16 GGUF 会对其重新编码，档位大小与已发布文件相符（GLM-5.3 Q8_0 为 746.3 GiB，BF16 为 1,404.4 GiB；FP8 发布版为 703.7 GiB）。来源：ggml GGML_TYPE_MXFP4 · llama-quantize 保留已量化张量 · unsloth/gpt-oss-120b-GGUF 文件大小 · ggml-org/gpt-oss-120b-GGUF · bartowski/openai_gpt-oss-120b-GGUF · openai/gpt-oss-120b 发布版 · unsloth/DeepSeek-V4-Flash-GGUF · unsloth/GLM-5.3-GGUF。
• deepseek-compressed-sparse-kv — KV 内存遵循 DeepSeek 参考推理代码中的缓存缓冲区：每层都有滑动窗口缓存，只有压缩自身 KV 的层才有压缩缓存和索引器键；按所选 KV 精度计算（16 位 = 参考代码的 bf16 缓冲区），并计入压缩器的 fp32 状态、V4.1 的 Engram 令牌历史，以及 512 MiB 索引器预填充工作区（vLLM 的默认值 VLLM_SPARSE_INDEXER_MAX_LOGITS_MB），每个关联的 GB10 单元均完整计入。参考 generate.py 中的整段提示词预填充（其索引器分数张量随提示词 × 上下文增长），以及缓存未压缩 KV 的运行时，需要更多内存，不在此模型范围内。无论权重量化方式如何，V4.1 的 196.6B Engram 表计算值都不会低于其 FP8 存储大小（含缩放值时为 8.25 位）；视觉塔和 MTP/DSpark 草稿权重计为常驻权重。来源：DeepSeek-V4-Flash 推理 model.py · DeepSeek-V4.1-Flash-1017 推理 model.py · engram.py · DeepSeek-V4.1-Flash 技术报告（全局 KV 为 890 字节/令牌） · vLLM DeepSeek V4 博文（V4-Pro 在 1M 上下文下 bf16 KV 为 9.62 GiB） · vLLM envs.py（索引器 logits 预算） · vLLM 索引器预填充分块。
• mtp-ordinary-generation — KV 内存假定进行普通的非推测式生成；不包含 MTP 草稿上下文。来源：llama.cpp llama-hparams.cpp · llama.cpp llama-model.cpp · llama.cpp convert_hf_to_gguf.py · vLLM qwen3_next_mtp.py。
• gb10-cluster-tensor-parallel — 附加到 2× / 4× GB10 判定：只有在运行时将一个模型拆分到多个单元上运行时，各单元的资源才能累加（使用 Ray 的 vLLM 或 TensorRT-LLM，张量并行度 = 单元数）；Ollama 和 LM Studio 使用单个单元；计入每单元的预留内存、激活缓冲区和张量并行 KV 复制；不计网络/NCCL 缓冲区和不均匀拆分。来源：NVIDIA DGX Spark 集群 · NVIDIA：最多四个节点（2026-03-16） · NVIDIA vLLM 操作手册 · vLLM 解码上下文并行 — MLA KV 在每个 TP rank 上复制 · TensorRT-LLM 并行策略 · ServeTheHome GB10 集群。
• gb10-cluster-tensor-parallel-incompatible — 当模型的注意力头、KV 头或线性注意力头数无法被单元数整除时附加（vLLM / TensorRT-LLM 会拒绝该张量并行规模）；判定为 no，且不声称集群可以容纳该模型。来源：vLLM llama.py 头数可整除性断言。
• gb10-unified-memory-reserve — 附加到每个 GB10（DGX Spark 级别）判定：预留量会扣除 DGX OS 无法看到的内存、DGX OS 空闲时的用量，以及 2 GiB 运行时余量；单个单元上的 GGUF 权重按文件大小计算，不额外增加百分比，另计 KV 缓存的 15% 和按上下文规模调整的激活内存额度——该额度根据启用闪存注意力的 llama.cpp/Ollama 运行校准（两者默认都使用 --flash-attn auto：llama.cpp common.h · Ollama llama_server.go）；关闭闪存注意力时（llama.cpp 随后会保留完整的注意力分数）以及使用 vLLM 时（CUDA 图、预分配的 KV 池）需要更多内存，此处未计入；其他正在运行的应用、文件页缓存、llama-server 的主机端提示词缓存（--cache-ram，默认 8 GiB）和上下文检查点均未计入；假定权重只常驻一份（加载时会保留 mmap 页缓存副本的加载器，可能需要额外一份权重大小的内存）。来源：NVIDIA DGX Spark 移植指南 — 没有固定的 GPU 内存划分 · NVIDIA DGX Spark 已知问题 — nvidia-smi 内存显示“Not Supported”、刷新页缓存 · MemTotal/CUDA 总量测量：bloomery #13 · NVIDIA 开发者论坛 · Back2Gaming · 空闲时用量：AAIF · Techno Tim。 常驻范围。 SSD/NVMe 流式处理、专家分页、交换分区以及通用 CPU/RAM 卸载均不纳入常规 FitLLM 适配判定。唯一披露的结构性例外是一个放置事实，而非存储分页：对于已验证的 Gemma 4 e2b/e4b 条目，独立 GPU 判定不包含逐层嵌入（PLE）张量，因为固定版本的 llama.cpp/GGUF 路径会确定性地将该输入层张量分配到 CPU/主机缓冲区，而非加速器内存（判定中会显示前提 ple-llamacpp-non-gpu-residency）。独立 GPU 判定不将该主机/系统内存计入预算；若运行时将 PLE 加载到加速器，则 PLE 估算会失效；在 Apple 统一内存和 GB10（DGX Spark）统一内存上，仍会计入全部权重。

npx fitllm "GLM-4.7-Flash" --gpu "RTX 4090"          # text adds:  premise [mla-compressed-latent-cache]: KV memory assumes …
npx fitllm "GLM-4.7-Flash" --gpu "RTX 4090" --json   # adds "structuralAssumptions": [{ "id": "…", "statement": "…" }]
npx fitllm "Llama-3.1-8B-Instruct" --gpu "RTX 4090" --json   # plain GQA: no structuralAssumptions key at all

用法

// from npm:  npm install fitllm-engine
import { simulate, structuralAssumptions, LOCAL_MODELS, GPUS, gpuDevice, parseHfConfig } from 'fitllm-engine';
// …or vendored single-file:
// import { simulate, structuralAssumptions, LOCAL_MODELS, GPUS, gpuDevice, parseHfConfig } from './engine.js';

const model = LOCAL_MODELS.find((m) => m.name === 'Gemma 4 31b');
const sim = simulate(model, /*ram*/ 64, /*ctx*/ 131072, /*bits*/ 8);
// → { used, free, verdict: 'yes'|'tight'|'no', param, kv, rt, os, maxContext, ... }

// affected results carry the active structural premises; plain GQA results have no such key:
const gpu = gpuDevice(GPUS.find((g) => g.name === 'RTX 4090'));
const mla = simulate(LOCAL_MODELS.find((m) => m.name === 'GLM-4.7-Flash'), gpu, 8192, { weightBpw: 4.8944, kvBits: 16 });
mla.structuralAssumptions; // → [{ id: 'mla-compressed-latent-cache', statement: '…' }]
structuralAssumptions(model, gpu); // → [] for an unaffected model (pure; same inputs as the calculation)

// a config from a modeled Hugging Face architecture family:
const m = parseHfConfig('Qwen/Qwen3-32B', configJson, totalSizeBytes);

验证

在仓库检出目录中，运行 npm run benchmark:accuracy（或添加 -- --json）以重新计算类型化的实测与预测账目。运行 npm run benchmark:differential 执行固定版本估算器差异测试。若要从单独下载的官方 llmfit 发布制品中重新捕获未截断的源输出：

npm run benchmark:capture:llmfit -- --binary /path/to/llmfit --artifact /path/to/llmfit-v1.1.12-x86_64-unknown-linux-gnu.tar.gz

该差异测试标记为 architecture_differential_not_runtime_accuracy：它展示了估算器如何处理 GQA、滑动窗口注意力和 MLA，但并非运行时测量证据。方法、竞品输入格式、校验和以及预先承诺的终止条件见 benchmarks/README.md。当前证据尚未通过比较准确性声明门槛。

• 根据官方 HuggingFace config.json 核对架构数值。
• Gemma 4 31B 全上下文 KV 重现了 20.78 GiB，与已发表的架构分析一致。手动复现方法如下：

global: 10 layers × 2(K,V) × 4 heads × 512 dim × 2 B × 262,144 = 21,474,836,480 B
local:  50 layers × 2(K,V) × 16 heads × 256 dim × 2 B × 1,024  =    838,860,800 B
total = 22,313,697,280 B ÷ 1024³ = 20.78 GiB

• MLA 每令牌成本：GLM-4.7-Flash = (512 + 64) × 2 B × 47 层 = 54,144 B/令牌——由一致性测试向量固定。

GB10（DGX Spark 级别）：公开日志中的计算值与实测值

检查日期：2026-10-20。日志记录值是本次运行的下限（allocation_floor），按行统计。Qwen 行：运行时加载模型时列出的缓冲区总和（权重、KV 缓存、循环状态、计算、输出）；不包括同一日志列出的视觉编码器 248 MiB CPU 计算缓冲区、编码器自身的权重、CUDA 上下文，以及随使用增长的缓存。Gemma 行：每个进程的 nvidia-smi 数值，其中包括 CUDA 上下文，但不包括主机内存。计算值 = 权重 + KV 缓存 + 循环状态 + 运行时缓冲区，不包括 13.3 GiB 的 GB10 预留（操作系统无法看到的 6.3 GiB、空闲 DGX OS 约 5 GiB、运行时预留 2 GiB）。相关条目、原始日志哈希及核验依据见 fixtures/measured.json；test/gb10-measured.test.mjs 确保计算值高于每个下限，且权重与日志中的模型缓冲区相差不超过 3%。

实测平台 · 日期 · 来源	模型 · 运行时 · 设置	日志记录值（下限）	2.21.3（不含预留）	2.21.4（不含预留）
ASUS Ascent GX10 · 2026-06-07 · ollama#16610（附日志）	Qwen3.6-35B-A3B BF16 GGUF · 通过 Ollama 0.30.6 运行 llama-server · ctx 65,536 · KV q8_0 · flash-attn	66.84 GiB	75.76（+13.4%）	67.94（+1.6%）
同一台机器和日志	相同 · ctx 102,400	67.42 GiB	77.27（+14.6%）	69.45（+3.0%）
同一台机器，Ollama 0.24.0 日志 ¹	Qwen3.6-35B-A3B Q8_0 · Ollama 自有引擎 · ctx 102,400 · KV q8_0	40.3 GiB	43.05（+6.8%）	38.89（−3.5%）
DGX Spark · 2026-04-09 · NVIDIA 论坛 366162	Gemma 4 31B F16 GGUF · llama-server（源码构建）· ctx 65,536 · KV q8_0 · flash-attn	62.60 GiB（nvidia-smi）	69.34（+10.8%）	62.48（−0.2%）

**2.21.3 的偏差所在：**它将权重的 12% 计作运行时开销——对 35B BF16 文件而言是 7.8 GiB。日志显示，GGUF 按文件大小加载（66,221.98 + 970.00 MiB = 65.62 GiB），计算缓冲区为 0.5–0.7 GiB（llama.cpp）或 1.7 GiB（Ollama 引擎）。2.21.4 在一台 GB10 设备上去掉了这 12%；15% 的 KV 缓冲余量和按上下文规模计算的激活值预留则保持不变。加上预留中包含的 2 GiB 运行时预留后，2.21.4 比每行数据都高出 1.5–6.0%——这为下限未计入的内存留出了余量，本身并不代表有误。

**限制：**在两台机器上进行了四次运行，全部开启了 flash attention（llama.cpp 和 Ollama 的默认值 --flash-attn auto）。关闭后，llama.cpp 会保留完整的注意力分数——对于 48 个注意力头、262K 个 token、批量大小 512 的模型，约需 24 GiB，并随批量大小增长——任何版本都不会为此预留；单台设备上的 vLLM（CUDA graphs、预分配的 KV 池）也不在覆盖范围内。随使用增长的主机内存未计入任何一行：llama-server 的提示词缓存（默认最高 8 GiB）以及最多 32 个上下文检查点。¹ Ollama 0.24.0 报告的 KV 缓存是手工计算值的 2.5 倍，日志对此未作解释——该行仅用于核对下限（community_unverified）。独立 GPU、GB10 集群和 Mac 仍采用 12%：目前都没有类似的运行时分配核验（账本中的 Mac 条目是空闲时的常驻权重读数）。同一张表也见于 fitllm.run/data。

所有数值均为估算值——实际用量会因运行时（MLX/Ollama/llama.cpp）、操作系统状态和量化方案而异。

符合性向量

vectors/fit-vectors-v1.json 固定了 49 个与语言无关的测试向量（精确的 KV 字节数、每个 token 的成本、适配判定），这些数据是根据官方 config.json 值手动推导得出的——例如 “Gemma 4 31B 在 262,144 ctx、bf16 下恰好占用 22,313,697,280 字节”。任何语言的实现，只要通过所有向量，就符合标准——运行我们的实现：node vectors/run.mjs。

这为何重要：公式很容易照搬，经过验证的答案集却不然。如果你将这个引擎移植到 Python、Rust 或 Go，你并不会变成一个不受信任的分支——通过这些向量，你就是同一标准的符合性实现。移植引擎，保留向量。

适配普查——每个模型 × 每台设备，一张真实结果表

census/ 包含 13,804 项判定（34 个模型，含草稿层级 × 104 款 GPU/Mac × 多个量化层级），由此引擎计算得出——提供可导入、制图或引用的 CSV/JSON，以及一个入门矩阵（“每台设备能轻松运行的最大模型”）。你也可以自行重新生成：npm run census。现实测量结果通过 fixtures/ PR 与预测并列呈现——公开对比预测值与实测值。

嵌入适配徽章

实时调用引擎，显示模型能否在指定硬件上运行——只需在任意 README 或模型卡中添加一行：

![fits](https://img.shields.io/endpoint?url=https%3A%2F%2Ffitllm.run%2Fapi%2Fbadge%3Fmodel%3DGLM-4.7-Flash%26gpu%3D4090)

参数：model（名称，模糊匹配）、gpu（名称，模糊匹配）或 ram（GB，Apple 统一内存），可选参数 quant（GGUF 量化层级 / 4|8|16）、ctx、kv。判定颜色：绿色表示适配 · 黄色表示勉强适配 · 红色表示无法运行。

为何要嵌入徽章？ 每张模型卡和本地 AI 教程下最常见的问题都是：“我的机器能运行吗？” 这个徽章会实时调用引擎给出答案——数据更新时会重新计算，而不是 README 中冻结的过时说法。如果你发布模型或编写指南：一行徽章就能替代整段常见问题解答，并在“我的 8GB 显卡内存溢出了”问题提交之前将其消除。

向 AI 助手提问（MCP）

该引擎作为公共 MCP 服务运行于 https://fitllm.run/api/mcp——连接一次后，你的助手就能使用此引擎的计算结果回答*“我的 Y 能运行 X 吗？”*，而不是根据过时的训练数据猜测（LLM 经常算错 KV 缓存——参见上方的 17.8× 表格）。

• Claude（网页端 / 桌面端 / 移动端）：设置 → 连接器 → 添加自定义连接器 → 粘贴 https://fitllm.run/api/mcp
• Claude Code：claude mcp add --transport http fitllm https://fitllm.run/api/mcp
• Cursor / Windsurf：添加到 mcp.json → { "mcpServers": { "fitllm": { "url": "https://fitllm.run/api/mcp" } } }
• ChatGPT：设置 → 应用 → 高级 → 开发者模式 → 添加 MCP 服务（Plus/Pro）

工具：check_llm_fit（判定 + 完整内存明细 + 修复建议——支持多 GPU 设备，例如 "RTX 5090 + RTX 3090"）、what_fits_on_hardware（为你的机器提供排序列表）、list_supported。资源：fitllm://models、fitllm://hardware、fitllm://census、fitllm://engine。有意保持开放：只读、无状态、无需身份验证、不含密钥——每次调用都只是公共数据的纯函数。

收录于：官方 MCP 注册表（run.fitllm/fitllm） · Glama · mcp.so · Smithery

面向 Agent 和脚本——纯 HTTP API

没有 MCP 客户端？只需发送一次 GET 请求，无需身份验证或密钥——默认返回 JSON，也可为 curl 返回纯文本：

curl 'https://fitllm.run/api/check?model=gemma%204%2031b&gpu=4090'
# multi-GPU rigs: gpu=5090%2B3090 · Mac: ram=64 · usage: curl https://fitllm.run/api/check

开放数据：完整的 适配普查（13,804 项判定，CC0）位于 fitllm.run/data，也发布在 Hugging Face Datasets。在浏览器中试用引擎：HF Space 演示。

原则

没有广告。无需登录。没有推广链接。输出绝不出售。 适配性是一个可验证、可实现的判断；原始 tok/s 则不是——因此，本引擎拒绝预测速度，而不把猜测伪装成精确结果。

协助校准

运行了模型并测量了实际峰值内存？报告测量结果——这能改进面向所有人的估算。

构建者

yongha — GitHub。为 fitllm.run 提供支持。

许可证

MIT © click6067-ship-it