책에 포함된 노트내 PC에서 시작하는 온디바이스 LLM 실전: llama.cpp로 배우는 로컬 AI 구축

5. 개발 환경 준비: Windows·macOS·Linux·Android

2026-04-23Views 11약 10분생성형 AI 활용

개발 환경 준비: Windows·macOS·Linux·Android

llama.cpp를 처음 접하면 이런 생각이 먼저 듭니다.

"모델보다 설치가 더 어려워 보이는데요?"

그 느낌이 이상한 건 아닙니다. 온디바이스 LLM은 모델만 고르면 끝나는 분야가 아니라, 내 운영체제에서 실제로 실행 파일을 만들고 확인하는 과정이 꼭 필요하기 때문입니다. 다만 겁먹을 필요는 없습니다. 선택지가 많아 보여서 복잡해 보일 뿐, 초보자가 따라갈 기본 흐름은 생각보다 단순합니다.

이 장의 목표는 딱 하나입니다.

내 운영체제에서 llama.cpp를 설치하거나 빌드해서, 다음 장에서 실제로 모델을 실행할 준비를 끝내는 것.

이번 장에서는 운영체제별로 가장 현실적인 시작 경로를 먼저 보여 드리고, 그다음 필요할 때만 한 단계 더 들어가겠습니다. 핵심 원칙은 같습니다.

처음에는 가장 쉬운 경로로 llama-cli가 실행되는 상태부터 만든다.

설치 방법은 네 가지로 생각하면 편하다

공식 quick start 기준으로 llama.cpp를 준비하는 대표 경로는 다음 네 가지입니다.¹²

패키지 매니저 설치
사전 빌드 바이너리 사용
소스에서 직접 빌드
Docker 사용

이 책은 초보자 중심이므로 Docker는 깊게 다루지 않겠습니다. 지금 여러분에게 중요한 것은 컨테이너 오케스트레이션이 아니라 로컬에서 바로 실행 파일을 확보하는 것이기 때문입니다.

그래서 실전 판단은 이렇게 하면 됩니다.

빨리 시작하고 싶다 → 패키지 매니저 또는 사전 빌드 바이너리
내 하드웨어에 맞춘 가속을 제대로 쓰고 싶다 → 소스 빌드
운영 환경을 깔끔하게 분리하고 싶다 → 나중에 Docker 검토

설치 전에 공통으로 준비할 것

운영체제가 달라도 먼저 챙길 것은 거의 같습니다.

1) 작업 폴더를 정한다

나중에 "실행 파일이 어디 있지?", "모델은 어느 폴더에 뒀지?" 하고 헤매지 않으려면, 폴더 구조를 먼저 잡는 편이 좋습니다.

예를 들면 이렇게만 정해도 충분합니다.

작업 폴더: ~/llm 또는 C:llm
소스 폴더: ~/llm/llama.cpp
모델 폴더: ~/llm/models
실험 결과 폴더: ~/llm/runs

이 구조를 미리 정해 두면 다음 장 실습이 훨씬 편해집니다.

2) 디스크 공간과 메모리 여유를 확인한다

llama.cpp 자체는 크지 않지만, 빌드 도구와 모델 파일은 생각보다 공간을 먹습니다. 특히 Windows에서 Visual Studio와 CUDA Toolkit까지 설치하면 용량이 빠르게 늘어납니다.

3) 터미널에 익숙해진다

이번 장에서는 운영체제마다 아래 도구를 씁니다.

Windows: PowerShell 또는 개발자용 PowerShell
macOS: Terminal
Linux: shell/bash
Android: Termux

명령어를 모두 외울 필요는 없습니다. 다만 현재 내가 어느 폴더에 있는지, 실행 파일 경로가 무엇인지 정도는 눈으로 읽을 수 있어야 합니다.

4) 다음 장에서 쓸 모델 경로를 미리 생각한다

이 장에서는 설치 중심으로 가지만, 다음 장에서는 곧바로 GGUF 모델을 불러옵니다. 그러니 모델을 둘 폴더는 지금 정해 두는 편이 좋습니다.

가장 먼저 기억할 공통 빌드 명령

운영체제별로 설명은 다르지만, llama.cpp의 가장 기본 빌드 흐름은 공식 build guide 기준으로 아래 두 줄입니다.²

cmake -B build
cmake --build build --config Release

정말 중요하니 한 번 더 말씀드리겠습니다. 초보자에게는 이 두 줄이 기준점입니다.

운영체제별 차이는 대부분 이 앞뒤에서 생깁니다.

CMake를 어떻게 설치하느냐
어떤 백엔드를 켜느냐
결과 실행 파일이 어디에 생기느냐

즉, 기본 뼈대는 생각보다 같습니다.

Windows에서 준비하기

Windows는 선택지가 많아서 처음엔 가장 복잡해 보입니다. 하지만 순서를 잘 잡으면 오히려 명확합니다.

가장 쉬운 길: winget 설치

공식 quick start는 Windows에서 winget 설치 경로를 안내합니다.¹

먼저 PowerShell을 열고 아래처럼 설치를 시도할 수 있습니다.

winget install ggml.llamacpp

설치가 끝난 뒤에는 새 터미널을 열고 확인합니다.

llama-cli --help
llama-server --help

이 명령이 정상적으로 도움말을 보여 주면, 가장 쉬운 시작은 이미 끝난 셈입니다.

이 경로는 이런 분께 좋습니다.

오늘 안에 실행 파일부터 확보하고 싶은 분
빌드 환경 설정에 시간을 쓰고 싶지 않은 분
CPU 위주로 먼저 시작해 보고 싶은 분

다만 주의할 점도 있습니다. 패키지 매니저 설치는 빠르지만, 내 GPU 백엔드나 세부 빌드 옵션을 세밀하게 통제하기에는 한계가 있을 수 있습니다. 그런 경우에는 아래의 직접 빌드 경로가 더 낫습니다.

정석 경로: Visual Studio + CMake 빌드

Windows에서 직접 빌드할 때 공식 문서가 안내하는 기본 방향은 Visual Studio 2022와 CMake입니다.²

먼저 다음을 준비합니다.

Visual Studio 2022
Desktop development with C++ 워크로드
CMake
Git

설치가 끝나면 Developer PowerShell for VS 2022 또는 개발자용 명령 프롬프트를 여는 편이 좋습니다. 일반 터미널보다 빌드 환경이 이미 잡혀 있어서 덜 헤맵니다.²

그다음 소스를 받아 빌드합니다.

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release

빌드가 끝난 뒤에는 보통 buildbinRelease 또는 buildbin 근처에서 실행 파일을 찾게 됩니다. 버전과 생성기 설정에 따라 경로가 조금 다를 수 있으니, llama-cli.exe와 llama-server.exe가 실제로 어디 생겼는지 한 번 눈으로 확인하세요.

NVIDIA GPU가 있다면: CUDA 빌드

NVIDIA GPU가 있고 CUDA 가속을 쓰고 싶다면, 공식 build guide 기준으로 CUDA Toolkit을 준비한 뒤 아래처럼 빌드합니다.²

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

여기서 초보자에게 가장 중요한 원칙은 하나입니다.

CPU 빌드를 먼저 성공시키고, 그다음 CUDA로 올라간다.

처음부터 GPU까지 한 번에 잡으려 하면, 실패했을 때 원인이 설치 문제인지 GPU 문제인지 구분하기 어렵습니다.

Windows에서 자주 막히는 지점

초보자가 특히 많이 겪는 문제는 대체로 이렇습니다.

winget은 됐는데 명령어가 안 잡힌다 → 새 터미널을 열지 않은 경우
CMake는 설치했는데 빌드가 안 된다 → 개발자용 PowerShell이 아닌 일반 셸에서 실행한 경우
CUDA를 설치했는데 인식이 안 된다 → Toolkit 설치 후 터미널 재시작이 필요한 경우
경로가 꼬였다 → build 폴더를 지우고 다시 구성하는 편이 빠를 때가 많음

Windows에서는 복잡한 해결책보다 경로, 셸, 도구 설치 상태를 차례대로 보는 편이 더 효과적입니다.

macOS에서 준비하기

macOS는 전반적으로 설치 경험이 좋은 편입니다. 특히 Apple Silicon이라면 Metal이 기본적으로 중요한 축이 됩니다.¹²

가장 쉬운 길: Homebrew 설치

공식 quick start는 brew 설치 경로를 안내합니다.¹

Homebrew가 없다면 먼저 설치합니다.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

그다음 llama.cpp를 설치합니다.

brew install llama.cpp

확인은 이렇게 합니다.

llama-cli --version
llama-server --version

이 경로의 장점은 아주 단순합니다. 오늘 안에 바로 실행해 보고 싶은 사람에게 가장 부담이 적다는 점입니다.

직접 빌드하는 길

직접 빌드로 가려면 먼저 기본 도구를 준비합니다.

xcode-select --install
brew install git cmake

그다음 일반 빌드를 진행합니다.

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release

실행 확인은 보통 이렇게 합니다.

./build/bin/llama-cli --help

Metal은 보통 기본 활성화라고 생각하면 된다

공식 build guide 기준으로 macOS에서는 Metal이 기본적으로 활성화됩니다.² 즉, 대부분의 경우 초보자가 굳이 처음부터 Metal 옵션을 별도로 고민하지 않아도 됩니다.

오히려 여기서 더 중요한 것은 이것입니다.

Apple Silicon에서 GPU 가속을 억지로 꺼야 하는 특별한 이유가 있는가
아니면 기본값으로 먼저 성공 경험을 만들 것인가

정답은 거의 항상 두 번째입니다.

만약 나중에 GPU 사용을 끄고 CPU-only로 비교하고 싶다면, 빌드 시점보다 실행 시점에서 --n-gpu-layers 0 같은 방식으로 비교하는 편이 더 이해하기 쉽습니다.²

Linux에서 준비하기

Linux는 "설치는 단순하지만 선택지는 많다"에 가깝습니다. 기본 CMake 빌드만으로도 충분히 시작할 수 있고, 필요하면 OpenBLAS, CUDA, Vulkan 같은 경로를 나중에 붙이면 됩니다.²

1단계: 필수 도구 설치

배포판별로 이름은 조금 다르지만, 필요한 것은 거의 같습니다. Git, 컴파일러, CMake입니다.

Ubuntu/Debian 계열은 보통 이렇게 시작합니다.

sudo apt update
sudo apt install -y git build-essential cmake

Fedora 계열은 이렇게 갑니다.

sudo dnf install git gcc gcc-c++ make cmake

Arch 계열은 다음과 비슷합니다.

sudo pacman -S git base-devel cmake

2단계: 기본 CPU 빌드

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release

설치 확인은 이렇게 하면 됩니다.

./build/bin/llama-cli --help

이 단계가 되면 이미 "Linux에서 llama.cpp를 실행할 수 있는 상태"는 확보한 것입니다.

CPU 프롬프트 처리 성능을 조금 챙기고 싶다면: BLAS

공식 build guide는 BLAS 지원이 배치 크기가 큰 프롬프트 처리에 성능 이점을 줄 수 있다고 설명합니다.² 다만 생성 속도를 무조건 올려 주는 만능 버튼은 아닙니다.

Ubuntu/Debian 기준 예시는 다음과 같습니다.

sudo apt install libopenblas-dev
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release

초보자 입장에서는 이렇게 이해하면 충분합니다.

먼저 일반 빌드로 성공한다.
긴 입력 처리에서 답답함이 보이면 BLAS를 붙여 본다.
그래도 생성 속도 자체가 느리면 다른 손잡이를 본다.

NVIDIA GPU가 있다면: CUDA

Linux에서 CUDA 빌드는 공식적으로 잘 정리되어 있습니다.²

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

이 경로로 가기 전에는 nvidia-smi가 정상 동작하는지 먼저 보는 편이 좋습니다. 이것이 안 되면 llama.cpp 이전에 드라이버나 CUDA 환경 자체를 먼저 봐야 합니다.

다양한 GPU를 노린다면: Vulkan

NVIDIA가 아닌 환경에서는 Vulkan 백엔드도 후보가 됩니다.²

cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

물론 초보자에게는 여기서부터 난이도가 조금 올라갑니다. 그래서 권장 순서는 늘 같습니다.

CPU 빌드 성공
필요 시 CUDA 또는 Vulkan 추가
성능 비교

Android에서 준비하기

Android는 완전히 다른 세계처럼 느껴지지만, 공식 문서는 두 경로를 보여 줍니다.³

Android Studio로 GUI 바인딩 프로젝트 빌드
Termux에서 CLI 빌드

이 책은 초보자용 step-by-step 실습이 목적이므로, Termux에서 CLI를 성공시키는 경로를 기준으로 설명하겠습니다.

가장 쉬운 길: Termux에서 CLI 빌드

공식 Android 문서는 Termux를 통해 llama.cpp를 Linux처럼 빌드하고 실행하는 흐름을 안내합니다.³

먼저 Termux에서 패키지를 업데이트합니다.

apt update && apt upgrade -y
apt install git cmake

그다음 소스를 내려받고 빌드합니다.

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release

이후 모델은 ~/ 아래에 두는 것이 성능상 유리하다고 공식 문서가 설명합니다.³

curl -L {model-url} -o ~/{model}.gguf

실행 예시는 이렇게 시작하면 됩니다.

./build/bin/llama-cli -m ~/{model}.gguf -c 4096 -p "안녕"

여기서 가장 중요한 것은 -c입니다. Android에서는 컨텍스트를 무작정 크게 잡으면 메모리가 급증해 Termux가 종료될 수 있습니다. 공식 문서도 처음에는 4096 정도의 합리적인 값으로 시작하라고 안내합니다.³

Android에서 기억할 점

스마트폰에서 LLM이 도는 건 인상적이지만, 운영 감각은 더 보수적이어야 합니다.

작은 모델부터 시작한다
출력 길이를 짧게 둔다
컨텍스트를 과하게 키우지 않는다
먼저 CLI로 안정성을 본다

즉, Android에서는 "된다"보다 "계속 된다"가 훨씬 중요합니다.

앱 통합이 목표라면: Android Studio 경로

만약 Termux가 아니라 실제 앱에 llama.cpp를 넣고 싶다면, 공식 문서의 examples/llama.android 프로젝트를 Android Studio로 여는 방향이 맞습니다.³

다만 이것은 앱 개발 흐름과 NDK, Gradle, Android 프로젝트 구조까지 함께 알아야 하므로, 이 책의 현재 단계에서는 욕심내지 않는 편이 좋습니다. 지금은 CLI 성공 → 모델 실행 감각 확보가 더 중요합니다.

운영체제별 추천 시작 경로를 한눈에 정리하면

처음 시작하는 독자에게는 아래 순서를 권합니다.

Windows: winget으로 먼저 설치 → 필요하면 Visual Studio + CMake 빌드
macOS: brew 설치로 시작 → 필요하면 직접 빌드
Linux: 기본 CMake 빌드 → 필요하면 BLAS/CUDA/Vulkan 추가
Android: Termux에서 CLI 빌드로 먼저 성공

핵심은 같습니다.

처음부터 최고 성능을 노리지 말고, 먼저 llama-cli가 실행되는 상태를 만들자.

설치가 끝났는지 확인하는 체크리스트

다음 질문에 모두 "예"라고 답할 수 있으면 다음 장으로 넘어갈 준비가 된 것입니다.

llama-cli --help 또는 해당 경로의 llama-cli가 실행되는가
llama-server --help도 확인했는가
모델을 둘 폴더를 정했는가
CPU로 시작할지, GPU 가속도 볼지 감이 잡혔는가
다음 장에서 사용할 GGUF 모델 파일 경로를 알고 있는가

초보자가 자주 하는 실수

마지막으로, 실제로 많이 막히는 지점을 짚고 가겠습니다.

실수 1: 모델 문제를 설치 문제로 착각한다

llama.cpp는 잘 설치됐는데 GGUF가 아닌 파일을 넣어 놓고 "설치가 실패했다"고 느끼는 경우가 많습니다. 설치와 모델 호환성은 구분해서 보세요.

실수 2: GPU 가속을 처음부터 욕심낸다

CPU 빌드가 먼저 성공해야 CUDA나 Vulkan 문제도 따로 진단할 수 있습니다.

실수 3: 실행 파일 경로를 헷갈린다

특히 직접 빌드한 경우에는 ./build/bin/ 또는 Windows의 buildbinRelease 경로를 자주 혼동합니다.

실수 4: 컨텍스트를 너무 크게 잡는다

설치는 성공했는데 실행 순간 메모리가 부족해지는 경우가 많습니다. 이때 원인은 설치가 아니라 설정입니다.

이제 다음 장으로 넘어갈 준비가 되었다

이번 장에서 한 일은 화려하지 않습니다. 하지만 온디바이스 LLM 실전에서는 아주 중요합니다. 여러분은 이제 운영체제에 맞는 경로를 골라 llama.cpp 실행 환경을 준비할 수 있고, 패키지 설치와 직접 빌드의 차이도 구분할 수 있게 되었습니다.

다음 장에서는 드디어 GGUF 모델을 실제로 불러와 내 PC에서 첫 답변을 받아보는 순간까지 가보겠습니다.

참고

²llama.cpp build guide

³llama.cpp Android guide

책 목록

내 PC에서 시작하는 온디바이스 LLM 실전: llama.cpp로 배우는 로컬 AI 구축

전체 목차 보기