microsoft/BitNet

이 데모를 통해 직접 체험해 보거나, 사용자의 CPU 또는 GPU에서 직접 빌드하여 실행할 수 있습니다.

bitnet.cpp는 1-bit LLM (예: BitNet b1.58)을 위한 공식 추론 프레임워크 (inference framework)입니다. 이 프레임워크는 CPU 및 GPU에서 1.58-bit 모델의 빠르고 (fast) 손실 없는 (lossless) 추론을 지원하는 최적화된 커널 (kernels) 제품군을 제공합니다 (NPU 지원은 향후 추가될 예정입니다).

bitnet.cpp의 첫 번째 릴리스는 CPU에서의 추론을 지원합니다. bitnet.cpp는 ARM CPU에서 **1.37배 (1.37x)**에서 **5.07배 (5.07x)**의 속도 향상을 달성하며, 모델의 크기가 커질수록 더 큰 성능 이득을 얻습니다. 또한, 에너지 소비를 **55.4%**에서 **70.0%**까지 줄여 전반적인 효율성을 더욱 높입니다. x86 CPU의 경우, 속도 향상은 **2.37배 (2.37x)**에서 6.17배 (6.17x) 사이이며, 에너지 감소는 **71.9%**에서 82.2% 사이입니다. 나아가, bitnet.cpp는 단일 CPU에서 100B 규모의 BitNet b1.58 모델을 실행할 수 있으며, 사람이 읽는 속도(초당 5-7 토큰)와 유사한 속도를 달성하여 로컬 장치에서 LLM을 실행할 수 있는 잠재력을 크게 향상시킵니다. 자세한 내용은 기술 보고서 (technical report)를 참조하십시오.

최신 최적화 (Latest optimization) 단계에서는 구성 가능한 타일링 (tiling) 및 임베딩 양자화 (embedding quantization) 지원을 갖춘 병렬 커널 구현을 도입하여, 다양한 하드웨어 플랫폼과 워크로드에 걸쳐 기존 구현 대비 **1.15배 (1.15x)에서 2.1배 (2.1x)**의 추가 속도 향상을 달성했습니다. 자세한 기술 정보는 최적화 가이드 (optimization guide)를 확인하십시오.

Apple M2에서 BitNet b1.58 3B 모델을 실행하는 bitnet.cpp의 데모:

demo.mp4

• 2026/01/15 BitNet CPU 추론 최적화 (Inference Optimization)
• 2025/05/20 BitNet 공식 GPU 추론 커널 (GPU inference kernel)
• 2025/04/14 Hugging Face의 BitNet 공식 2B 파라미터 모델 (2B Parameter Model)
• 2025/02/18 bitnet.cpp: 삼진 LLM (Ternary LLMs)을 위한 효율적인 엣지 추론 (Efficient Edge Inference)
• 2024/11/08 BitNet a4.8: 1-bit LLM을 위한 4-bit 활성화 함수 (4-bit Activations)
• 2024/10/21 1-bit AI 인프라 (AI Infra): 파트 1.1, CPU에서의 빠르고 손실 없는 BitNet b1.58 추론
• 2024/10/17 bitnet.cpp 1.0 출시
• 2024/03/21 The-Era-of-1-bit-LLMs__Training_Tips_Code_FAQ
• 2024/02/27 1-bit LLM의 시대: 모든 대규모 언어 모델은 1.58 비트이다 (The Era of 1-bit LLMs: All Large Language Models are in 1.58 Bits)
• 2023/10/17 BitNet: 대규모 언어 모델을 위한 1-bit Transformer 스케일링 (Scaling 1-bit Transformers for Large Language Models)

이 프로젝트는 llama.cpp 프레임워크를 기반으로 합니다. 오픈 소스 커뮤니티에 기여해 주신 모든 저자분께 감사드립니다. 또한, bitnet.cpp의 커널은 T-MAC에서 개척한 룩업 테이블 (Lookup Table) 방법론을 기반으로 구축되었습니다. 삼진 모델 (ternary models) 이외의 일반적인 저비트 LLM (low-bit LLMs) 추론을 위해서는 T-MAC 사용을 권장합니다.

모델 (Model)	파라미터 (Parameters)	CPU	커널 (Kernel)
I2_S	TL1	TL2
...
❗️우리는 bitnet.cpp의 추론 능력을 입증하기 위해 Hugging Face에서 사용 가능한 기존 1-bit LLM들을 사용합니다. bitnet.cpp의 출시가 모델 크기와 학습 토큰 (training tokens) 측면에서 대규모 환경의 1-bit LLM 개발에 영감을 주기를 바랍니다.

모델 (Model)	파라미터 (Parameters)	CPU	커널 (Kernel)
I2_S	TL1	TL2
...

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

Windows 사용자의 경우, Visual Studio 2022를 설치하십시오. 설치 프로그램에서 최소한 다음 옵션들을 활성화하십시오 (이는 CMake와 같은 필요한 추가 도구들도 자동으로 설치합니다):

• C++를 사용한 데스크톱 개발 (Desktop-development with C++)

• Windows용 C++-CMake 도구 (C++-CMake Tools for Windows)

• Windows용 Git (Git for Windows)

• Windows용 C++-Clang 컴파일러 (C++-Clang Compiler for Windows)

• LLVM-Toolset (clang)용 MS-Build 지원 (MS-Build Support for LLVM-Toolset (clang))

Debian/Ubuntu 사용자의 경우, 자동 설치 스크립트로 다운로드할 수 있습니다.

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

• conda (강력 권장)

중요 (Important)

Windows를 사용 중이라면, 다음 명령들을 실행할 때 항상 VS2022용 Developer Command Prompt / PowerShell을 사용해야 함을 기억해 주세요. 문제가 발생할 경우 아래의 FAQ를 참조하시기 바랍니다.

• 저장소(repo) 클론 (Clone the repo)

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

• 의존성 설치 (Install the dependencies)

# (권장) 새로운 conda 환경 생성
conda create -n bitnet-cpp python=3.9
conda activate bitnet-cpp
...

• 프로젝트 빌드 (Build the project)

# 모델을 수동으로 다운로드하고 로컬 경로로 실행
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

사용법(usage): setup_env.py [-h] [--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}] [--model-dir MODEL_DIR] [--log-dir LOG_DIR] [--quant-type {i2_s,tl1}] [--quant-embd] [--use-pretuned] 추론(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 {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}: 추론에 사용할 모델
--model-dir MODEL_DIR, -md MODEL_DIR: 모델을 저장/로드할 디렉토리
--log-dir LOG_DIR, -ld LOG_DIR: 로깅 정보를 저장할 디렉토리
--quant-type {i2_s,tl1}, -q {i2_s,tl1}: 양자화(Quantization) 유형
--quant-embd: 임베딩(embeddings)을 f16으로 양자화
--use-pretuned, -p: 사전 조정된(pretuned) 커널 파라미터 사용

# 양자화된 모델로 추론(inference) 실행
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] 추론 실행
선택적 인자(optional arguments):
-h, --help: 이 도움말 메시지를 보여주고 종료
-m MODEL, --model MODEL: 모델 파일 경로
-n N_PREDICT, --n-predict N_PREDICT: 텍스트 생성 시 예측할 토큰(tokens) 수
-p PROMPT, --prompt PROMPT: 텍스트를 생성할 프롬프트(prompt)
-t THREADS, --threads THREADS: 사용할 스레드(threads) 수
-c CTX_SIZE, --ctx-size CTX_SIZE: 프롬프트 컨텍스트(context) 크기
-temp TEMPERATURE, --temperature TEMPERATURE: 온도(Temperature), 생성된 텍스트의 무작위성을 제어하는 하이퍼파라미터(hyperparameter)
-cnv, --conversation: 채팅 모드 활성화 여부 (지시 모델(instruct models)용). (이 옵션이 켜지면, -p로 지정된 프롬프트가 시스템 프롬프트(system prompt)로 사용됩니다.)

모델을 제공하여 추론 벤치마크(inference benchmark)를 실행하기 위한 스크립트를 제공합니다.

사용법: e2e_benchmark.py -m MODEL [-n N_TOKEN] [-p N_PROMPT] [-t THREADS]
추론 실행을 위한 환경 설정
필수 인자(required arguments):
...

각 인자에 대한 간략한 설명은 다음과 같습니다:

-m, --model: 모델 파일의 경로입니다. 스크립트를 실행할 때 반드시 제공해야 하는 필수 인자입니다.

-n, --n-token: 추론 중에 생성할 토큰(tokens)의 수입니다. 기본값이 128인 선택적 인자입니다.

-p, --n-prompt: 텍스트 생성을 위해 사용할 프롬프트 토큰(prompt tokens)의 수입니다. 기본값이 512인 선택적 인자입니다.

-t, --threads: 추론 실행에 사용할 스레드(threads) 수입니다. 기본값이 2인 선택적 인자입니다.

-h, --help: 도움말 메시지를 보여주고 종료합니다. 사용법 정보를 표시하려면 이 인자를 사용하세요.

예시:

python utils/e2e_benchmark.py -m /path/to/model -n 200 -p 256 -t 4

이 명령은 /path/to/model에 위치한 모델을 사용하여 추론 벤치마크 (inference benchmark)를 실행하며, 256 토큰의 프롬프트 (prompt)로부터 200개의 토큰을 생성하고 4개의 스레드 (threads)를 사용합니다.

공개된 모델 중 지원되지 않는 모델 레이아웃 (model layout)의 경우, 주어진 모델 레이아웃으로 더미 모델 (dummy model)을 생성하고 사용자의 기기에서 벤치마크를 실행할 수 있는 스크립트를 제공합니다:

python utils/generate-dummy-bitnet-model.py models/bitnet_b1_58-large --outfile models/dummy-bitnet-125m.tl1.gguf --outtype tl1 --model-size 125M
# 생성된 모델로 벤치마크를 실행합니다. 모델 경로를 지정하려면 -m을, 처리할 프롬프트를 지정하려면 -p를, 생성할 토큰 수를 지정하려면 -n을 사용하세요.
python utils/e2e_benchmark.py -m models/dummy-bitnet-125m.tl1.gguf -p 512 -n 128

# .safetensors 모델 파일 준비
huggingface-cli download microsoft/bitnet-b1.58-2B-4T-bf16 --local-dir ./models/bitnet-b1.58-2B-4T-bf16
# gguf 모델로 변환
...

A:
이는 최근 버전의 llama.cpp에서 발생한 이슈입니다. 이 문제를 해결하려면 토론 (discussion)에 있는 이 커밋 (commit)을 참조하십시오.

A:
프로젝트를 빌드 (build)하기 전에, 다음을 실행하여 clang 설치 상태와 Visual Studio 도구에 대한 접근 권한을 확인하십시오:

clang -v

이 명령은 올바른 버전의 clang을 사용하고 있는지, 그리고 Visual Studio 도구를 사용할 수 있는지 확인합니다. 만약 다음과 같은 오류 메시지가 나타난다면:

'clang' is not recognized as an internal or external command, operable program or batch file.

이는 명령줄 창 (command line window)이 Visual Studio 도구에 대해 제대로 초기화되지 않았음을 나타냅니다.

• 명령 프롬프트 (Command Prompt)를 사용하는 경우:

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

• Windows 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"

이 단계들은 환경을 초기화하여 올바른 Visual Studio 도구들을 사용할 수 있도록 해줍니다.