Transformers 로컬 LLM 4bit 양자화 - bitsandbytes 오류 해결

로컬 PC나 온프레미스 서버에서 Hugging Face Transformers로 LLM을 4bit로 양자화해 띄우면, 생각보다 모델보다 환경에서 더 많이 막힙니다. 특히 bitsandbytes는 CUDA 런타임, 드라이버, PyTorch 빌드, GLIBC, 심지어 CPU 아키텍처까지 여러 축에 걸쳐 민감해서 에러 메시지 하나만 보고는 원인을 놓치기 쉽습니다.

이 글은 transformers + bitsandbytes 4bit 로딩을 목표로, 자주 만나는 오류를 “증상 → 원인 → 해결 → 검증” 순서로 정리합니다. (로컬 Linux 기준, Windows는 WSL2를 권장합니다.)

4bit 양자화 로딩의 기본 형태

먼저 정상 동작하는 최소 예제를 기준점으로 잡아두면, 이후 문제를 분리하기 쉽습니다.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

model_id = "meta-llama/Llama-2-7b-chat-hf"  # 예시

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
)

tok = AutoTokenizer.from_pretrained(model_id, use_fast=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    quantization_config=bnb_config,
)

inputs = tok("Hello", return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=30)
print(tok.decode(out[0], skip_special_tokens=True))

여기서 실패한다면, 대부분은 코드 문제가 아니라 아래 중 하나입니다.

bitsandbytes가 GPU용 바이너리를 못 찾음
PyTorch CUDA 버전과 시스템 CUDA 런타임 불일치
libstdc++, glibc 같은 시스템 라이브러리 버전 이슈
GPU가 너무 구형이거나 드라이버가 낮음
CPU only 환경에서 4bit를 GPU처럼 쓰려는 설정

먼저 확인할 5가지 체크리스트

에러를 보기 전에, 아래를 한 번에 수집해두면 원인 추적이 빨라집니다.

python -V
python -c "import torch; print('torch', torch.__version__); print('cuda', torch.version.cuda); print('is_available', torch.cuda.is_available()); print('device', torch.cuda.get_device_name(0) if torch.cuda.is_available() else None)"

nvidia-smi

python -c "import transformers; print(transformers.__version__)"
python -c "import bitsandbytes as bnb; print(bnb.__version__)"

ldd --version | head -n 1

torch.version.cuda는 “PyTorch가 어떤 CUDA로 빌드됐는지”입니다.
nvidia-smi는 “드라이버가 제공하는 CUDA 호환” 관점입니다.
ldd는 GLIBC 버전(리눅스 배포판 노후 여부)을 빠르게 보여줍니다.

오류 1: `CUDA Setup failed despite GPU being available`

대표 증상

torch.cuda.is_available()는 True인데, 로딩 시 bitsandbytes가 CUDA setup 실패
로그에 CUDA Setup failed 또는 could not load bitsandbytes CUDA extension 류

흔한 원인

bitsandbytes가 기대하는 CUDA 바이너리와 PyTorch CUDA 버전이 어긋남
LD_LIBRARY_PATH에 엉뚱한 libcuda.so 혹은 libcudart.so가 잡힘
컨테이너/서버에서 드라이버는 있는데 런타임 라이브러리가 누락

해결 방법 A: PyTorch CUDA 빌드에 맞춰 재설치

가장 안전한 방향은 “PyTorch CUDA 버전과 호환되는 조합”으로 맞추는 겁니다.

예를 들어 PyTorch가 CUDA 12.1 빌드라면:

pip uninstall -y bitsandbytes
pip install -U bitsandbytes

만약 PyTorch 자체가 CPU 빌드라면(매우 흔함):

python -c "import torch; print(torch.version.cuda)"  # None 이면 CPU 빌드

이 경우는 bitsandbytes가 아니라 PyTorch를 CUDA 빌드로 바꿔야 합니다.

pip uninstall -y torch torchvision torchaudio
# 예시: CUDA 12.1
pip install --index-url https://download.pytorch.org/whl/cu121 torch torchvision torchaudio

해결 방법 B: 라이브러리 로딩 경로 충돌 제거

서버에 여러 CUDA가 깔려 있거나, conda가 libstdc++를 끌고 오면서 깨지는 경우가 있습니다.

LD_LIBRARY_PATH를 과하게 설정해둔 경우 일단 최소화
conda 환경이면 conda deactivate 후 시스템 파이썬으로 재현해보기

검증은 bitsandbytes 자체 진단을 돌리는 게 빠릅니다.

python -m bitsandbytes

여기서 어떤 libcudart.so를 찾았는지, 어떤 CUDA extension을 로드하려다 실패했는지 힌트를 줍니다.

오류 2: `undefined symbol` 또는 `GLIBCXX_... not found`

대표 증상

ImportError: ... undefined symbol: ...
GLIBCXX_3.4.xx not found 또는 CXXABI_... not found

원인

대부분 C++ 런타임(libstdc++) 버전이 낮거나, conda가 오래된 런타임을 우선 로딩해서 발생합니다. 특히 오래된 Ubuntu, CentOS 계열에서 자주 터집니다.

해결 방법

conda 환경이면 우선 conda의 libstdc++가 문제인지 확인

python -c "import sys; print(sys.prefix)"
python -c "import ctypes; import os; print(os.environ.get('LD_LIBRARY_PATH'))"

conda를 쓴다면 아래처럼 런타임을 올리는 방식이 비교적 안전합니다.

conda install -c conda-forge libstdcxx-ng

OS가 너무 구형이면, 가장 확실한 해결은 더 최신 배포판/컨테이너로 옮기는 겁니다.

호스트가 구형이면 nvidia-container-toolkit 기반으로 최신 CUDA 이미지 사용
또는 최소한 GLIBC가 충분히 높은 환경으로 이동

이 문제는 “코드로 해결”이 거의 불가능하고, 환경을 바꾸는 게 정답인 경우가 많습니다.

오류 3: `RuntimeError: CUDA error: no kernel image is available for execution on the device`

대표 증상

모델 로딩 또는 첫 연산에서 커널 이미지 불가

원인

GPU 아키텍처가 너무 구형이라, 설치된 PyTorch 또는 bitsandbytes 바이너리가 해당 compute capability를 포함하지 않는 경우입니다.

예:

오래된 Tesla, GTX 10xx 일부, 모바일 GPU 등

해결 방법

가능한 경우: 더 낮은 CUDA/PyTorch 조합으로 내리거나, 해당 아키텍처를 포함한 빌드 사용
현실적으로는: GPU 업그레이드 또는 CPU/다른 백엔드 사용 고려

대안으로는 llama.cpp 계열(GGUF)로 우회하는 방법이 있습니다. PyTorch 체크포인트를 GGUF로 바꾸는 과정에서 막히는 경우는 아래 글이 도움이 됩니다.

PyTorch→GGUF 변환 실패 - 양자화·텐서명 해결

오류 4: `bitsandbytes was compiled without GPU support`

대표 증상

import는 되는데, GPU 기능이 없다고 나옴
4bit 로딩 시 CPU fallback 또는 즉시 실패

원인

CPU 전용 wheel이 설치됨
플랫폼/파이썬 버전 조합 때문에 GPU wheel을 못 받아옴

해결 방법

파이썬 버전을 너무 최신으로 올려서 wheel이 아직 없는 경우가 있습니다. 이때는 Python을 한 단계 내리는 게 해결이 될 수 있습니다.
pip가 오래되면 적절한 wheel 선택을 못하는 경우가 있으니 업데이트합니다.

pip install -U pip setuptools wheel
pip install -U bitsandbytes

그래도 안 되면, 아예 uv 같은 도구로 깨끗한 venv를 만들고 재설치해 “환경 오염”을 제거하는 게 빠릅니다.

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install transformers accelerate bitsandbytes

오류 5: `ValueError: You can't pass load_in_4bit ...` 또는 설정 충돌

대표 증상

load_in_4bit=True와 quantization_config를 같이 줬더니 충돌
device_map 관련 경고/에러

원인

Transformers 버전에 따라 4bit 옵션 전달 방식이 변했습니다. 요즘 권장 방식은 BitsAndBytesConfig를 만들어 quantization_config로 넘기는 것입니다.

해결 방법

load_in_4bit=True 같은 구식 플래그를 제거하고 quantization_config만 사용
accelerate를 설치하고 device_map="auto"를 사용

pip install -U transformers accelerate

그리고 아래처럼 구성합니다.

from transformers import BitsAndBytesConfig
import torch

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
)

디버깅을 빠르게 만드는 로깅/검증 팁

1) Transformers 로딩 경로와 디바이스 매핑 확인

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    quantization_config=bnb_config,
)

print(model.hf_device_map)

여기서 레이어가 CPU로 많이 떨어지면 VRAM 부족이거나, CUDA 초기화가 완전히 성공하지 못한 상태일 수 있습니다.

2) VRAM 부족과 bitsandbytes 오류를 구분

VRAM 부족은 보통 CUDA out of memory로 명확히 뜹니다. 반면 bitsandbytes는 설치/로드 단계에서 터지는 경우가 많습니다.

OOM이면 max_memory를 주거나, 더 작은 모델/더 공격적인 양자화를 고려
로드 실패면 이 글의 1~4번 케이스를 우선 의심

3) 환경 문제는 “10분 진단 루틴”이 중요

로컬 LLM 환경 문제는 본질적으로 “의존성 그래프” 문제라서, 체크리스트 기반으로 빠르게 좁히는 게 효율적입니다. 비슷한 접근으로 인프라 장애를 빠르게 분류하는 글로는 아래가 참고가 됩니다.

K8s ImagePullBackOff - registry auth·CA 10분 진단

마무리: 에러 메시지보다 ‘불일치 축’을 찾아라

bitsandbytes 오류는 표면적으로는 한 줄짜리 ImportError처럼 보이지만, 실제 원인은 보통 “버전 불일치”입니다. 특히 다음 3개 축을 우선으로 맞추면 해결 확률이 크게 올라갑니다.

PyTorch가 어떤 CUDA로 빌드됐는지(torch.version.cuda)
드라이버가 제공하는 CUDA 호환(nvidia-smi)
시스템 런타임(GLIBC, libstdc++)이 충분히 최신인지

그래도 해결이 안 되면, 에러 전문과 함께 위 체크리스트 출력(파이썬/토치/CUDA/GLIBC/python -m bitsandbytes)을 묶어서 보면 원인 추정이 훨씬 정확해집니다.

4bit 양자화 로딩의 기본 형태

먼저 확인할 5가지 체크리스트

오류 1: CUDA Setup failed despite GPU being available

대표 증상

흔한 원인

해결 방법 A: PyTorch CUDA 빌드에 맞춰 재설치

해결 방법 B: 라이브러리 로딩 경로 충돌 제거

오류 2: undefined symbol 또는 GLIBCXX_... not found

대표 증상

원인

해결 방법

오류 3: RuntimeError: CUDA error: no kernel image is available for execution on the device

대표 증상

원인

해결 방법

오류 4: bitsandbytes was compiled without GPU support

대표 증상

원인

해결 방법

오류 5: ValueError: You can't pass load_in_4bit ... 또는 설정 충돌

대표 증상

원인

해결 방법

디버깅을 빠르게 만드는 로깅/검증 팁

1) Transformers 로딩 경로와 디바이스 매핑 확인

2) VRAM 부족과 bitsandbytes 오류를 구분

3) 환경 문제는 “10분 진단 루틴”이 중요

추천 조합(경험적으로 덜 깨지는 스택)

마무리: 에러 메시지보다 ‘불일치 축’을 찾아라

오류 1: `CUDA Setup failed despite GPU being available`

오류 2: `undefined symbol` 또는 `GLIBCXX_... not found`

오류 3: `RuntimeError: CUDA error: no kernel image is available for execution on the device`

오류 4: `bitsandbytes was compiled without GPU support`

오류 5: `ValueError: You can't pass load_in_4bit ...` 또는 설정 충돌