NF12 是一种无损、定长 12 位编码的 BF16 权重矩阵，基于论文《NyoomFloat12: Accelerating LLM Inference via Lossless 12-bit Weight Compression》（Liberman、Fang、Zhang、Dao、Fu，Together AI，2026）。本库在 NVIDIA GPU（从 Ampere 架构到 Blackwell）上高效实现了该数据类型。本库的位布局和内存布局（tiled）与论文中描述的格式不兼容。更多格式信息请参阅 spec。

需要 SM80 或更新架构的 NVIDIA GPU（Ampere 及之后）。需要 CUDA toolkit 13.0+、C++ 编译器、CMake 3.26+ 以及 Ninja 用于构建。使用 uv 管理 Python 环境和构建。Python 包需要 Python 3.10+ 和支持 CUDA 的 PyTorch 2.10+。

权重形状要求：N（out_features）必须是 16 的倍数，K（in_features）必须是 64 的倍数。

安装：

uv pip install nf12

Linux x86-64 和 ARM64 的 wheel 包含面向 SM80、86、89、90、100、110 和 120 的 kernel，并捆绑 CUDA 13 运行时，需要兼容的 NVIDIA 驱动。

uv sync --locked # 所有支持的架构 NF12_CUDA_ARCHS=120 uv sync --locked # 仅一个架构，用于开发

如需延迟到第一次原生操作时才编译：

NF12_BUILD_NATIVE=OFF uv sync --locked

也可以只用 CMake 单独构建 C 库：

cmake -B build/c -G Ninja -DNF12_BUILD_TORCH=OFF -DNF12_CUDA_ARCHS=120 cmake --build build/c

Python 用法：

import torch import nf12 w = torch.randn(4096, 4096, dtype=torch.bfloat16, device="cuda") nw = nf12.encode(w) assert torch.equal(nf12.decode(nw).view(torch.int16), w.view(torch.int16)) x = torch.randn(2, 7, 4096, dtype=torch.bfloat16, device="cuda") y = nf12.linear(x, nw) # 保留前置维度

使用 nf12.NF12Linear.from_linear(layer) 可以转换 BF16 CUDA 的 nn.Linear。解码可恢复原始权重。由于累加顺序不同，GEMM 输出可能与 cuBLAS 有所差异。

w13 = nf12.encode_moe(gate_up) # BF16 [E, 2I, K]，gate 行在前 w2 = nf12.encode_moe(down) # BF16 [E, K, I]

x: [T, K]，router weights 和 IDs: [T, topk]

out = nf12.fused_moe(x, w13, w2, topk_weights, topk_ids)

Embedding 与绑定头：

nw = nf12.encode(model.embed_tokens.weight) # BF16 [V, H] x = nf12.embedding(token_ids, nw) # [*token_ids.shape, H] embed = nf12.NF12Embedding.from_weight(nw) lm_head = nf12.NF12Linear.from_weight(nw) # 共享编码后的权重

基准测试

展开基准测试表格

服务吞吐对比 BF16

NF12 / BF16 的输出 token 每秒。每个单元格显示并发 1 / 8 / 32 的结果。高于 1× 表示 NF12 更优。HTTP 生成，128 输入 / 256 输出 token，68 次服务器运行，BF16/NF12 顺序交替。PyTorch 2.14，CUDA 13.0。*Qwen3-30B 在测试的内存上限下只能以 NF12 运行：CMP 170HX 上为 75%，Thor 上为 40%。BF16 在这些场景下未尝试。——：在 48 GB GPU 上排除。H200 Granite 的计时不稳定，因此未报告汇总加速比。服务测试框架使用了仅用于基准测试的 nf12.fused_moe 适配器。基线使用原生 BF16 后端，包括 B200 上的 FlashInfer TRT-LLM。Prefill 结果参差不齐。贪心输出可能不同；这些不是精度结果。

模型 BF16 GiB NF12 GiB Qwen3-8B 15.27 11.49 Granite 1B MoE 2.50 1.89 Qwen3-30B-A3B 56.88 42.80

单 token MoE kernel

NF12 层延迟，单位 µs（加速比是相对于之前的组合式 NF12 路径，而非 BF16）。真实权重，均匀路由，冷 CUDA graph 轮换至少 2 GiB。两次运行中位数的中位数。PyTorch 2.15，CUDA 13.2。

格式与 API 规范

C API

基准测试与测试

许可证

Apache-2.0。