快速入门

相关源文件

• .gitmodules
• CMakeLists.txt
• README.md

本指南提供了设置和运行 BitNet.cpp 的说明，BitNet.cpp 是一个用于 1 位（三元）大型语言模型的专用推理框架。有关 BitNet.cpp 及其功能的更全面概述，请参阅BitNet.cpp 概述。

BitNet.cpp 通过针对不同硬件平台优化的内核，实现三元模型的高效推理。本文档涵盖了安装过程、基本用法和初始配置步骤。

先决条件

在设置 BitNet.cpp 之前，请确保您的系统满足以下要求：

要求	最低版本
Python	3.9 或更高版本
CMake	3.22 或更高版本
Clang	18 或更高版本
Conda	推荐要求

平台特定要求

对于 Windows 用户

• 安装 Visual Studio 2022 并包含以下组件：
  • 使用 C++ 进行桌面开发
  • 适用于 Windows 的 C++ CMake 工具
  • 适用于 Windows 的 Git
  • 适用于 Windows 的 C++ Clang 编译器
  • MS-Build 对 LLVM-Toolset (clang) 的支持

对于 Debian/Ubuntu 用户

• 使用自动安装脚本安装 Clang：

来源：README.md145-158

安装过程

BitNet.cpp 的安装涉及以下步骤：

1. 克隆仓库

1. 克隆 BitNet 仓库及其子模块（包括 llama.cpp）

来源：README.md166-169 .gitmodules1-4

2. 设置环境

建议使用 conda 环境：

来源：README.md170-177

3. 下载并准备模型

您有两种方法获取用于推理的模型：

选项 1：从 Hugging Face 下载预构建的 GGUF 模型

选项 2：使用 setup_env.py 从 Hugging Face 下载并转换模型

setup_env.py 脚本处理：

1. 从 Hugging Face 下载模型
2. 将模型转换为 GGUF 格式
3. 为您的平台生成优化的内核代码
4. 构建 C++ 代码

来源：README.md178-184

setup_env.py 的可用命令行参数

参数	短期	描述	选项
--hf-repo	-hr	Hugging Face 上的模型仓库	支持的各种模型
--model-dir	-md	保存/加载模型的目录	自定义路径
--log-dir	-ld	日志信息目录	自定义路径
--quant-type	-q	量化类型	i2_s, tl1
--quant-embd	-	将嵌入量化为 f16	标志
--use-pretuned	-p	使用预调优的内核参数	标志

来源：README.md185-203

基本用法

运行推理

设置完成后，您可以使用 run_inference.py 脚本运行推理：

此命令将

1. 加载量化模型 (-m)
2. 设置提示词 (-p)
3. 启用对话模式 (-cnv)

来源：README.md206-209

run_inference.py 的命令行参数

参数	短期	描述	默认
--model	-m	模型文件路径	必填
--n-predict	-n	预测的令牌数量	默认值不同
--prompt	-p	用于生成文本的提示词	必填
--threads	-t	使用的线程数	默认值不同
--ctx-size	-c	提示上下文大小	默认值不同
--temperature	-temp	控制生成文本的随机性	默认值不同
--conversation	-cnv	启用聊天模式（用于指令模型）	标志

来源：README.md210-231

基准测试

要评估 BitNet.cpp 在您的模型上的性能，请使用提供的基准测试脚本：

此命令将

1. 使用指定的模型 (-m)
2. 处理 512 个令牌的提示词 (-p)
3. 生成 128 个令牌 (-n)

来源：README.md233-279

支持的模型

BitNet.cpp 官方支持以下模型

模型	大小	支持 ARM	支持 x86
BitNet-b1.58-2B-4T	2.4B	✓ (TL1, I2_S)	✓ (TL2, I2_S)
bitnet_b1_58-large	0.7B	✓ (TL1, I2_S)	✓ (TL2, I2_S)
bitnet_b1_58-3B	3.3B	✓ (TL1)	✓ (TL2)
Llama3-8B-1.58	8.0B	✓ (TL1, I2_S)	✓ (TL2, I2_S)
Falcon3 系列	1B-10B	✓ (TL1, I2_S)	✓ (TL2, I2_S)

来源：README.md37-139

故障排除

问题：llama.cpp 由于 log.cpp 中的 std::chrono 导致构建错误

这是 llama.cpp 近期版本中的一个问题。请参考此commit 获取修复。

问题：Windows 中无法识别 Clang

确保您使用的是正确的 Visual Studio 开发者命令提示符。要初始化它：

对于命令提示符 (Command Prompt)

"C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\Tools\VsDevCmd.bat" -startdir=none -arch=x64 -host_arch=x64

对于 PowerShell

Import-Module "C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\Tools\Microsoft.VisualStudio.DevShell.dll" 
Enter-VsDevShell 3f0e31ad -SkipAutomaticLocation -DevCmdArguments "-arch=x64 -host_arch=x64"

来源：README.md280-313

下一步

有关以下内容的更多详细信息：

• 设置特定环境，请参阅环境设置
• 为推理准备不同模型，请参阅模型准备
• 推理选项的综合指南，请参阅运行推理

来源：README.md204-231 CMakeLists.txt1-77