SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

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

llama.cpp의 bNNNN 빌드 번호와 vX.Y.Z 버전 태그의 차이를 설명합니다. GGUF 모델과 함께 특정 버전을 고정하여 서버 환경의 일관성을 유지하고, 예기치 않은 업데이트 문제를 방지하는 실무적인 관리 전략을 제시합니다.

llama.cpp 버전 체계의 변경 사항

llama.cpp 릴리스를 고정한다는 것은 특정 태그를 빌드하고 해당 이름을 모델 파일 옆에 기록해 두는 것을 의미합니다. 태그는 스스로 변경되지 않으므로, 서버는 오늘 생성한 결과물을 내일도 동일하게 유지합니다. 수년간 선택할 수 있는 태그는 master 브랜치에서 자동으로 생성되는 b10502와 같은 빌드 번호뿐이었습니다. 2026년부터는 v0.6.0과 같은 버전 태그가 추가되었으며, 이 두 트랙은 서로 연동되어 움직이지 않습니다. 빌드 태그는 master 브랜치의 거의 모든 커밋마다 생성됩니다. 반면 버전 태그는 관리자가 수동으로 더 느린 주기에 맞춰 생성하며, 각 버전 릴리스는 그에 대응하는 빌드 태그를 명시합니다.

버전 태그는 초기에는 시험적인 성격이 강했습니다. 2026년 8월 18일에 게시된 v0.1.2의 릴리스 노트에는 다음과 같은 한 줄이 포함되어 있었습니다.

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

3일 후 v0.2.0에서 이 문제가 정리되었습니다. 해당 릴리스 노트는 이 릴리스가 "llama.cpp를 위한 일관된 시맨틱 버전 관리의 시작을 알린다"고 명시합니다. 이들은 vX.Y.Z 태그를 하위 배포판 및 일반 사용자를 위한 안정적인 버전(더 느린 릴리스 주기)으로, b[NUM] 태그를 최신 기능이 포함된 나이틀리(nightly) 또는 개발 빌드(개발자 및 기술 사용자 권장)로 정의합니다. 2026년 11월 14일 기준으로 최신 버전 태그는 11월 13일에 릴리스된 v1.0.0이며, 릴리스 노트는 대응하는 빌드 태그로 b12359을 명시하고 있습니다.

해당 링크의 ggml 토론에는 여전히 이 체계의 근거가 담겨 있으며, 2026년 10월 21일 기준으로 피드백을 받고 있습니다. 버전 번호가 1.x에 도달했으므로, 단순히 숫자가 바뀌었다고 업그레이드 여부를 판단하기보다는 매번 릴리스 노트를 읽어보아야 합니다.

빌드 태그의 숫자는 버전의 의미를 담고 있지 않습니다. 이는 커밋 횟수에서 파생된 값이므로, 사용자의 설정과 관련이 있는지 여부와 관계없이 커밋이 발생할 때마다 자동으로 증가합니다.

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

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

대신 태그를 고정하십시오. 프로젝트 측에서 태그를 생성하며, Windows CUDA 런타임 번들(cudart-llama-bin-win-...)을 제외한 사전 빌드된 릴리스 아카이브의 파일명에는 빌드 태그가 포함되어 있습니다.

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

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

의도적인 지점들을 따라가고 싶다면 버전 태그를 고정하십시오. 현재 프로젝트에서 다운스트림 배포를 위해 권장하는 방식입니다. 각 버전 릴리스는 그에 대응하는 빌드 태그를 명시하며, 미리 빌드된 바이너리도 해당 빌드 태그에 위치하므로 버전 옆에 빌드 번호를 함께 기록해 두십시오. 버전 번호가 1.x에 도달했더라도 업데이트 전에는 반드시 노트를 읽어보시기 바랍니다.

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

고정된 태그 빌드하기

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: 0adcc3b
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는 시작 중에 종료됩니다. 2026년 10월 21일 기준으로 서버 소스 로그는 이에 대해 failed to load model, '/srv/models/model-q4_k_m.gguf'을 출력하며, 쉼표와 함께 작은따옴표로 묶인 경로가 표시됩니다. 마지막으로 출력되는 줄은 exiting due to model loading error이며, 여기에는 경로가 포함되지 않습니다. 전체 줄을 검색하기보다 failed to load model로 저널을 grep하십시오. 로더가 어디까지 진행되었고 왜 중단되었는지 보여주는 로더 자체의 error loading model: 줄을 포함하여, 그 직전에 출력된 줄들을 읽어보십시오. GGUF는 헤더에 형식 버전을 포함합니다(현재 사양 값은 3이며, 버전 2에서는 길이 필드가 32비트에서 64비트로 확장되었습니다). 하지만 실제로는 형식 버전보다 알 수 없는 아키텍처 이름 때문에 훨씬 먼저 중단됩니다. 해결책은 더 최신 태그를 선택하여 기록해 두는 것입니다.

서버 플래그의 이름이 변경되거나 폐기되었습니다. 인식할 수 없는 플래그는 무시되지 않고 시작 시 llama-server를 중단시킵니다. systemd 환경에서는 서비스가 시작과 종료를 반복하는 것처럼 보입니다. journalctl -u llama-server -n 50를 확인하면 실제 메시지를 볼 수 있습니다. 2026년 8월 19일 기준으로 서버 문서에서는 -lm, --load-mode을 위해 --mlock과 --mmap을 폐기된 것으로 표시했습니다. 2026년 10월 21일 기준으로 두 플래그 모두 서버 문서나 마스터 브랜치의 인수 목록에 더 이상 나타나지 않으므로, auto(기본값), none, mmap, mlock, mmap+mlock, dio를 인수로 받는 --load-mode를 사용하여 해당 동작을 수행하십시오. GPU 오프로드 플래그는 -ngl, --gpu-layers, --n-gpu-layers으로 문서화되어 있으므로, 이전 가이드에 나오는 긴 철자도 여전히 허용됩니다. 기본값도 변경됩니다. v0.7.0부터 llama-server은 기본적으로 8080 대신 9931 포트에서 수신 대기합니다(Docker 이미지는 컨테이너 내부에서 8080을 유지합니다). 따라서 --port를 생략한 유닛 파일은 리버스 프록시가 예상하는 위치에서 응답하지 않게 됩니다. v1.0.0 릴리스에서는 폐기된 --defrag-thold 플래그도 제거되었습니다. 심볼릭 링크를 이동하기 전에 /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에서 실행됩니다. llama-bench을 확인하면 backend 열이 CPU으로 표시되므로 즉시 알 수 있습니다.

가속기 빌드는 이식성이 없습니다. 2026년 8월 19일 기준으로 빌드 태그에 첨부된 Linux 에셋은 x64, arm64, s390x용 CPU, Vulkan, SYCL, OpenVINO 변형이었으며 Linux용 CUDA 아카이브는 없었습니다. 그 후 상황이 바뀌었습니다. 2026년 10월 21일 기준으로 v0.7.0의 기반이 되는 빌드 태그인 b11669는 x64용 CUDA 12.8 및 13.4, arm64용 CUDA 13.4에 대한 Ubuntu CUDA 아카이브를 포함하며, 각각 일치하는 cudart- 런타임 아카이브와 ROCm 빌드를 제공합니다. CUDA 아카이브는 Linux와 Windows 모두에서 툴킷 버전별로 게시되는데, 이는 유용한 힌트가 됩니다. 툴킷 버전은 바이너리를 식별하는 요소 중 하나이므로 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와 같은 빌드 태그는 장기 지원 트랙입니다. 미리 빌드된 릴리스 아카이브의 파일명에 이 태그가 포함되며(Windows CUDA 런타임 번들 제외), 대부분의 버그 리포트도 이를 인용하므로 빌드 번호가 다른 운영자와 비교하기 가장 쉽습니다. v0.6.0과 같은 버전 태그는 프로젝트가 다운스트림 배포를 위해 권장하는 신중하게 선택된 지점들의 짧은 목록이며, 일 년에 몇 번만 관리하는 서버에 적합합니다. 각 버전 태그는 대응하는 빌드 태그를 명시하므로 둘 다 기록해 두십시오. 선택보다 중요한 것은 태그 문자열을 모델 파일 옆에 기록해 두는 것과, 업그레이드가 git pull의 부작용이 아닌 의도된 결정이어야 한다는 점입니다.

llama.cpp는 이제 시맨틱 버저닝을 따릅니까?

네, 2026년 8월 21일 v0.2.0 이후부터 그렇습니다. 릴리스 노트에 따르면 이는 llama.cpp의 일관된 시맨틱 버저닝의 시작을 의미하며, v0.1.2가 가졌던 작업 중이라는 경고를 대체합니다. 2026년 11월 14일 기준으로 버전 번호는 1.x에 도달했으며, 11월 13일에 릴리스된 v1.0.0가 최신 버전입니다. 이동하기 전에 릴리스 노트를 읽고, 어떤 숫자가 변경되었든 상관없이 새로운 태그를 자신의 모델 파일로 테스트한 뒤 전환하십시오.

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

llama-server --version은 버전과 빌드 정보를 출력하므로, 서비스가 사용하는 바이너리에 대해 /opt/llama.cpp/current/bin/llama-server --version을 실행하십시오. 2026년 10월 21일 시점에 빌드 번호, 커밋 해시, 컴파일러 정보를 포함하는 시작 라인은 trace 레벨로 기록되므로, 기본 로그 레벨의 journalctl -u llama-server에서 해당 정보를 찾을 수 있다고 기대하지 마십시오. 소스 설치의 경우, 고정된 체크아웃 내부의 git describe --tags는 태그를 출력하며, readlink /opt/llama.cpp/current은 서비스가 실제로 가리키고 있는 디렉터리를 보여줍니다.

llama.cpp 업그레이드 후 모델 로드가 중단된 이유는 무엇입니까?

업그레이드 직후의 로드 실패는 빌드와 GGUF 파일 간의 불일치 때문입니다. 로그에는 파일명을 명시하는 failed to load model, '<path>' 라인이 포함되어 있고 exiting due to model loading error로 끝나며, 그 위의 라인들은 로더가 어디까지 읽었는지 보여줍니다. 앞으로 나아갈 때, 매우 새로운 모델 파일은 해당 아키텍처를 인식하는 빌드가 필요합니다. 뒤로 돌아갈 때, 파일이 생성된 태그보다 낮은 버전으로 롤백하면 어제까지 작동하던 파일이 손상될 수 있습니다. 심볼릭 링크를 이전 빌드로 가리키고 재시작한 뒤, 둘 중 무엇을 변경할지 결정하기 전에 어떤 빌드와 파일이 올바르게 쌍을 이루는지 확인하십시오.

빌드하는 대신 고정할 수 있는 미리 빌드된 Linux 바이너리가 있습니까?

네. 각 빌드 태그는 llama-b10502-bin-ubuntu-x64.tar.gz과 같이 해당 태그의 이름이 붙은 릴리스 아카이브를 포함하므로, 파일명에 태그가 있어 고정하기 쉽습니다. 2026년 8월 19일 기준으로 Linux 세트는 CPU, arm64, s390x, Vulkan, SYCL, OpenVINO였으며 CUDA 아카이브는 없었습니다. 2026년 10월 21일 기준으로 더 새로운 b11669는 Ubuntu CUDA 12.8 및 13.4 아카이브와 그에 대응하는 cudart- 런타임 번들도 포함하므로, 최신 태그를 사용하는 NVIDIA 서버는 더 이상 -DGGML_CUDA=ON으로 소스에서 빌드하거나 CUDA 컨테이너 이미지를 실행할 필요가 없습니다. 버전 태그를 고정하는 경우, 해당 릴리스 노트에 명시된 빌드 태그에서 아카이브를 다운로드하십시오.

이 글이 도움이 되었나요?