llama.cpp 릴리스 버전 고정 및 관리 방법

llama.cpp 버전 관리의 변경 사항

llama.cpp 릴리스를 고정한다는 것은 특정 태그를 빌드하고 해당 이름을 모델 파일 옆에 기록해 두는 것을 의미합니다. 태그는 스스로 이동하지 않으므로, 서버는 오늘 생성한 결과물을 내일도 동일하게 생성합니다. 수년간 선택할 수 있는 태그는 마스터 브랜치에서 자동으로 생성되는 b10502과 같은 빌드 번호뿐이었습니다. 2026년부터는 v0.1.2와 같은 버전 태그라는 두 번째 유형이 추가되었으며, 두 트랙 모두 동일한 기록에서 동시에 생성됩니다.

버전 태그가 일반적인 버전 번호의 의미를 완전히 담고 있는 것은 아닙니다. v0.1.2의 릴리스 노트에는 다음과 같이 명시되어 있습니다.

시맨틱 버전 관리는 아직 진행 중인 작업입니다. 자세한 정보는 https://github.com/ggml-org/ggml/discussions/1579에서 확인할 수 있습니다.

이 문구를 그대로 받아들여야 합니다. 해당 링크의 ggml 토론은 릴리스 주기와 패치 기준을 포함하여 버전 체계를 어떻게 구성할지 논의하는 곳입니다. v0. 태그는 프로젝트 팀이 기록의 특정 지점을 표시하기로 결정했음을 의미할 뿐입니다. 마지막 숫자가 1 증가했다고 해서 다음 버전이 안전하게 교체 가능한 릴리스라는 보장은 없습니다.

빌드 태그의 숫자 또한 버전으로서의 의미를 갖지 않습니다. 이 숫자는 커밋 횟수에서 파생되므로, 사용자의 설정과 관련이 있는지 여부와 관계없이 숫자가 계속 증가합니다. 2026년 8월 19일 기준으로 릴리스 목록 첫 페이지에는 b10455부터 b10502까지 9개의 빌드 태그가 있었으며, 그사이에 v0.1.2이 포함되어 있었습니다.

서비스 중인 서버에서 master 브랜치를 직접 빌드하지 마십시오

git pull 명령을 실행한 뒤 재빌드하면 최근 몇 시간 동안 반영된 모든 변경 사항이 적용됩니다. 이는 개인용 노트북에서는 문제가 되지 않지만, 서버에서는 동작이 변경되었을 때 가장 중요한 질문인 '현재 무엇이 실행 중인가'와 '지난주에는 무엇이 실행 중이었는가'에 답할 수 없게 만듭니다. 모델이 생성하는 텍스트의 품질과 속도는 빌드 시점에 따라 달라집니다. 화요일에 커밋된 내용이 기록되지 않았다면, 화요일부터 답변 품질이 저하되었다는 문제 제기에 대해 원인을 파악할 방법이 없습니다.

대신 특정 태그를 고정하여 사용하십시오. 프로젝트에서 태그를 생성하며, 모든 사전 빌드된 릴리스 아카이브는 해당 태그 이름을 따서 명명됩니다.

llama.cpp 릴리스는 어떤 태그에 고정해야 합니까?

특정 상태를 유지하려면 빌드 태그에 고정하십시오. 이 태그는 긴 이력을 가지고 있으며, 릴리스 아카이브의 이름이 이 태그를 따르고, 대부분의 버그 리포트에서 이를 기준으로 삼습니다. 따라서 빌드 번호가 다른 사용자와 상태를 비교하기에 가장 적합합니다.

의도적으로 선택된 지점들을 따라가고 싶다면 버전 태그에 고정하십시오. 이동하기 전에 릴리스 노트를 읽어야 하며, 버전 번호가 아직 호환성을 보장하는 계약은 아니라는 점을 유의하십시오.

어떤 방식을 선택하든 운영 규칙은 동일합니다. 태그 문자열은 파일에 저장되며, 해당 문자열이 변경될 때만 빌드가 다시 수행됩니다. 이 변경은 누군가가 의도적으로 결정한 결과여야 합니다.

고정된 태그 빌드하기

sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tags

git describe --tags 명령은 b10502을 출력해야 합니다. 태그를 기준으로 얕은 복제(shallow clone)를 수행하면 해당 커밋만 유지되고 이후의 변경 사항은 포함되지 않으므로, 누군가 부주의하게 git pull 명령을 실행하여 태그를 이동시킬 위험이 없습니다. 설정(configure) 단계에서 의존성 패키지 누락으로 중단되면, 메시지에 표시된 패키지를 설치한 뒤 다시 실행하십시오.

사용 중인 하드웨어에 필요한 옵션을 사용하여 빌드합니다. CPU 전용 빌드:

cmake -B build
cmake --build build --config Release -j $(nproc)

NVIDIA GPU 빌드(CUDA 툴킷이 먼저 설치되어 있어야 합니다):

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

CPU 전용 환경에서 OpenBLAS 사용:

cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)

바이너리는 로드하는 공유 라이브러리(libllama.so 및 libggml 파일)와 함께 build/bin 디렉터리에 생성됩니다. 설치하기 전에 빌드가 정상적으로 실행되는지 확인하십시오:

./build/bin/llama-server --version

태그 이름을 딴 경로 아래에 전체 디렉터리를 설치한 다음, 심볼릭 링크를 해당 경로로 연결하십시오:

sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current

단일 파일이 아닌 디렉터리 전체를 복사하십시오. llama-server 파일만 단독으로 실행하면 필요한 라이브러리가 같은 디렉터리에 없기 때문에 error while loading shared libraries: libllama.so: cannot open shared object file 오류가 발생하며 첫 실행부터 실패합니다.

서비스가 태그 디렉터리가 아닌 심볼릭 링크를 가리키도록 설정하십시오:

[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080

systemd는 프로세스를 시작할 때 심볼릭 링크를 해석하므로, 빌드를 교체할 때는 심볼릭 링크의 대상만 변경한 뒤 sudo systemctl restart llama-server 명령을 실행하면 됩니다. 유닛 파일의 나머지 부분과 앞단에 위치한 리버스 프록시 설정에 관한 자세한 내용은 VPS에서 llama.cpp 서버를 운영하기 위한 전체 가이드를 참조하십시오.

GGUF 파일과 양자화 수준 옆에 태그 기록하기

빌드는 결과물을 결정하는 절반의 요소이며, 모델 파일이 나머지 절반을 차지합니다. GGUF(GGML universal file format)는 가중치가 담기는 컨테이너이며, 동일한 모델이 여러 양자화 수준으로 배포됩니다. 따라서 같은 태그를 사용하더라도 한 서버는 Q4_K_M 파일을, 다른 서버는 Q8_0 파일을 사용하면 결과가 다를 수 있습니다. 설정을 정확하게 재현하는 데 필요한 모든 정보를 담은 작은 파일을 모델 옆에 유지하십시오.

tag: b10502
commit: 7c1f2a9
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>

고정된 체크아웃 내부에서 git rev-parse --short HEAD 명령으로 커밋을 확인하십시오. sha256sum model-q4_k_m.gguf 명령으로 체크섬을 구하고, 다운로드 시점에 게시자가 제공한 값과 비교하십시오. 게시된 체크섬으로 다운로드 파일 검증하기를 수행하면 파일이 잘려 나가는 문제를 미리 발견하여 혼란스러운 버그를 방지할 수 있습니다. 양자화 수준 자체가 답변에 미치는 영향은 별개의 문제이며, 각 양자화 수준의 비용에서 다룹니다.

서버를 중단시키지 않고 업그레이드하는 방법은 무엇입니까?

업그레이드를 모의 훈련처럼 수행하십시오. 기존 태그 옆에 새 태그를 빌드하고, 둘 다 측정한 뒤, 새 버전이 안정적으로 동작할 때까지 기존 버전을 유지하십시오.

1. 새 태그를 별도의 디렉터리에 복제하십시오. 기존 체크아웃을 재사용하지 마십시오.
2. 매니페스트에 기록된 것과 동일한 cmake 인수를 사용하여 빌드하십시오.
3. 동일한 모델 파일을 대상으로, 동일한 프롬프트 길이와 반복 횟수를 설정하여 두 빌드 모두에서 llama-bench을 실행하십시오.
4. 정답을 알고 있는 프롬프트를 두 서버 모두에 보내고 두 응답을 읽어보십시오.
5. 심볼릭 링크를 이동하고 서비스를 재시작하십시오. 기존 디렉터리는 디스크에 그대로 두십시오.

/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5

llama-bench은 테스트당 한 행씩 출력하며, backend 열, ngl 열, 그리고 표준 편차를 포함한 초당 토큰 수(tokens per second) 열을 표시합니다. 한 빌드의 프롬프트 행과 다른 빌드의 생성 행을 비교하지 말고, 두 빌드 간의 동일한 행을 비교하십시오. 프롬프트 길이가 다르면 측정값도 달라지므로, 항상 동일한 방식으로 초당 토큰 수 측정하기가 수치 자체보다 더 중요합니다.

롤백은 두 개의 명령어로 가능하며, 기존 디렉터리가 그대로 남아 있기 때문에 작동합니다.

sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server

최소한 이전 빌드 하나는 유지하십시오. 이는 옆에 있는 모델 파일이 사용하는 디스크 공간의 일부에 불과합니다.

llama.cpp 업그레이드 시 발생하는 문제

모델 파일을 불러오지 못합니다. 이는 보통 사용자가 업그레이드를 결정하는 주된 이유입니다. 새로 출시된 모델이 현재 고정된 빌드 버전에서 지원하지 않는 아키텍처를 사용하면 모델을 불러올 수 없습니다. llama-server는 시작 도중 종료되며 로그에는 failed to load model from /srv/models/model-q4_k_m.gguf 메시지가 남습니다. 로더가 어디까지 진행했는지 보여주는 직전 출력 줄을 확인하십시오. GGUF 헤더에는 형식 버전이 포함되어 있습니다(현재 사양 값은 3이며, 버전 2에서는 길이 필드가 32비트에서 64비트로 확장되었습니다). 하지만 실제로는 형식 버전보다 알 수 없는 아키텍처 이름 때문에 문제가 발생하는 경우가 훨씬 많습니다. 해결 방법은 더 최신 태그를 선택하여 적용하는 것입니다.

서버 플래그의 이름이 변경되거나 폐기되었습니다. 인식할 수 없는 플래그가 있으면 llama-server은 이를 무시하지 않고 시작 단계에서 중단됩니다. systemd 환경에서는 서비스가 시작과 종료를 반복하는 것처럼 보입니다. journalctl -u llama-server -n 50을 확인하면 실제 오류 메시지를 볼 수 있습니다. 2026년 8월 19일 기준으로 서버 문서에서는 --mlock 및 --mmap가 폐기되었으며, 대신 -lm, --load-mode을 사용하도록 권장합니다. 이 플래그는 auto, mmap, mlock, dio와 같은 값을 인자로 받습니다. GPU 오프로드 플래그는 -ngl, --gpu-layers로 문서화되어 있으나, 구형 가이드에는 --n-gpu-layers으로 기재되어 있습니다. 심볼릭 링크를 변경하기 전에 /opt/llama.cpp/<new tag>/bin/llama-server --help을 실행하여 유닛 파일의 모든 플래그가 현재 버전과 호환되는지 확인하십시오.

빌드 옵션의 이름이 변경되었습니다. CMake 옵션은 LLAMA_ 접두사에서 GGML_ 접두사로 변경되었으며, 루트 CMakeLists.txt에서 매핑 정보를 확인할 수 있습니다. LLAMA_CUBLAS은 이제 치명적인 오류로 간주되며 대체 항목으로 GGML_CUDA를 명시합니다. 반면 LLAMA_CUDA과 LLAMA_METAL는 경고를 출력하며 자동으로 변환됩니다. 빌드 스크립트가 구성 단계에서 멈추는 것은 차라리 다행인 경우입니다. 더 위험한 것은 조용히 실패하는 상황입니다. 실수로 -DGGML_CUDA=ON를 누락하면 빌드는 성공하고 서버도 시작되지만, 모든 연산이 CPU에서 수행됩니다. backend 열의 값이 CPU로 표시되므로 llama-bench을 실행하면 즉시 확인할 수 있습니다.

가속기 빌드는 이식성이 없습니다. 2026년 8월 19일 기준으로 빌드 태그에 포함된 Linux 에셋은 x64, arm64, s390x 아키텍처용 CPU, Vulkan, SYCL, OpenVINO 변형입니다. 해당 목록에는 Linux용 CUDA 아카이브가 없으므로, NVIDIA 서버를 사용하려면 소스에서 직접 빌드하거나 컨테이너 이미지를 실행해야 합니다. Windows용 CUDA 아카이브는 툴킷 버전별로 배포되는데, 이는 중요한 단서가 됩니다. 툴킷 버전은 바이너리를 식별하는 요소 중 하나이므로, cmake 인자와 함께 기록해 두십시오.

컨테이너 이미지 고정하기

같은 규칙이 다른 명사에도 적용됩니다. 배포된 이미지(ghcr.io/ggml-org/llama.cpp:server 및 해당 가속기 변형)는 이름이 계속 변경되므로, 다음 달에 :server을 가져오면 동일한 레이블 아래에서 다른 프로그램이 실행될 수 있습니다. 이미지를 한 번 가져온 뒤 다이제스트를 확인하십시오.

docker pull ghcr.io/ggml-org/llama.cpp:server

docker pull은 Digest: sha256:... 라인을 출력합니다. 태그 대신 해당 다이제스트를 compose 파일에 입력하면, 다음에 누군가 docker compose pull을 실행하더라도 이미지가 임의로 변경되지 않습니다. 이전 다이제스트를 주석으로 남겨두면 Compose 스택의 업그레이드 및 롤백 루틴에서 다른 서비스를 처리하는 방식과 동일하게 한 번의 수정으로 롤백할 수 있습니다.

핀(pin)의 목적

핀을 사용하면 현재 실행 중인 항목을 정확히 파악할 수 있으며, 변경 사항으로 인해 문제가 발생했을 때 1분 내에 이전 빌드로 되돌릴 수 있습니다. llama.cpp는 빌드 태그와 모델 파일을 별도로 제공하므로, 이 두 가지를 추적하도록 요구합니다. 이 둘을 하나로 묶어 제공하는 런타임은 다르게 동작하며, 서버로서의 Ollama와 llama.cpp 비교에서 이러한 차이를 다룹니다. 전체 시스템에 하나의 버전 번호를 사용하는 방식은 기록하고 관리해야 할 대상이 줄어든다는 장점이 있습니다.

FAQ

bNNNN 빌드 태그와 v0.x 태그 중 무엇을 고정해야 합니까?

어떤 것을 선택하든 고정만 되어 있다면 상관없습니다. b10502와 같은 빌드 태그는 장기 지원 트랙입니다. 모든 사전 빌드 릴리스 아카이브는 이 태그를 기준으로 명명되며, 대부분의 버그 리포트도 이를 인용하므로 다른 운영자와 비교하기에 빌드 번호가 가장 쉽습니다. v0.1.2와 같은 버전 태그는 의도적으로 지정된 짧은 지점들을 나타내며, 일 년에 몇 번만 관리하는 서버에 적합합니다. 선택보다 중요한 것은 태그 문자열이 모델 파일 옆에 기록되어야 한다는 점과, 업그레이드가 git pull의 부작용이 아닌 의도적인 결정이어야 한다는 점입니다.

llama.cpp는 현재 시맨틱 버저닝(Semantic Versioning)을 따르고 있습니까?

아직은 아닙니다. 프로젝트 공식 입장에 따르면, v0.1.2 릴리스 노트에서 시맨틱 버저닝은 여전히 작업 중이며 릴리스 주기와 패치 기준 등을 논의하는 ggml 토론을 참조하라고 명시하고 있습니다. 버전 태그는 관리자가 표시하기로 선택한 지점으로 이해하십시오. 마지막 숫자가 변경되었다고 해서 즉시 교체 가능한 업그레이드라고 가정하지 마십시오. 전환하기 전에 새로운 태그를 자신의 모델 파일로 테스트하십시오.

서버에서 실행 중인 llama.cpp 빌드를 어떻게 확인합니까?

llama-server --version은 버전과 빌드 정보를 출력합니다. 시작 로그 또한 빌드 번호, 커밋 해시, 사용된 컴파일러가 포함된 build 라인으로 시작하므로, journalctl -u llama-server을 사용하면 실행 중인 서비스의 정보를 찾을 수 있습니다. 소스 설치의 경우 고정된 체크아웃 내부에서 git describe --tags을 실행하면 태그가 출력되며, readlink /opt/llama.cpp/current를 통해 서비스가 실제로 어떤 디렉터리를 가리키고 있는지 확인할 수 있습니다.

llama.cpp를 업그레이드한 후 모델이 로드되지 않는 이유는 무엇입니까?

업그레이드 직후 발생하는 로드 실패는 빌드와 GGUF 파일 간의 불일치 때문입니다. 로그의 마지막에는 경로를 명시하는 failed to load model from 라인이 있으며, 그 위쪽 라인에서 로더가 어디까지 읽었는지 확인할 수 있습니다. 최신 모델 파일은 해당 아키텍처를 인식하는 빌드가 필요합니다. 반대로, 파일이 생성된 태그보다 낮은 버전으로 롤백하면 어제까지 작동하던 파일이 손상될 수 있습니다. 심볼릭 링크를 이전 빌드로 다시 연결하고 재시작한 뒤, 어떤 빌드와 파일이 올바르게 쌍을 이루는지 확인하고 나서 둘 중 무엇을 변경할지 결정하십시오.

소스에서 빌드하는 대신 고정할 수 있는 Linux용 사전 빌드 바이너리가 있습니까?

일부 설정에서는 가능합니다. 각 빌드 태그에는 llama-b10502-bin-ubuntu-x64.tar.gz와 같이 해당 태그로 명명된 릴리스 아카이브가 포함되어 있으며, 2026년 8월 19일 기준으로 arm64, s390x, Vulkan, SYCL, OpenVINO 변형이 함께 제공됩니다. 파일 이름에 태그가 포함되어 있어 고정하기 쉽습니다. 해당 목록에는 Linux용 CUDA 아카이브가 없으므로, NVIDIA 서버의 경우 여전히 -DGGML_CUDA=ON를 사용하여 소스에서 빌드하거나 CUDA 컨테이너 이미지를 실행해야 합니다.