AI: 介绍微软 BitNet 下载、安装、使用说明

Microsoft BitNet 下载、安装与使用指南

BitNet 是微软公司开源的 1-bit 大语言模型推理框架，最大的特点是仅用 CPU 就能高效运行大模型，内存占用极低。以下是完整的安装和使用教程。

📋 一、环境要求

依赖项	版本要求	说明
Python	≥ 3.9	推荐使用 conda 管理环境
CMake	≥ 3.22	构建系统
Clang	≥ 18	编译器
Git	任意版本	克隆仓库，需支持 `--recursive`

各操作系统具体要求

Windows：需安装 Visual Studio 2022，并勾选以下组件：

桌面开发与 C++
C++ 的 CMake 工具
Windows 的 Git
C++ 的 Clang 编译器
LLVM-Toolset (clang) 的 MS-Build 支持

Debian/Ubuntu：可用自动脚本安装 Clang：

bash 复制代码

bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"

macOS：通过 Homebrew 安装 CMake：

bash 复制代码

brew install cmake

🚀 二、快速开始（5 分钟上手）

1. 克隆仓库

bash 复制代码

git clone --recursive https://github.com/microsoft/BitNet.git
cd BitNet

⚠️ 必须使用 --recursive 参数，否则子模块不会自动下载。

2. 创建 Python 环境并安装依赖

bash 复制代码

# 创建 conda 环境（推荐）
conda create -n bitnet-cpp python=3.9
conda activate bitnet-cpp

# 安装 Python 依赖
pip install -r requirements.txt

3. 下载模型并构建项目

最简单的方式是用 setup_env.py 一键完成模型下载、格式转换和编译：

bash 复制代码

# 以 Falcon3-7B 模型为例
python setup_env.py --hf-repo tiiuae/Falcon3-7B-Instruct-1.58bit -q i2_s

也可手动下载模型后再构建：

bash 复制代码

# 下载模型
huggingface-cli download microsoft/BitNet-b1.58-2B-4T-gguf --local-dir models/BitNet-2B

# 构建
python setup_env.py -md models/BitNet-2B -q i2_s

4. 运行推理

bash 复制代码

# 对话模式
python run_inference.py -m models/BitNet-2B/ggml-model-i2_s.gguf -p "你是一个 helpful assistant" -cnv

🛠️ 三、各平台详细安装说明

Windows 用户必读：构建坑点及解决方案

根据社区反馈，Windows 上编译 BitNet 需要特别注意两个问题：

问题 1：缺少头文件引用

部分上游 llama.cpp 文件存在 bug，需手动修复 4 个文件，在头部添加 #include <chrono>：

3rdparty/llama.cpp/common/common.cpp
3rdparty/llama.cpp/common/log.cpp
3rdparty/llama.cpp/examples/imatrix/imatrix.cpp
3rdparty/llama.cpp/examples/perplexity/perplexity.cpp

问题 2：conda 环境无法使用 clang 构建

需要加载 Visual Studio 的开发者环境：

powershell 复制代码

# 1. 加载 DevShell 模块
Import-Module "C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"

# 2. 获取 VS 实例 ID
Install-Module -Name VSSetup -Scope CurrentUser -Force
Import-Module VSSetup
Get-VSSetupInstance   # 记录输出的 InstanceId

# 3. 进入开发者环境（替换为你的 InstanceId）
Enter-VsDevShell 6d25e4c3 -SkipAutomaticLocation -DevCmdArguments "-arch=x64 -host_arch=x64"

# 4. 验证 clang 可用
clang -v

Linux / macOS 用户

Linux 流程相对顺畅，按上述"快速开始"步骤即可。若在 macOS 上遇到问题，确保：

bash 复制代码

# 确认 CMake 已安装
brew install cmake

# 更新子模块
git submodule update --init --recursive

不想折腾？用 Docker 一键运行

社区已有人制作了 Docker 镜像，省去所有环境配置：

bash 复制代码

git clone https://github.com/ahfuzhang/BitNet.git
cd BitNet
docker build -t local-bitnet:latest .

运行推理：

bash 复制代码

# 单次问答
docker run --rm -it --cpuset-cpus="8" -m 512m local-bitnet:latest \
    python3 run_inference.py -m models/BitNet-b1.58-2B-4T/ggml-model-i2_s.gguf \
    -t 1 -c 4096 -n 1024 -temp 0.7 -p "什么是 1-bit 模型？"

# 对话模式
docker run --rm -it --cpuset-cpus="8" -m 512m local-bitnet:latest \
    python3 run_inference.py -m models/BitNet-b1.58-2B-4T/ggml-model-i2_s.gguf \
    -t 1 -c 4096 -n 1024 -temp 0.7 -p "" -cnv

💡 仅需 512MB 内存 + 1 个 CPU 核心 就能流畅运行 20 亿参数模型。

📊 四、推理命令详解

基础命令格式

bash 复制代码

python run_inference.py -m <模型路径> -p <提示词> [选项]

常用参数说明

参数	简写	说明	默认值
`--model`	`-m`	模型文件路径（.gguf 文件）	必填
`--prompt`	`-p`	输入提示词	必填
`--n-predict`	`-n`	生成的最大 token 数	128
`--threads`	`-t`	CPU 线程数	2
`--ctx-size`	`-c`	上下文窗口大小	2048
`--temperature`	`-temp`	温度值（0~1，越高越随机）	0.8
`--conversation`	`-cnv`	开启对话交互模式	否

示例

bash 复制代码

# 生成 512 个 token，用 4 个线程，温度 0.7
python run_inference.py -m models/bitnet-model.gguf -p "写一首关于 AI 的诗" -n 512 -t 4 -temp 0.7

# 对话模式，上下文 4096
python run_inference.py -m models/bitnet-model.gguf -p "" -cnv -c 4096

📁 五、可用模型清单

所有模型均托管在 Hugging Face，可通过 setup_env.py 或 huggingface-cli 下载：

模型名称	参数量	特点
`microsoft/BitNet-b1.58-2B-4T-gguf`	2.4B	低延迟聊天，适合入门
`microsoft/BitNet-b1.58-3B-gguf`	3B	平衡速度与质量
`HF1BitLLM/Llama3-8B-1.58-100B-tokens`	8B	基于 Llama3 的 1.58-bit 版本
`tiiuae/Falcon3-7B-Instruct-1.58bit`	7B	Falcon 架构，指令微调版

⚠️ 六、当前版本注意事项

BitNet 目前仍在快速迭代中，存在以下已知问题：

输出不稳定：可能出现重复词、循环输出或无意义内容
知识准确度：2B 小模型在复杂问答上表现有限
平台差异：macOS 下偶现随机异常输出
Windows 构建：需要额外修复和 VS 环境配置

这些都是开源社区正在解决的问题，随着版本更新会逐步改善。

📌 七、命令速查表

操作	命令
克隆仓库	`git clone --recursive https://github.com/microsoft/BitNet.git`
安装依赖	`pip install -r requirements.txt`
下载模型	`huggingface-cli download <模型ID> --local-dir models/<名称>`
一键构建	`python setup_env.py -md models/<名称> -q i2_s`
运行推理	`python run_inference.py -m <模型.gguf> -p "<提示词>"`
对话模式	添加 `-cnv` 参数
Docker 构建	`docker build -t local-bitnet:latest .`

如果遇到问题，建议优先查阅微软官方 GitHub 仓库的 Issues 页面，或尝试 Docker 方式避免环境差异带来的麻烦。

我的实践经验

git clone https://hf-mirror.com/microsoft/bitnet-b1.58-2B-4T-gguf

复制代码

cd D:\AI
D:\AI> git clone --recursive https://github.com/microsoft/BitNet.git
Cloning into 'BitNet'...
error: RPC failed; curl 28 Recv failure: Connection was reset
fatal: expected flush after ref listing

D:\AI> git clone --recursive https://github.com/ahfuzhang/BitNet.git
Cloning into 'BitNet'...
remote: Enumerating objects: 414, done.
remote: Counting objects: 100% (63/63), done.
remote: Compressing objects: 100% (46/46), done.
remote: Total 414 (delta 34), reused 22 (delta 17), pack-reused 351 (from 3)
Receiving objects: 100% (414/414), 8.05 MiB | 138.00 KiB/s, done.
Resolving deltas: 100% (174/174), done.
Submodule '3rdparty/llama.cpp' (https://github.com/Eddie-Wang1120/llama.cpp.git) registered for path '3rdparty/llama.cpp'
Cloning into 'D:/AI/BitNet/3rdparty/llama.cpp'...
remote: Enumerating objects: 25639, done.
remote: Total 25639 (delta 0), reused 0 (delta 0), pack-reused 25639 (from 1)
Receiving objects: 100% (25639/25639), 59.61 MiB | 140.00 KiB/s, done.
Resolving deltas: 100% (18206/18206), done.
Submodule path '3rdparty/llama.cpp': checked out '1f86f058de0c3f4098dedae2ae8653c335c868a1'
Submodule 'kompute' (https://github.com/nomic-ai/kompute.git) registered for path '3rdparty/llama.cpp/ggml/src/kompute'
Cloning into 'D:/AI/BitNet/3rdparty/llama.cpp/ggml/src/kompute'...
fatal: unable to access 'https://github.com/nomic-ai/kompute.git/': Failed to connect to github.com port 443 after 21083 ms: Could not connect to server
fatal: clone of 'https://github.com/nomic-ai/kompute.git' into submodule path 'D:/AI/BitNet/3rdparty/llama.cpp/ggml/src/kompute' failed
Failed to clone 'ggml/src/kompute'. Retry scheduled
Cloning into 'D:/AI/BitNet/3rdparty/llama.cpp/ggml/src/kompute'...
error: RPC failed; curl 28 Recv failure: Connection was reset
fatal: expected flush after ref listing
fatal: clone of 'https://github.com/nomic-ai/kompute.git' into submodule path 'D:/AI/BitNet/3rdparty/llama.cpp/ggml/src/kompute' failed
Failed to clone 'ggml/src/kompute' a second time, aborting
fatal: Failed to recurse into submodule path '3rdparty/llama.cpp'

(base) D:\AI>cd BitNet

(base) D:\AI\BitNet>conda activate bitnet-cpp

(bitnet-cpp) D:\AI\BitNet>where pip
D:\anaconda3\envs\bitnet-cpp\Scripts\pip.exe

(bitnet-cpp) D:\AI\BitNet> pip install -r requirements.txt
Looking in indexes: https://pypi.org/simple, https://download.pytorch.org/whl/cpu, https://download.pytorch.org/whl/cpu, https://download.pytorch.org/whl/cpu, https://download.pytorch.org/whl/cpu
......
Successfully installed MarkupSafe-3.0.3 certifi-2026.2.25 charset_normalizer-3.4.6 colorama-0.4.6 filelock-3.25.2 fsspec-2026.2.0 gguf-0.18.0 huggingface-hub-0.36.2 idna-3.11 jinja2-3.1.6 mpmath-1.3.0 networkx-3.4.2 numpy-1.26.4 protobuf-4.25.8 pyyaml-6.0.3 regex-2026.2.28 requests-2.32.5 safetensors-0.7.0 sentencepiece-0.2.1 sympy-1.14.0 tokenizers-0.22.2 torch-2.2.2+cpu tqdm-4.67.3 transformers-4.57.6 typing-extensions-4.15.0 urllib3-2.6.3

(bitnet-cpp) D:\AI\BitNet> where huggingface-cli
D:\anaconda3\envs\bitnet-cpp\Scripts\huggingface-cli.exe

(bitnet-cpp) D:\AI\BitNet>huggingface-cli download microsoft/BitNet-b1.58-2B-4T-gguf --local-dir models/BitNet-2B
⚠️  Warning: 'huggingface-cli download' is deprecated. Use 'hf download' instead.
Fetching 4 files:   0%|                                                                          | 0/4 [00:00<?, ?it/s]Still waiting to acquire lock on models\BitNet-2B\.cache\huggingface\.gitignore.lock (elapsed: 0.1 seconds)
Downloading '.gitattributes' to 'models\BitNet-2B\.cache\huggingface\download\wPaCkH-WbT7GsmxMKKrNZTV4nSM=.4e3e1a539c8d36087c5f8435e653b7dc694a0da6.incomplete'
.gitattributes: 1.64kB [00:00, ?B/s]
Download complete. Moving file to models\BitNet-2B\.gitattributes
Fetching 4 files:  25%|████████████████▌                                                 | 1/4 [00:00<00:01,  1.81it/s]Downloading 'data_summary_card.md' to 'models\BitNet-2B\.cache\huggingface\download\rO2cXQjMJqsORRCCpgXS1A8CgMk=.156c5705d7cf1e2f11a27e62f673c4576af7aa19.incomplete'
data_summary_card.md: 3.86kB [00:00, ?B/s]
Download complete. Moving file to models\BitNet-2B\data_summary_card.md
Downloading 'ggml-model-i2_s.gguf' to 'models\BitNet-2B\.cache\huggingface\download

AI: 介绍 微软 BitNet 下载、安装、使用说明

Microsoft BitNet 下载、安装与使用指南

📋 一、环境要求

各操作系统具体要求

🚀 二、快速开始（5 分钟上手）

1. 克隆仓库

2. 创建 Python 环境并安装依赖

3. 下载模型并构建项目

4. 运行推理

🛠️ 三、各平台详细安装说明

Windows 用户必读：构建坑点及解决方案

Linux / macOS 用户

不想折腾？用 Docker 一键运行

📊 四、推理命令详解

基础命令格式

常用参数说明

示例

📁 五、可用模型清单

⚠️ 六、当前版本注意事项

📌 七、命令速查表

我的实践经验

AI: 介绍微软 BitNet 下载、安装、使用说明