笔记本电脑部署BitNet

BitNet是微软在2025年发布的，可以在CPU上运行的本地大模型。

之间搞好的wsl终于有了用武之地，成功在ubuntu上完成了部署。本文将介绍部署方法并进行效果展示。

一、简介

BitNet是第一个支持在CPU上进行推理的LLM。

本机环境

Win11下的wsl。

CPU：AMD Ryzen9 7940H
GPU：NVIDIA GeForce RTX 4060 Laptop GPU

二、部署

按照官方说明，我个人建议在Linux上部署，win上强制下载Visual Studio，需要的存储空间大，而且万一哪里点漏了需要重来，Linux上几行命令就可以搞定。

WSL（Ubuntu）准备

• git
• pip
• conda

README——作者省略版（Linux）

Requirements

• python>=3.9
• cmake>=3.22
• clang>=18

  就是这个clang，在win上必须要下载visual studio2022，我拒绝。但是ubuntu简单

下载clang

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

下载安装并执行 LLVM 官方提供的安装脚本，常用于在 Ubuntu 或 Debian 系统中安装 LLVM 工具链（如 clang、lld 等）
这些软件包提供 LLVM + Clang + compiler-rt + polly + LLDB + LLD + libFuzzer + libc++ + libc++abi + openmp + libclc + libunwind + MLIR + BOLT + flang + libc + wasm 支持
没成功也没关系，我好像就没有成功，后续手动安装了clang……

Build from source

wsl：进入自己的用户（有sudo权限的）和对应的空文件夹。

1. Clone the repo

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

2. Install the dependencies

# (Recommended) Create a new conda environment
conda create -n bitnet-cpp python=3.9
conda activate bitnet-cpp

pip install -r requirements.txt

可能需要cmake，可用cmake --version检查。没有的话就执行下面的:

sudo apt update
sudo apt install cmake

3. Build the project

# Manually download the model and run with local path
huggingface-cli download microsoft/BitNet-b1.58-2B-4T-gguf --local-dir models/BitNet-b1.58-2B-4T
python setup_env.py -md models/BitNet-b1.58-2B-4T -q i2_s

说明：

• 从 Hugging Face 下载 BitNet-b1.58-2B-4T-gguf 模型文件，并保存到你本地的 models/BitNet-b1.58-2B-4T 文件夹中。
• 使用 setup_env.py 脚本，基于本地路径下的 BitNet 模型，准备并编译运行环境，用于后续高效推理。

usage: setup_env.py [-h] 
             [--hf-repo 模型仓库名] 
             [--model-dir 模型目录] 
             [--log-dir 日志目录] 
             [--quant-type 量化类型] 
             [--quant-embd] 
             [--use-pretuned]

Setup the environment for running inference

optional arguments:
  -h, --help
                        显示帮助信息并退出
  --hf-repo {1bitLLM/bitnet_b1_58-large,1bitLLM/bitnet_b1_58-3B,HF1BitLLM/Llama3-8B-1.58-100B-tokens,
             tiiuae/Falcon3-1B-Instruct-1.58bit,tiiuae/Falcon3-3B-Instruct-1.58bit,
             tiiuae/Falcon3-7B-Instruct-1.58bit,tiiuae/Falcon3-10B-Instruct-1.58bit},
  -hr {同上}
                        要用于推理的模型（从 Hugging Face 下载）
  --model-dir MODEL_DIR, -md MODEL_DIR
                        模型保存或加载的本地目录
  --log-dir LOG_DIR, -ld LOG_DIR
                        保存日志信息的目录
  --quant-type {i2_s,tl1}, -q {i2_s,tl1}
                        模型的量化类型（如：i2_s 表示 2-bit 对称量化）
  --quant-embd
                        是否将嵌入层量化为 float16（f16）
  --use-pretuned, -p
                        是否使用已预调优的底层内核参数（提高性能）

如果LLVM成功安装的话，这里不会有任何报错。

如果失败，需要手动下载clang。

失败提示：

clang --version

提示无命令

安装clang

sudo apt install clang

clang 是必要的，无法通过gcc绕过。

三、Usage 用法

Basic usage

# Run inference with the quantized model
python run_inference.py -m models/BitNet-b1.58-2B-4T/ggml-model-i2_s.gguf -p "You are a helpful assistant" -cnv

说明

run_inference.py [-h] [-m MODEL] [-n N_PREDICT] -p PROMPT [-t THREADS] [-c CTX_SIZE] [-temp TEMPERATURE] [-cnv]

  -h, --help
                        显示帮助信息并退出
  -m MODEL, --model MODEL
                        模型文件的路径
  -n N_PREDICT, --n-predict N_PREDICT
                        生成文本时预测的 token 数量
  -p PROMPT, --prompt PROMPT
                        用于生成文本的提示词
  -t THREADS, --threads THREADS
                        使用的线程数量
  -c CTX_SIZE, --ctx-size CTX_SIZE
                        提示词上下文的长度
  -temp TEMPERATURE, --temperature TEMPERATURE
                        温度系数，控制生成文本的随机程度
  -cnv, --conversation
                        是否启用对话模式（用于 instruct 模型）
                        （启用时，-p 指定的 prompt 会作为系统提示词）

执行完之后就可以继续对话了。

说实话看起来笨笨的，之后再慢慢研究。

---

四、 权重版本总结

让GPT根据hugging face 部分的命令提供的注释，总结了仓库中提供的权重：

模型	权重大小	使用场景	精度	下载命令
1bitLLM/bitnet_b1_58-large	大	高精度推理任务，复杂语言任务处理	高	huggingface-cli download 1bitLLM/bitnet_b1_58-large --local-dir models/bitnet_b1_58-large
1bitLLM/bitnet_b1_58-3B	3B	大规模语言理解，复杂的推理任务	极高	huggingface-cli download 1bitLLM/bitnet_b1_58-3B --local-dir models/bitnet_b1_58-3B
HF1BitLLM/Llama3-8B-1.58-100B-tokens	8B	大规模数据处理，长文本生成和理解	极高	huggingface-cli download HF1BitLLM/Llama3-8B-1.58-100B-tokens --local-dir models/Llama3-8B-1.58-100B-tokens
tiiuae/Falcon3-1B-Instruct-1.58bit	1B	指令型任务，如问题回答、文本生成	高	huggingface-cli download tiiuae/Falcon3-1B-Instruct-1.58bit --local-dir models/Falcon3-1B-Instruct-1.58bit
tiiuae/Falcon3-3B-Instruct-1.58bit	3B	指令型任务，要求较高的精度	高	huggingface-cli download tiiuae/Falcon3-3B-Instruct-1.58bit --local-dir models/Falcon3-3B-Instruct-1.58bit
tiiuae/Falcon3-7B-Instruct-1.58bit	7B	需要更强推理能力的指令型任务	极高	huggingface-cli download tiiuae/Falcon3-7B-Instruct-1.58bit --local-dir models/Falcon3-7B-Instruct-1.58bit
tiiuae/Falcon3-10B-Instruct-1.58bit	10B	高精度指令型任务，大规模文本生成	极高	huggingface-cli download tiiuae/Falcon3-10B-Instruct-1.58bit --local-dir models/Falcon3-10B-Instruct-1.58bit
microsoft/BitNet-b1.58-2B-4T-gguf	2B	资源受限环境，性能和精度之间的平衡	高	huggingface-cli download microsoft/BitNet-b1.58-2B-4T-gguf --local-dir models/BitNet-b1.58-2B-4T

总结：

• 可以直接在 BitNet 上运行 的模型是 BitNet 系列 的模型（如 bitnet_b1_58-large 和 bitnet_b1_58-3B）以及 microsoft/BitNet-b1.58-2B-4T-gguf 这样的变体。
• 其他模型，如 Llama3 和 Falcon3，虽然可能可以在 BitNet 上运行，但需要额外的适配或转换，具体取决于模型格式、量化方式和框架支持。

五、配置其他更大权重（GPT整理，尚未尝试）

如果你想在 BitNet 上下载并运行一个更高精度的模型，可以选择 BitNet 系列中更大的模型。例如，选择 bitnet_b1_58-large 或 bitnet_b1_58-3B，这些模型具有更大的参数量，因此可以提供更高的精度。

以下是下载和配置这些更高精度模型的完整命令：

1. 下载更大的 BitNet 模型：

选择 bitnet_b1_58-large 或 bitnet_b1_58-3B 作为目标模型。你可以使用 Hugging Face CLI 下载。

下载 bitnet_b1_58-large：

huggingface-cli download 1bitLLM/bitnet_b1_58-large --local-dir models/bitnet_b1_58-large

下载 bitnet_b1_58-3B：

huggingface-cli download 1bitLLM/bitnet_b1_58-3B --local-dir models/bitnet_b1_58-3B

2. 设置 BitNet 环境：

下载完模型后，你需要设置环境，并选择适合的量化方式（例如 i2_s）。以下命令会将模型配置好并进行量化优化。

配置命令：

python setup_env.py -md models/bitnet_b1_58-large -q i2_s

或者对于 bitnet_b1_58-3B 模型：

python setup_env.py -md models/bitnet_b1_58-3B -q i2_s

• -md 选项指定了本地模型路径。
• -q 选项指定了量化方式，i2_s 是一种优化的量化类型，你也可以使用 tl1（具体选择取决于你的硬件和性能需求）。

3. 运行推理：

配置好模型之后，你可以使用 python 来运行推理任务。以下是一个简单的推理示例命令：

python inference.py -m models/bitnet_b1_58-large/ggml-model-i2_s.gguf -p "Your input prompt here" -n 128

或者如果使用 bitnet_b1_58-3B 模型：

python inference.py -m models/bitnet_b1_58-3B/ggml-model-i2_s.gguf -p "Your input prompt here" -n 128

• -m 选项指定了模型文件路径。
• -p 选项是你要输入的提示文本。
• -n 选项指定要生成的 token 数量。

4. 配置日志和输出目录（可选）：

如果你希望指定日志目录或输出目录，可以使用以下命令：

python setup_env.py -md models/bitnet_b1_58-large -q i2_s -ld /path/to/logs

• -ld 选项指定了日志输出目录。

5. 配置更多高级选项（可选）：

如果需要进行预调优或使用其他量化选项，可以在命令中添加更多参数。例如：

• --use-pretuned：使用预调优的内核参数（如果有）。
• --quant-embd：将嵌入量化为 f16。

例如：

python setup_env.py -md models/bitnet_b1_58-large -q i2_s --use-pretuned --quant-embd

总结：

• 选择更大的模型：下载 bitnet_b1_58-large 或 bitnet_b1_58-3B。
• 设置环境并量化优化：使用 setup_env.py 设置模型并选择量化方式。
• 运行推理：使用模型进行推理。

这样，你就可以运行更高精度的 BitNet 模型，并根据需求调整性能和精度。