本文档提供了设置 BitNet.cpp 环境的详细说明，该环境用于准备运行三元（1比特）大型语言模型推理所需的组件。设置过程包括下载模型、生成优化内核以及构建推理所需的执行组件。有关设置后实际运行模型的信息，请参阅运行推理。
环境设置过程由setup_env.py脚本管理，该脚本协调以下几项关键任务
该脚本会自动检测您的硬件架构（ARM64 或 x86_64），并相应地配置构建过程，生成适当的内核优化（ARM 为 TL1，x86 为 TL2）。
图 1：环境设置工作流程
来源： setup_env.py206-210 README.md142-202
在运行设置脚本之前，请确保您的系统满足以下要求
| 要求 | 最低版本 | 备注 |
|---|---|---|
| Python | 3.9+ | 运行设置脚本所需 |
| CMake | 3.22+ | 构建 C++ 代码所需 |
| Clang | 18+ | 所需编译器 |
| Conda | 任何最新版本 | 推荐用于环境管理 |
对于 Windows 用户，设置需要安装带有特定组件的 Visual Studio 2022
来源： README.md144-159
图 2：设置过程序列
来源： setup_env.py97-139 setup_env.py190-204 setup_env.py144-188
setup_env.py 脚本接受多个命令行参数以自定义设置过程
| 参数 | 短格式 | 描述 | 默认 | 选项 |
|---|---|---|---|---|
--hf-repo | -hr | 要下载的 Hugging Face 仓库 | 无 | 请参阅下面支持的模型 |
--model-dir | -md | 保存/加载模型的目录 | "models" | 任何有效的目录路径 |
--log-dir | -ld | 日志信息目录 | "logs" | 任何有效的目录路径 |
--quant-type | -q | 量化类型 | "i2_s" | "i2_s"、"tl1" （ARM） 或 "tl2" （x86） |
--quant-embd | 不适用 | 将嵌入量化为 f16 | 否 | 标志（无需值） |
--use-pretuned | -p | 使用预调优的内核参数 | 否 | 标志（无需值） |
BitNet.cpp 支持多种三元（1比特）模型。官方模型是 BitNet-b1.58-2B-4T，但该框架兼容其他多种模型
| 模型 | 参数 | 架构支持 |
|---|---|---|
| BitNet-b1.58-2B-4T | 2.4B | ARM (TL1), x86 (TL2) |
| bitnet_b1_58-large | 0.7B | ARM (TL1), x86 (TL2) |
| bitnet_b1_58-3B | 3.3B | ARM (TL1), x86 (TL2) |
| Llama3-8B-1.58-100B-tokens | 8.0B | ARM (TL1), x86 (TL2) |
| Falcon3 系列 | 1B-10B | ARM (TL1), x86 (TL2) |
来源： README.md37-139 setup_env.py13-47
模型准备过程包括下载模型（如果需要）并将其转换为具有适当量化的 GGUF 格式。
图 3：模型准备过程
BitNet.cpp 为您的特定硬件平台和模型生成优化内核
图 4：内核生成过程
构建过程使用 CMake 编译 BitNet.cpp 代码，并进行平台特定优化
图 5：构建过程
来源： README.md179-182
如果在设置过程中遇到问题，请检查logs目录中的日志文件。常见问题包括
对于遇到编译器问题的 Windows 用户，请确保您使用的是要求部分中提到的 Visual Studio 2022 的开发人员命令提示符/PowerShell。
来源： README.md162-164 README.md282-312
成功设置环境后，您可以继续使用准备好的模型运行推理。请参阅运行推理，了解如何使用run_inference.py脚本与您准备好的模型的详细说明。
来源： README.md204-231