bitnet.cpp 中文教程：把源码、模型和基准一起固定
bitnet.cpp 是 Microsoft 为 BitNet/ternary 模型开发的推理框架。它提供 1.58-bit 专用 CPU/GPU kernels、模型转换和 CLI/server 示例。它不是把任意普通模型按一下按钮就无损压成 1.58-bit 的工具。
1. 先核对支持矩阵
官方表格按模型、x86/ARM 和 I2_S/TL1/TL2 分开标注。同一模型在 x86 可运行，不代表 ARM 或 GPU 也支持；两个 embedding 模型当前只在 x86 的 I2_S 路径标为支持。先确认组合，再准备工具链。
2. 固定主仓库与 submodules
git clone --recursive https://github.com/microsoft/BitNet.git
cd BitNet
git rev-parse HEAD
git submodule status仓库没有 release 资产，所以只写“最新版”不能复现。记录主 commit 和每个 submodule commit。不要直接执行 README 里的远程 apt 脚本；按操作系统包管理器手工安装并核对来源。
3. 准备隔离构建环境
官方要求 Python 3.10+、CMake 3.22+ 和 Clang 18+。新建独立 conda 或 venv，安装固定的 requirements，再确认编译器和 CMake 实际版本。Windows 还需要 Visual Studio 2022 的 C++、CMake、Clang 和 MSBuild 组件。
4. 固定模型 revision 与 hash
从 Microsoft 官方 Hugging Face 仓库选择明确支持的 GGUF，固定 revision，并记录每个模型文件的 SHA-256。模型仓库可能在同名文件下更新权重；只记录文件名无法解释以后出现的输出变化。
5. 编译后先跑最小正确性检查
用 setup_env.py 指定本地模型目录和量化格式，完成转换与构建。先用很短的固定 prompt 检查 tokenizer、终止条件和基本输出，再增加线程、上下文和批量参数。生成乱码或重复 token 时，先核对模型 hash 和支持矩阵。
6. 性能与质量必须一起测
官方报告列出的最高 6.17 倍速度和 82.2% 能耗下降来自特定 x86、模型与 baseline。自己的测试应固定 CPU governor、线程、prompt/prefill 长度和输出长度，同时记录 tokens/s、首 token 延迟、内存、功耗以及任务正确率。只快但答错没有实用收益。
7. 同类对比：bitnet.cpp 与 llama.cpp
相比 llama.cpp，bitnet.cpp 针对 BitNet/ternary 权重增加专用 kernel，模型范围更窄；llama.cpp 支持的常见 GGUF 架构、量化格式和发布生态更广。明确测试 1.58-bit 模型时用 bitnet.cpp，普通 GGUF 推理通常先看 llama.cpp。
8. 验证状态与边界
未验证：构建、模型 hash、转换、tokenizer、生成质量、速度、能耗、内存、GPU、Windows/ARM 与 server 接口。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
近期变化与关注原因
1-bit 权重希望降低内存带宽、能耗和 CPU 推理成本。官方 2026 年继续发布 CPU 优化、BitNet embedding 模型和 VibeASR.cpp，说明 kernels 已扩展到生成、向量和语音场景。本页依据官方仓库、模型卡与报告说明适用范围。
适合谁用
适合评估 ternary LLM 在 CPU/边缘设备上的内存、吞吐和能耗，或实验 BitNet embedding 与专用 GPU kernels。模型质量、prompt 行为、长上下文和工具调用能力取决于具体 checkpoint；框架 benchmark 不能替代任务级准确性评估。
采用建议
bitnet.cpp 适合做明确支持模型的 1-bit 本地推理实验，但安装页不应写成开箱即用。先固定 commit 与模型 hash，在隔离环境完成 CPU 构建，用一组真实任务同时检查质量、速度、内存和能耗；只看项目方最高加速数字没有决策价值。
原教程未展开的系统信息
核心功能
1.58-bit CPU kernels
针对 x86 与 ARM 提供 I2_S、TL1、TL2 等路径；具体模型、架构和量化类型的支持矩阵不同，不能把一个平台的勾选项套到另一个平台。
模型转换与预调优
setup_env.py 下载或读取本地模型、转换 GGUF/量化格式并编译匹配 kernel，可选择量化 embedding 和预调优参数。
CLI 与本地 server
run_inference.py 调用编译产物做生成或 benchmark，run_inference_server.py 提供本地服务入口；接口、模型文件和上下文参数仍需按仓库说明配置。
官方 GPU 与 embedding 扩展
仓库包含官方 GPU kernel 文档，并在 2026-07 发布 0.6B/270M 1-bit embedding 模型与 I2_S 转换指南；支持范围与生成模型不同。
技术栈和运行条件
语言
C/C++ kernels 与 Python 3.10+ 构建/运行脚本
框架
llama.cpp 派生推理核心 + GGUF + CMake + Clang
关键依赖
- CMake 3.22+ 与 Clang 18+
- Hugging Face CLI/模型文件与 Python requirements
- 可选 CUDA GPU kernel 或 x86 AVX/ARM NEON CPU 路径
运行环境
源码构建；Windows、Linux 与 macOS 的具体编译链不同；MIT 许可
常见问题
bitnet.cpp 能把任意 Llama 模型无损压成 1.58-bit 吗？
不能这样理解。它主要为 BitNet/ternary 架构和列入支持矩阵的模型提供推理与转换；普通模型直接压到三值权重会涉及训练和质量损失问题。
bitnet.cpp 当前最新 release 是哪个？
官方 README 显示 1.0 徽章和 2024-10-17 的 1.0 新闻，但 GitHub Releases 页面没有正式 release 资产。复现时应固定具体 commit 和模型 revision。
官方 6.17 倍速度提升适用于我的电脑吗？
不一定。结果取决于 CPU 指令集、线程数、模型、量化格式、prompt 长度和 baseline。应在同一硬件上用固定模型与参数同时测吞吐、延迟、内存和任务质量。
BitNet embedding 模型在 ARM 上也支持 I2_S 吗？
不能按生成模型的支持情况推断。官方当前矩阵把两个 embedding 模型的 I2_S 支持列在 x86 CPU，ARM 对应项未标支持。
bitnet.cpp 与 llama.cpp 怎么选？
模型明确是 BitNet/ternary 且支持矩阵匹配时用 bitnet.cpp；常见 GGUF 架构、更多量化格式或更成熟的发布生态通常先用 llama.cpp。