llama.cpp v1.0 가이드: 달라진 점과 업그레이드 방법

2026년 11월 13일 공개된 llama.cpp v1.0.0은 시맨틱 버전 규칙을 적용한 첫 안정 버전입니다. 이제 공개 C API를 깨뜨리는 변경에는 메이저 버전 업데이트가 필요합니다. GitHub에서는 이 태그를 Latest로 표시하고 있습니다. 릴리스 노트에 따르면 이번 버전은 API 정리와 호환성 개선에 초점을 맞췄으며, API 삭제와 새로운 캐시, 모델 지원 확대가 함께 포함됐습니다.

v1.0은 속도 향상이 아니라 버전에 대한 약속이다

릴리스 노트의 API 변경 항목에서 호환성을 보장하는 대상은 llama.h의 공개 C API입니다. CLI 플래그와 서버 라우트, 나이틀리 빌드의 동작은 여전히 바뀔 수 있다고 보는 편이 안전합니다. 재현 가능한 빌드가 필요하다면 v1.0.0 태그를 사용하세요. 반대로 최신 수정 사항이 꼭 필요할 때만 커밋별 나이틀리를 선택하면 됩니다. 릴리스 페이지에는 v1.0.0과 함께 나이틀리 b12359도 올라와 있습니다.

「그렇다면 이제 매 릴리스마다 CLI 파라미터를 바꾸는 대신 안정화해서, 어떤 앱도 업스트림을 믿고 쓸 수 없는 상황을 끝내겠다는 뜻인가요?」 — r/LocalLLaMA의 u/halvacoffee

업그레이드 전 확인할 4가지: 오래된 스크립트와 연동 코드

기존 환경에서 가장 자주 문제를 일으키는 호환성 변경입니다. 먼저 아래 문자열부터 검색해 보세요.

grep -rn "llama_set_warmup\|clip\.h\|--mmap\|--no-mmap\|--defrag-thold\|:8080\|localhost:8080" .

1. 삭제된 C 함수 — 바인딩을 업데이트하자

릴리스 노트에 따르면 v1.0에서는 llama.h에서 더 이상 사용되지 않던 함수 35개가 삭제됐습니다. 여기에는 llama_set_warmup도 포함됩니다. 별도로 defrag_thold 필드와 --defrag-thold 옵션도 사라졌습니다. 심볼 하나의 이름도 llama_set_embd_state_src에서 llama_set_ctx_state_src로 변경됐고, NextN API는 llama.h로 승격됐습니다. 전체 삭제 목록은 위에 링크한 릴리스 변경 로그에서 확인할 수 있습니다.

2. 서버 포트가 8080에서 9931로 변경 — URL을 수정하자

이제 llama-server의 기본 주소는 http://127.0.0.1:9931입니다. 기존 예제는 8080을 기준으로 작성된 경우가 많으며, 자세한 내용은 Axiomi 설정 가이드에도 정리돼 있습니다. 헬스 체크와 에디터의 base URL을 새 포트에 맞춰 바꾸거나, 예전 매핑을 유지하려면 --port 8080을 전달하세요.

3. `--mmap`이 거부된다면 — `-lm` 로드 모드로 전환

빌드가 --mmap을 인식하지 못하고 error: invalid argument: --mmap 오류를 내면, 문서에 안내된 대체 옵션인 -lm, --load-mode를 사용하세요. 선택지는 auto, none, mmap, mlock, mmap+mlock, dio입니다. 우선 -lm auto로 시작한 뒤 llama-cli --help와 실제 모델 로딩 테스트로 동작을 확인하면 됩니다.

4. `clip.h` 삭제 — 비전 코드를 `mtmd`로 이전

clip.h를 사용하는 비전 연동 코드는 통합된 mtmd로 옮겨야 합니다. 릴리스 노트에 따르면 mtmd는 여러 서브 컨텍스트 사이에서 연산 버퍼를 공유합니다. 비전 파이프라인을 업그레이드하기 전에는 릴리스 노트의 멀티모달 항목에서 모델별 주의 사항도 확인하세요.

llama.cpp v1.0에서 실제로 달라진 점

릴리스 노트 기준으로 로컬 실행에 특히 의미 있는 추가 기능은 다섯 가지입니다.

기능	무엇을 하는가	대상 사용자
FP8 KV 캐시 (`-ctk/-ctv f8_e4m3`)	긴 컨텍스트에서 `f16`보다 KV 캐시 메모리 사용량을 줄임	VRAM이 빠듯한 환경에서 긴 컨텍스트 대화와 RAG를 사용하는 경우
MoE 전문가 캐시 (`moe_cache_size`, `moe_cache_cpu_share`)	CPU 참여 비율을 설정하면서 전문가를 캐시함	VRAM을 넘어서는 MoE 모델을 실행하는 경우
OpenAI 호환 `/v1/audio/speech` + `/tts` temperature, `drama-3` TTS	서버에서 음성을 생성할 수 있음	클라우드 TTS 없이 로컬 음성 앱을 만들려는 경우
서버 보안 강화 (옵트인 `--allow-unauthenticated-tools`, `--media-allow-private-urls`; CORS, DNS 재바인딩, SSRF, MCP 취소 관련 수정)	로컬호스트 노출과 도구 실행과 관련된 여러 문제를 해결함	`127.0.0.1` 외부 주소에 바인딩하는 경우
새 모델 지원 (Kimi-K3.1-Pro, Ripple-65B-Preview dense 65B, `xing4_0`, 비전 지원 추가)	지원하는 GGUF 모델 범위를 넓힘	해당 모델 출시를 따라가는 사용자

설치부터 OpenAI 호환 서버 실행까지

아래 과정은 공식 설치 문서와 Axiomi 설정 가이드를 바탕으로, 새 기본값인 포트 9931, llama-cli / llama-server, -hf 다운로드 방식을 사용합니다.

1. 설치:

curl -LsSf https://llama.app/install.sh | sh

패키지 매니저를 사용하거나 릴리스 페이지에서 미리 빌드된 ZIP을 내려받아도 됩니다. 설치 후 llama-cli --version으로 확인하세요. 지원되지 않는 하드웨어를 사용하거나, 커스텀 패치 또는 아직 병합되지 않은 수정 사항이 필요하다면 소스에서 직접 빌드하는 편이 낫습니다.

2. 터미널에서 대화:

llama-cli -hf ggml-org/Qwen3.5-0.8B-GGUF -c 8192

Axiomi 가이드에 따르면 -hf는 Hugging Face에서 모델을 캐시합니다. :quant 접미사가 없으면 Q4_K_M을 선택하고, 기본값인 --fit on은 설정되지 않은 값을 장치 메모리에 맞도록 조정합니다.

3. 로컬 API 서버 실행:

llama-server -hf ggml-org/Qwen3.5-0.8B-GGUF -c 8192
# open http://127.0.0.1:9931

지원하는 라우트에는 /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/messages, /v1/audio/speech가 있습니다(Axiomi 라우트 목록). 간단한 동작 확인은 다음 명령으로 할 수 있습니다.

curl http://localhost:9931/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Explain GGUF in one sentence."}]}'

같은 가이드의 Python 예제는 로컬 단일 모델 서버에 base_url="http://localhost:9931/v1"과 api_key="no-key"를 사용합니다. 로컬에서만 사용할 때는 127.0.0.1을 유지하세요.

v1.0, 나이틀리, 래퍼, 호스팅 API 중 무엇을 선택할까?

선택지	이럴 때 선택	주의할 점
`v1.0.0` 고정	앱이나 튜토리얼을 배포하며 재현 가능한 빌드가 필요할 때	11월 13일 이후 병합된 수정 사항은 반영하지 못함
나이틀리 추적 (`b12359`+)	최신 모델 지원이나 백엔드 수정이 필요할 때	플래그와 동작이 여전히 바뀔 수 있음
Ollama / LM Studio	플래그를 직접 다루지 않고 라이브러리나 GUI를 사용하고 싶을 때	레이어, 캐시, 서버 플래그를 직접 제어하는 폭이 대체로 좁음
호스팅 API	탄력적인 서버 운영이 필요하거나 로컬 VRAM 한계를 피하고 싶을 때	일반적으로 토큰당 비용이 발생하며 데이터가 컴퓨터 밖으로 나감

FAQ

v1.0은 안정 버전인가요? 기존 환경도 계속 작동하나요?

안정성이 보장되는 대상은 공개 C API입니다. CLI 플래그와 서버 라우트, 나이틀리 빌드까지 안정적이라는 뜻은 아닙니다. 업그레이드 전에 llama_set_warmup, clip.h, --mmap, --defrag-thold, 하드코딩된 8080을 검색해 보세요.

8B 모델에는 메모리가 얼마나 필요한가요?

Tech Insider의 크기 표에 따르면 8B Q4_K_M 모델은 약 4.9GB, 비양자화 모델은 32.1GB입니다. 이는 컨텍스트와 런타임 메모리를 제외한 수치입니다. 일반적인 기준으로 참고하되, 소형 모델의 CPU 측정값이 그대로 적용되지는 않으므로 llama-bench로 자신의 시스템에서 직접 측정하세요.

배포하는 것은 무엇이든 v1.0에 고정하자

CI에서는 태그를 고정하고, 한 대의 머신은 나이틀리로 운영하세요. 래퍼를 업그레이드하기 전에는 고정해 둔 서버를 기준으로 다시 테스트하는 것도 잊지 마세요.