BitNet 설치 가이드
BitNet(비트넷)은 2025/4/12 (미국 시간) 마이크로소프트가 오픈소스로 발표한 소위 "1비트 LLM"입니다.
비트넷 의의
지금까지 로컬에서 구동 가능한 LLM이라고 말할 때, "로컬"은 H100 GPU, 맥북 프로, RTX 3090 정도를 보유한 로컬이었습니다. 그런데 비트넷은 일반 CPU (노트북 또는 PC에 탑재한 인텔 13세대 CPU 등)에서 사용할 수 있는 LLM을 오픈소스로 제공합니다. GPU도 필요없고 맥북 프로도 필요 없습니다. Windows OS를 탑재한 LG 그램같은 노트북에서도 LLM을 돌릴 수 있습니다.
- 논문 환경
- CPU: Intel Core i7-13700H processor (14 cores, 20 threads)
- RAM: 64GB
이 설치 가이드를 작성하는 이유
저는 테크라이팅 또는 개인 개발 프로젝트에서 쓰기 위한 로컬 LLM을 찾고 있습니다. OpenAI 또는 Gemini API 호출이 필요 없고 아주 저사양 PC에서 돌릴 수 있는 로컬 LLM을 찾고 있던 중, 비트넷을 발견하고 한 번 설치해보았습니다.
여러 오픈 소스 프로젝트 README.md는 불친절하거나, 오류가 있거나, 누락된 내용이 다소 존재합니다. 이번에도 마찬가지였고, BitNet Github README.md를 보고 삽질한 내용을 공유해 다른 사람들이 더 쉽게 설치할 수 있으면 좋겠다는 생각이 들어 작성합니다.
테크라이터이지만 이 블로그는 대충 쓰려고 하니 글에 여러 문제가 있더라도 너그러히 넘어가주세요.
Note
이 글은 2025-04-25 기준으로 작성한 글입니다. 현 시점 이후 BitNet과 서브 모듈 업데이트 여부에 따라 현재 안내한 설치 방법이 작동하지 않거나, 일부 설치 과정을 생략해야할 수도 있습니다.
설치 환경
아래 환경에서 설치, 구동에 성공했습니다. 그래서 아래 환경 기준으로만 안내합니다.
- 플랫폼: 노트북(LG 그램)
- CPU: Intel® Core™ i7-1360P Processor (12 cores, 16 threads)
- RAM: 32GB
- OS: Windows 11 Pro, 64bit
- 사용한 터미널: Visual Studio Code의 Powershell 터미널
설치 방법
Visual Studio Code(VSC), Anaconda(콘다) 모두 설치되어 있지 않다고 가정하고 안내합니다.
1. VSC와 콘다 설치
저는 미니 콘다 말고 아나콘다 정식 버전 설치했습니다. 설치 시 콘다를 환경 변수(PATH)에 등록 안 해도 됩니다.
2. Visual Studio 2022 설치 (커뮤니티 버전 기준)
프로페셔널을 설치해도 괜찮습니다. 아래 모든 내용에서 Visual Studio 2022 설치 경로만 프로페셔널 버전 설치 경로로 변경하면 됩니다. 주의할 점은 Visual Studio 2022 인스톨러 UI에서 아래 모듈을 반드시 같이 설치해야 한다는 점입니다.
- Desktop-development with C++
- C++-CMake Tools for Windows
- Git for Windows
- C++-Clang Compiler for Windows
- MS-Build Support for LLVM-Toolset (clang)
3. Clone repository
4. CMake kit 선택
VSC에서 Ctrl + Shift + P 누르고 CMake: Select a Kit: Clang 19.1.1 (MSVC CLI) - x86 for MSVC 17.x.x 선택합니다. 선택하면 build VSC 빌드 설정 진행하면서 src/CMakeLists.txt에서 발생하던 이슈 사라집니다.
5. 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
6. Python interpreter 변경
VSC에서 Ctrl + Shift + P 누르고 Select Interpreter for Python: bitnet-cpp로 Python interpreter 변경합니다.
변경 후 콘다 가상 환경이 잘 활성화되었는지 확인합니다.
아래와 같이 bitnet-cpp 가상 환경이 활성화되어 있어야 합니다.
7. Build the project
huggingface-cli download microsoft/BitNet-b1.58-2B-4T-gguf --local-dir models/BitNet-b1.58-2B-4T
Import-Module "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
Enter-VsDevShell -SkipAutomaticLocation -DevCmdArguments "-arch=x64 -host_arch=x64"
겨우 2B 모델 써봤자 무쓸모라고 판단되시면 huggingface-cli 커맨드에서 모델명 다른 거로 바꾸셔도 됩니다만, 여기선 2B 모델로 안내합니다.
8. clang -v 체크
대충 아래와 같이 나타나야합니다.
clang version 19.1.1
Target: x86_64-pc-windows-msvc
Thread model: posix
InstalledDir: C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm\x64\bin
9. 서브모듈 업데이트 & 디버깅
서브모듈로 사용중인 써드파티 도구인 llama.cpp에 버그가 있으므로 이를 고쳐줍니다. 누가 빨리 PR좀 올려주면 좋겠네요. 깃헙 이슈보면 고쳤다고 누가 써놨는데 아직 에러납니다. 일단 서브모듈 최신으로 업데이트합니다.
그리고 다음 파일에
#include <chrono> 추가합니다.
- 3rdparty\llama.cpp\common\common.cpp
- 3rdparty\llama.cpp\common\log.cpp
- 3rdparty\llama.cpp\examples\imatrix\imatrix.cpp
- 3rdparty\llama.cpp\examples\imatrix\imatrix.cpp
- 3rdparty\llama.cpp\examples\perplexity\perplexity.cpp
10. 빌드
빌드 메시지에 ERROR 없으면 잘 된 것입니다.
11. 대화 모드로 실행
python run_inference.py -m models/BitNet-b1.58-2B-4T/ggml-model-i2_s.gguf -p "You are a helpful assistant" -cnv
후기
쓸 만한 지 아닌지는 Llama3-8B-1.58-100B-tokens를 받아서 테스트해봐야 할 것 같습니다. 다음에는 노트북용 RTX 4060에서도 돌아가게 만들었다는 Gemma 3 QAT를 테스트해볼 예정입니다.