编译BitNet.cpp并部署BitNet 2B4T模型的实践

关于BitNet模型

BitNet 是微软研究院提出的一种极致量化技术，将大语言模型的权重量化到 1.58-bit （三值：-1, 0, +1），相比传统的 16-bit 浮点数，模型大小减少了 10 倍以上，同时保持了相当的性能。BitNet 代表了大语言模型量化的极致探索，将 2B 参数的模型压缩到 1.1GB，同时保持了实用的推理性能。通过部署可以在普通 CPU 服务器上运行一个生产级的 LLM 服务，无需昂贵的 GPU 硬件。

传统量化方法对比如下。三值表示需要 log₂(3) ≈ 1.58 bit 的信息熵。相比 2-bit（四值），1.58-bit 减少了一个状态，简化了计算逻辑。

量化方式	位宽	表示范围	模型大小 (2B参数)	典型应用
FP16	16-bit	连续浮点数	~4GB	训练、高精度推理
INT8	8-bit	-128~127	~2GB	通用量化推理
INT4	4-bit	-8~7	~1GB	llama.cpp Q4 量化
BitNet 1.58-bit	1.58-bit	{-1, 0, +1}	~1.1GB	极致压缩推理

BitNt 2B-4T 和3B 的模型对比如下，2B-4T 虽然参数更少（2.41B vs 3B），但训练数据更多（4T tokens），质量更好，且是 2025 年发布的生产就绪版本。

特性	BitNet 3B	BitNet 2B-4T
发布时间	2024年2-3月	2025年4月
参数量	3B	2.41B
训练数据	未公开	4T tokens
定位	研究模型	生产就绪
质量	基准	更优（数据量大）

本次测试环境的机器为t3.xlarge， amazonlinux 2023

受限安装编译工具

# 安装 clang 编译器
sudo yum install -y clang
# 安装 cmake
sudo yum install -y cmake

初始化 Python 环境

# 初始化 uv 项目
uv init
# 安装必要的 Python 包
uv add transformers torch modelscope

下载 GGUF 格式模型。GGUF (GPT-Generated Unified Format) 是 llama.cpp 使用的模型格式，说明如下

• i2_s：2-bit 对称量化（BitNet 1.58-bit 的存储格式）
• 单文件：所有权重、配置、分词器打包在一个文件中
• 高效加载：支持 mmap，内存占用小
• 跨平台：CPU、GPU 通用

import os
from modelscope import snapshot_download

def main():
    model_id = "AI-ModelScope/bitnet-b1.58-2B-4T-gguf"
    output_dir = "./models/bitnet-2b4t-gguf"
    
    print(f"下载模型: {model_id}")
    print(f"保存到: {output_dir}")
    
    os.makedirs(output_dir, exist_ok=True)
    
    model_path = snapshot_download(
        model_id=model_id,
        cache_dir=output_dir,
        revision='master'
    )

if __name__ == "__main__":
    main()

---

编译 BitNet.cpp

BitNet.cpp 是 BitNet 的官方推理引擎，基于 llama.cpp 扩展。在 llama.cpp 基础上添加 1.58-bit 量化支持，并针对三值权重的位运算和查找表优化

# 克隆 BitNet.cpp（包含子模块）
git clone --recursive https://github.com/microsoft/BitNet.git bitnet.cpp
cd bitnet.cpp

# 如果忘记 --recursive，手动初始化子模块
git submodule update --init --recursive

创建编译脚本

# 1. 安装 gguf-py
gguf_path="bitnet.cpp/3rdparty/llama.cpp/gguf-py"
uv pip install -e "$gguf_path"

# 2. CMake 配置和编译
cd bitnet.cpp
cmake -B build \
    -DBITNET_X86_TL2=OFF \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_C_COMPILER=clang \
    -DCMAKE_CXX_COMPILER=clang++

cmake --build build --config Release -j 4

编译完成后，bitnet.cpp/build/bin/ 目录包含：

llama-cli          # 命令行推理工具
llama-server       # HTTP API 服务器
llama-quantize     # 模型量化工具
llama-bench        # 性能测试工具

创建简单的推理脚本 run_bitnet.sh：

MODEL_PATH="./models/bitnet-2b4t-gguf/AI-ModelScope/bitnet-b1___58-2B-4T-gguf/ggml-model-i2_s.gguf"
BITNET_CLI="./bitnet.cpp/build/bin/llama-cli"

# 默认参数
PROMPT="${1:-Hello, how are you?}"
MAX_TOKENS="${2:-256}"
THREADS="${3:-4}"

# 运行推理
$BITNET_CLI \
    -m "$MODEL_PATH" \
    -p "$PROMPT" \
    -n "$MAX_TOKENS" \
    -t "$THREADS" \
    -ngl 0

运行测试：

bash run_bitnet.sh "What is artificial intelligence?"

llama_model_load: loaded meta data with 24 key-value pairs
llama_model_load: n_vocab    = 128256
llama_model_load: n_ctx      = 4096
llama_model_load: n_embd     = 2560
llama_model_load: n_layer    = 30
llama_model_load: n_head     = 32
llama_model_load: n_params   = 2.41B

What is artificial intelligence?

Artificial Intelligence (AI) refers to the simulation of human 
intelligence in machines that are programmed to think and learn 
like humans. AI systems can perform tasks such as visual perception, 
speech recognition, decision-making, and language translation.

The field of AI research was founded on the claim that human 
intelligence can be so precisely described that a machine can be 
made to simulate it. This includes learning, reasoning, problem-solving, 
perception, and language understanding.

llama_perf_context_print:        load time =     523.45 ms
llama_perf_context_print: prompt eval time =     177.77 ms /     5 tokens
llama_perf_context_print:        eval time =    8749.48 ms /   100 tokens
llama_perf_context_print:       total time =    9450.70 ms

推理速度: 11.43 tokens/second

prompt eval time: 177.77 ms / 5 tokens
  - 提示词处理时间：35.55 ms/token
  - 速度：28.13 tokens/second

eval time: 8749.48 ms / 100 tokens
  - 生成时间：87.49 ms/token
  - 速度：11.43 tokens/second

total time: 9450.70 ms
  - 总耗时：9.45 秒

还可以通过类似 vLLM、OpenAI API 的部署方式启动服务，以兼容 OpenAI API 格式并提供如下功能

• 支持多个请求同时处理
• 任何语言都可以通过 HTTP 调用
• 支持流式输出、健康检查、指标监控

创建启动脚本 start_bitnet_server.sh：

#!/bin/bash
# BitNet 2B-4T HTTP API 服务器

MODEL_PATH="./models/bitnet-2b4t-gguf/AI-ModelScope/bitnet-b1___58-2B-4T-gguf/ggml-model-i2_s.gguf"
BITNET_SERVER="./bitnet.cpp/build/bin/llama-server"

# 配置参数
HOST="${HOST:-0.0.0.0}"
PORT="${PORT:-8080}"
THREADS="${THREADS:-4}"
CTX_SIZE="${CTX_SIZE:-4096}"
N_PARALLEL="${N_PARALLEL:-4}"

echo "BitNet 2B-4T HTTP API 服务器"
echo "API 端点:"
echo "  POST http://localhost:${PORT}/v1/chat/completions"
echo "  POST http://localhost:${PORT}/v1/completions"
echo "  GET  http://localhost:${PORT}/health"

# 启动服务器
$BITNET_SERVER \
    --model "$MODEL_PATH" \
    --host "$HOST" \
    --port "$PORT" \
    --threads "$THREADS" \
    --ctx-size "$CTX_SIZE" \
    --parallel "$N_PARALLEL" \
    --metrics

使用测试脚本如下，此外BitNet 服务器完全兼容 OpenAI Python SDK，并且支持流式输出

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello 你是什么模型"}
    ],
    "max_tokens": 50
  }'

output：
{"choices":[{"finish_reason":"stop","index":0,"message":{"content":"Hi there! How can I assist you today?","role":"assistant"}}],"created":1771307637,"model":"gpt-3.5-turbo-0613","object":"chat.completion","usage":{"completion_tokens":11,"prompt_tokens":8,"total_tokens":19},"id":"chatcmpl-vBnBXMAWpLFAG5HuVFhC8A22Qp3FLLqS"}

从服务器日志中可以看到详细的性能指标：

• 提示词处理：44.97 tokens/s（并行处理）
• 生成速度：11.96 tokens/s（自回归生成）
• 总耗时：13 秒生成 150 tokens
• 延迟：首 token 延迟 ~467ms

slot print_timing: id 0 | task 101 | 
prompt eval time =     466.93 ms /    21 tokens (   22.23 ms per token,    44.97 tokens per second)
       eval time =   12539.27 ms /   150 tokens (   83.60 ms per token,    11.96 tokens per second)
      total time =   13006.20 ms /   171 tokens

构建docker镜像

直接复制已编译的二进制文件和模型

FROM amazonlinux:2023

WORKDIR /app

# 安装运行时依赖
RUN yum update -y && \
    yum install -y libstdc++ libomp && \
    yum clean all && \
    rm -rf /var/cache/yum

# 复制已编译的二进制文件
COPY bitnet.cpp/build/bin/llama-server /app/bin/llama-server
COPY bitnet.cpp/build/bin/llama-cli /app/bin/llama-cli

# 复制共享库
COPY bitnet.cpp/build/3rdparty/llama.cpp/ggml/src/libggml.so /usr/lib64/libggml.so
COPY bitnet.cpp/build/3rdparty/llama.cpp/src/libllama.so /usr/lib64/libllama.so

# 复制模型文件
COPY models/bitnet-2b4t-gguf/AI-ModelScope/bitnet-b1___58-2B-4T-gguf/ggml-model-i2_s.gguf/app/models/ggml-model-i2_s.gguf

# 复制启动脚本，即使用/app/bin/llama-server启动服务
COPY start-bitnet.sh /app/start.sh
RUN chmod +x /app/start.sh

EXPOSE 8080

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# 环境变量
ENV MODEL_PATH=/app/models/ggml-model-i2_s.gguf
ENV HOST=0.0.0.0
ENV PORT=8080
ENV THREADS=4
ENV CTX_SIZE=4096
ENV N_PARALLEL=4

# 启动服务
CMD ["/app/start.sh"]

构建镜像

# 构建镜像
docker build -f Dockerfile.simple -t bitnet-2b4t:latest .

# 查看镜像
docker images bitnet-2b4t:latest

基本运行

# 启动容器
docker run -d \
    --name bitnet \
    -p 8080:8080 \
    bitnet-2b4t:latest

# 查看日志
docker logs -f bitnet