Transformers+bitsandbytes 4bit CUDA 오류 해결 가이드

로컬 LLM을 Transformers + bitsandbytes 4bit(QLoRA 계열)로 돌리려다 보면, 설치는 성공했는데 실행 시점에 CUDA 관련 에러가 터지는 경우가 많습니다. 특히 윈도우/WSL 혼용, PyTorch CUDA 런타임 버전 불일치, bitsandbytes 바이너리 미지원 조합에서 빈번합니다.

이 글은 “에러 메시지”를 기준으로 원인을 좁히고, 가장 적은 변경으로 4bit 로딩을 안정화하는 방법을 제공합니다. 마지막에는 정상 동작하는 최소 예제 코드까지 포함합니다.

가장 흔한 증상(에러 패턴) 요약

아래 중 하나라도 보이면, 거의 항상 PyTorch CUDA 런타임과 bitsandbytes 바이너리/환경이 맞지 않는 문제입니다.

CUDA is required but not available
RuntimeError: CUDA error: invalid device function
OSError: libcudart.so.*: cannot open shared object file
bitsandbytes was compiled without GPU support
undefined symbol: cublas* 또는 libcublas.so 로드 실패
No module named 'bitsandbytes.cuda_setup' 혹은 CUDA setup 관련 경고

핵심은 다음 3가지 축입니다.

GPU/드라이버: NVIDIA 드라이버가 너무 낮거나, WSL/컨테이너에서 GPU 패스스루가 안 됨
PyTorch CUDA 런타임: torch 가 +cu121 같은 CUDA 빌드인지, CPU 전용인지
bitsandbytes 바이너리/버전: OS/파이썬/쿠다 조합에 맞는 wheel인지, 혹은 소스 빌드가 필요한지

0단계: 환경을 먼저 “고정”하자(재현 가능한 베이스라인)

4bit 로딩은 의존성 조합에 민감합니다. 먼저 가상환경을 새로 만들고, 아래 체크를 통과시키는 것을 목표로 하세요.

리눅스(우분투) 권장. 윈도우 네이티브는 bitsandbytes 호환성이 흔들리는 경우가 많습니다.
WSL2는 가능하지만, NVIDIA WSL 드라이버/툴킷 구성이 맞아야 합니다.

필수 체크 1: GPU 드라이버 확인

nvidia-smi

여기서 GPU가 보이지 않으면, 어떤 설정을 해도 4bit CUDA 가속은 불가능합니다.
WSL이라면 nvidia-smi 가 WSL 내부에서 동작해야 합니다.

필수 체크 2: PyTorch 가 CUDA 빌드인지 확인

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)"

torch.version.cuda 가 None 이면 CPU 전용입니다.
torch.cuda.is_available() 가 False 면 드라이버/런타임 경로 문제일 가능성이 큽니다.

1단계: 설치 조합(권장 버전)으로 먼저 맞추기

가장 빠른 해결책은 “검증된 조합”으로 재설치하는 것입니다.

리눅스(우분투)에서 권장 설치 예시

아래는 CUDA 12.1 계열 PyTorch를 기준으로 한 예시입니다. (드라이버는 12.x 런타임을 지원해야 합니다.)

python -m venv .venv
source .venv/bin/activate

pip install -U pip

# PyTorch CUDA 빌드 설치 (예: cu121)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Transformers 스택
pip install -U transformers accelerate safetensors

# 4bit용 bitsandbytes
pip install -U bitsandbytes

설치 후 다시 아래를 확인합니다.

python -c "import bitsandbytes as bnb; import torch; print('bnb', bnb.__version__); print('torch', torch.__version__, 'cuda', torch.version.cuda)"

자주 하는 실수: 시스템 CUDA Toolkit 설치에 집착하기

bitsandbytes 와 torch 는 보통 wheel에 포함된 CUDA 런타임을 사용합니다. 시스템에 CUDA Toolkit을 설치해도, torch 가 CPU 빌드면 의미가 없습니다.

먼저 torch 를 +cu121 같은 CUDA 빌드로 맞추는 게 1순위
그 다음 bitsandbytes 가 해당 조합에서 GPU를 잡는지 확인

2단계: 에러 메시지별 원인과 해결

여기부터는 “에러 문구”로 분기합니다.

케이스 A: `CUDA is required but not available`

원인 후보:

torch 가 CPU 전용 빌드
컨테이너/WSL에서 GPU가 노출되지 않음
드라이버가 너무 낮아 런타임이 초기화 실패

해결 순서:

torch.version.cuda 가 None 이면 CUDA 빌드로 재설치

pip uninstall -y torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

컨테이너라면 --gpus all 또는 NVIDIA Container Toolkit 설정 확인
WSL이면 WSL용 NVIDIA 드라이버 설치 및 WSL 내부 nvidia-smi 확인

케이스 B: `bitsandbytes was compiled without GPU support`

원인 후보:

OS/파이썬 버전 조합에서 GPU 지원 wheel을 못 받아서 CPU 폴백
오래된 bitsandbytes 버전
윈도우 네이티브 환경에서 흔함

해결 방법:

bitsandbytes 업그레이드

pip install -U bitsandbytes

가능하면 리눅스/WSL로 이동(가장 확실)
그래도 안 되면 소스 빌드가 필요할 수 있습니다. 다만 소스 빌드는 환경별 편차가 커서, 실무에서는 리눅스 기반 도커/WSL로 우회하는 것이 비용이 낮습니다.

케이스 C: `OSError: libcudart.so.*` 또는 `libcublas.so` 로드 실패

원인 후보:

LD_LIBRARY_PATH 문제
torch CUDA wheel과 시스템 라이브러리가 충돌
컨테이너 베이스 이미지가 너무 슬림해서 런타임 라이브러리가 없음

해결 방법:

우선 torch 를 CUDA wheel로 설치했는지 재확인
컨테이너라면 CUDA 런타임이 포함된 베이스 이미지를 사용

예: nvidia/cuda 런타임 기반에서 실행하거나, 최소한 드라이버 마운트가 정상인지 확인합니다.

리눅스에서 라이브러리 탐색

python -c "import torch; import os; print(torch.__file__); print(os.environ.get('LD_LIBRARY_PATH'))"

이 케이스는 “시스템 CUDA 설치”로 해결되는 경우도 있지만, 대체로 PyTorch wheel 기반 런타임을 깨끗하게 재설치하는 게 더 빠릅니다.

케이스 D: `RuntimeError: CUDA error: invalid device function`

원인 후보:

GPU 아키텍처가 너무 낮아(구형) 해당 커널을 지원하지 않음
bitsandbytes 가 특정 compute capability에서만 동작

해결 방법:

GPU 모델 확인

nvidia-smi --query-gpu=name,compute_cap --format=csv

구형 GPU(예: compute capability가 낮은 카드)라면 4bit가 불안정할 수 있습니다.

대안:

8bit 로딩으로 타협(load_in_8bit)
CPU 또는 다른 양자화 백엔드(GGUF + llama.cpp 계열)로 전환

3단계: Transformers 4bit 로딩 “정상 동작” 최소 예제

아래 코드는 transformers 의 BitsAndBytesConfig 로 4bit NF4 로딩을 수행합니다.

주의: 모델은 예시이며, 실제로는 본인이 접근 가능한 HF 모델로 바꾸세요.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

model_id = "mistralai/Mistral-7B-Instruct-v0.2"

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

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

prompt = "한국어로 3문장만: 로컬 LLM 4bit 로딩이 왜 유용한가?"
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

with torch.no_grad():
    out = model.generate(
        **inputs,
        max_new_tokens=120,
        do_sample=True,
        temperature=0.7,
    )

print(tokenizer.decode(out[0], skip_special_tokens=True))

`bfloat16` 관련 주의

torch.bfloat16 은 GPU가 BF16을 잘 지원할 때 유리합니다.
BF16 지원이 애매하면 torch.float16 으로 바꾸세요.

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

4단계: 디버깅 체크리스트(실전용)

문제가 반복될 때는 아래를 위에서부터 순서대로 확인하면 대부분 잡힙니다.

1) 파이썬/패키지 충돌 제거

pip freeze | grep -E "torch|transformers|accelerate|bitsandbytes"

의심되면 과감히 지우고 재설치:

pip uninstall -y bitsandbytes transformers accelerate torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install -U transformers accelerate bitsandbytes

2) `device_map` 과 오프로딩 상태 확인

device_map="auto" 는 편하지만, VRAM이 부족하면 CPU 오프로딩이 섞이면서 속도가 급격히 느려지고, 일부 환경에서는 예외가 날 수 있습니다.

VRAM이 빡빡하면 max_memory 를 명시해 안정화할 수 있습니다.

max_memory = {0: "10GiB", "cpu": "32GiB"}
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=bnb_config,
    device_map="auto",
    max_memory=max_memory,
)

3) 드라이버-런타임 “버전 착시” 피하기

nvidia-smi 에 보이는 CUDA 버전은 “드라이버가 지원하는 최대 버전”에 가깝습니다.
실제로 파이썬에서 쓰는 런타임은 torch.version.cuda 가 기준입니다.

둘이 다르다고 무조건 문제는 아니지만, torch.cuda.is_available() 가 False 면 설치/런타임 문제가 맞습니다.

5단계: 그래도 안 되면(우회 전략)

환경 제약 때문에 bitsandbytes 4bit가 계속 실패하는 경우, 아래 우회가 실무적으로 더 빠를 때가 많습니다.

우회 1) 8bit 로딩으로 내리기

from transformers import BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(load_in_8bit=True)

4bit보다 메모리는 더 쓰지만, 특정 GPU/드라이버 조합에서 안정적일 수 있습니다.

우회 2) GGUF + llama.cpp 계열로 전환

CUDA가 아니라도(또는 다른 백엔드로) 안정적으로 양자화 모델을 돌릴 수 있습니다.
다만 Transformers 파이프라인과는 운영 방식이 달라집니다.

운영 관점 팁: 로컬 LLM은 “환경 고정”이 성능 최적화다

로컬 LLM 스택은 패키지 버전 하나만 바뀌어도 성능/안정성이 흔들립니다. 도커 이미지나 requirements.txt 로 환경을 고정하고, GPU 노드별로 검증된 조합을 문서화해두는 것이 장기적으로 시간을 절약합니다.

빌드/캐시 최적화 관점은 다음 글의 접근이 도움 됩니다: Docker 빌드 느림? BuildKit 캐시·레이어 최적화 12

또한 로컬 LLM을 RAG로 확장할 계획이라면, 벡터 인덱스 튜닝이 병목이 되는 경우가 많습니다. 아래 글도 함께 참고해두면 좋습니다.

Rust+Qdrant RAG - HNSW 튜닝으로 지연 50%↓

마무리

Transformers + bitsandbytes 4bit CUDA 오류는 대부분 “GPU는 보이는데, 파이썬 런타임에서 CUDA가 초기화되지 않거나, bitsandbytes 바이너리가 현재 조합을 지원하지 않는 문제”로 귀결됩니다.

해결의 우선순위는 명확합니다.

torch 를 CUDA 빌드로 고정하고 torch.cuda.is_available() 를 True 로 만든다
그 위에 bitsandbytes 를 올려 GPU 지원이 활성화되는지 확인한다
그래도 안 되면 OS를 리눅스/WSL로 정리하거나 8bit/GGUF로 우회한다

위 체크리스트와 최소 예제를 그대로 따라가면, “설치만 되고 실행은 안 되는” 상태에서 빠르게 빠져나올 수 있습니다.

가장 흔한 증상(에러 패턴) 요약

0단계: 환경을 먼저 “고정”하자(재현 가능한 베이스라인)

필수 체크 1: GPU 드라이버 확인

필수 체크 2: PyTorch 가 CUDA 빌드인지 확인

1단계: 설치 조합(권장 버전)으로 먼저 맞추기

리눅스(우분투)에서 권장 설치 예시

자주 하는 실수: 시스템 CUDA Toolkit 설치에 집착하기

2단계: 에러 메시지별 원인과 해결

케이스 A: CUDA is required but not available

케이스 B: bitsandbytes was compiled without GPU support

케이스 C: OSError: libcudart.so.* 또는 libcublas.so 로드 실패

케이스 D: RuntimeError: CUDA error: invalid device function

3단계: Transformers 4bit 로딩 “정상 동작” 최소 예제

bfloat16 관련 주의

4단계: 디버깅 체크리스트(실전용)

1) 파이썬/패키지 충돌 제거

2) device_map 과 오프로딩 상태 확인

3) 드라이버-런타임 “버전 착시” 피하기

5단계: 그래도 안 되면(우회 전략)

우회 1) 8bit 로딩으로 내리기

우회 2) GGUF + llama.cpp 계열로 전환

운영 관점 팁: 로컬 LLM은 “환경 고정”이 성능 최적화다

마무리

케이스 A: `CUDA is required but not available`

케이스 B: `bitsandbytes was compiled without GPU support`

케이스 C: `OSError: libcudart.so.*` 또는 `libcublas.so` 로드 실패

케이스 D: `RuntimeError: CUDA error: invalid device function`

`bfloat16` 관련 주의

2) `device_map` 과 오프로딩 상태 확인