WSL2(Ubuntu 24.04)에서 llama.cpp 빌드 및 GPU 서버 실행 완벽 정리

안녕하세요! 로컬에서 LLM을 돌리기 위해 llama.cpp를 사용하시는 분들이 많으신데요, 특히 WSL2 환경에서 NVIDIA GPU를 사용하도록 직접 빌드하는 과정은 예상치 못한 오류들의 연속일 수 있습니다. 😭

이 글에서는 수많은 오류를 해결하며 얻은 최종 성공 방법만을 모아 WSL2에서 llama.cpp를 완벽하게 빌드하고 GGUF 모델을 서버로 실행하는 과정을 순서대로 안내합니다.

1단계: 필수 패키지 및 CUDA Toolkit 설치

가장 먼저 컴파일에 필요한 모든 도구와 라이브러리, 그리고 GPU 사용을 위한 CUDA Toolkit을 설치합니다.

1. 기본 빌드 도구 및 라이브러리 설치

터미널을 열고 아래 명령어를 실행해 git, cmake, libcurl 등 필수 패키지를 한 번에 설치합니다.

Bash

sudo apt update
sudo apt install -y build-essential git cmake libcurl4-openssl-dev

2. NVIDIA CUDA Toolkit 설치

다음으로 WSL용 NVIDIA CUDA Toolkit을 설치합니다.

Bash

# CUDA 리포지토리 PIN 파일 다운로드 및 이동
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin
sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600

# CUDA 리포지토리 GPG 키 다운로드 및 추가
wget https://developer.download.nvidia.com/compute/cuda/12.5.1/local_installers/cuda-repo-wsl-ubuntu-12-5-local_12.5.1-1_amd64.deb
sudo dpkg -i cuda-repo-wsl-ubuntu-12-5-local_12.5.1-1_amd64.deb
sudo cp /var/cuda-repo-wsl-ubuntu-12-5-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update

# CUDA Toolkit 설치
sudo apt-get -y install cuda-toolkit-12-5

3. CUDA 환경 변수 설정 (매우 중요)

설치된 CUDA를 시스템이 인식할 수 있도록 경로를 설정해야 합니다.

Bash

# .bashrc 파일에 환경 변수 추가
echo 'export PATH=/usr/local/cuda/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc

# 변경된 설정 즉시 적용
source ~/.bashrc

---

2단계: llama.cpp 소스코드 다운로드 및 컴파일

이제 모든 준비가 끝났습니다. llama.cpp 소스코드를 내려받아 내 GPU에 맞게 컴파일합니다.

1. llama.cpp 소스코드 다운로드
2. Bash

   git clone https://github.com/ggerganov/llama.cpp.git
   cd llama.cpp
   

3. 빌드 디렉토리 생성
4. Bash

   mkdir build
   cd build
   

5. CMake로 빌드 환경 구성 (최종 성공 옵션) 아래 명령어가 이 가이드의 핵심입니다. **GPU 사용(GGML_CUDA)**과 GPU 아키텍처 지정(CMAKE_CUDA_ARCHITECTURES) 옵션을 모두 포함합니다. (RTX 30/40/50 시리즈 기준 89)
6. Bash

   cmake .. -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES=89
   

7. 컴파일 실행오류 없이 완료되면 build/bin 폴더 안에 server 실행 파일이 생성됩니다.
8. Bash

   cmake --build . --config Release
   

---

3단계: API 서버 실행 및 확인

컴파일된 서버를 실행하여 모델을 로드합니다.

1. 서버 실행 llama.cpp 폴더 밖, GGUF 모델이 있는 상위 디렉토리로 이동하여 아래 명령어를 실행하세요. (파일 경로와 -ngl 값은 본인 환경에 맞게 조절)
2. Bash

   ./llama.cpp/build/bin/server -m ./models/[모델파일이름].gguf -ngl 35 --host 0.0.0.0 --port 8000
   

3. 확인 윈도우의 웹 브라우저를 열고 주소창에 http://localhost:8000 을 입력하면 llama.cpp의 웹 UI가 나타납니다. 여기서 모델과 대화하며 테스트할 수 있습니다.

 

 

이 글이 WSL2에서 llama.cpp를 설정하는 데 도움이 되었으면 좋겠습니다. 성공적으로 로컬 LLM 서버를 구축하신 것을 축하합니다! 🎉