본문 바로가기
삵
AI

llama.cpp 1.0으로 올리기

sstdio.h·2026년 11월 19일·조회 0

로컬 모델을 llama-server로 서빙해 온 지 꽤 됐는데, 그동안 llama.cpp는 날짜 기반 빌드 번호(b4000 같은)로만 굴러왔다. 바인딩을 짜 둔 쪽에서는 빌드 하나 올릴 때마다 뭔가 조용히 바뀌지 않았을까 신경이 쓰였다. 그 불편을 2026년 11월 13일에 나온 v1.0.0이 정리했다.

결론부터 말하자면, 1.0은 공개 C API에 처음으로 시맨틱 버전 규칙을 건 릴리스다. 메이저 올림은 공개 C API가 깨지는 변경, 마이너는 호환되는 기능 추가, 패치는 API 변화 없는 버그 수정으로 못 박았다. 그 대가로 1.0은 쌓여 있던 deprecated 함수 35개를 한 번에 걷어냈고, llama-server가 네트워크에 노출된 채 도구를 켜면 API 키를 강제한다. 반대로 FP8 KV 캐시와 호스트 메모리 MoE 전문가 캐시가 들어와, 작은 VRAM에서 큰 MoE 모델을 돌릴 여지가 넓어졌다.

여기서 시맨틱 버전이 보장하는 범위를 먼저 짚어 둘 필요가 있다. 규칙은 include 디렉터리의 공개 C API에만 적용된다. 즉 libllama를 링크해 쓰는 코드는 메이저가 같은 동안 심볼이 안 바뀌지만, llama-server의 명령행 플래그나 CLI 동작까지 보장해 주지는 않는다. 스크립트와 systemd 유닛은 여전히 릴리스 노트를 보고 손봐야 한다.

1. 제거된 deprecated 함수와 soname 변경

바인딩을 직접 유지하는 쪽에는 이게 가장 큰 벽이다. 1.0은 오래 deprecated로 표시돼 있던 함수 35개와 llama_set_warmup을 제거했다. 공개 심볼이 255개에서 237개로 줄었고, soname도 libllama.so.0에서 libllama.so.1로 올라갔다.

soname이 바뀌었으니 예전 바이너리는 새 라이브러리를 자동으로 집지 못한다. 먼저 내 코드가 사라진 심볼을 참조하는지부터 확인한다.

$ nm -D /usr/lib/libllama.so.0 | grep -E 'llama_load_model_from_file|llama_new_context_with_model|llama_n_vocab'
0000000000042a10 T llama_load_model_from_file
0000000000042c30 T llama_new_context_with_model
0000000000039f80 T llama_n_vocab

1.0으로 올린 뒤 같은 심볼을 찾으면 비어 있고, 이 함수들을 부르던 코드는 컴파일 단계에서 막힌다.

$ g++ app.cpp -lllama -o app
app.cpp: In function 'int main()':
app.cpp:14:18: error: 'llama_load_model_from_file' was not declared in this scope
   14 |     auto * model = llama_load_model_from_file(path, mparams);
      |                    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~

대응은 기계적이다. deprecated 함수 대부분은 이미 1.0 이전에 새 이름이 들어와 있었고, 1.0은 옛 이름만 떼어 냈다. 자주 걸리는 교체를 정리하면 아래와 같다.

제거된 함수대체
llama_load_model_from_file, llama_free_modelllama_model_load_from_file, llama_model_free
llama_new_context_with_modelllama_init_from_model
llama_n_vocab, llama_token_*llama_model_get_vocab()에 llama_vocab_* 적용
llama_n_ctx_train, llama_n_embd, llama_n_layerllama_model_n_* 계열
llama_add_bos_token, llama_add_eos_tokenllama_vocab_get_add_bos, llama_vocab_get_add_eos
llama_set_warmup대체 없음, 더미 디코드로 직접 워밍업

llama_set_warmup만 대체가 없다. 모델 로드 직후 짧은 더미 토큰을 한 번 디코드해서 커널과 할당을 미리 데우는 식으로 직접 흉내 내야 한다.

헤더 쪽 변화도 같이 챙긴다. NextN 투기적 디코딩 API가 확장 헤더 llama-ext.h에서 공개 헤더 llama.h로 승격됐고, 멀티모달용 clip.h는 제거돼 mtmd 쪽으로 옮겨졌다. 컨텍스트 상태 복원 함수 llama_set_embd_state_src는 llama_set_ctx_state_src로 이름이 바뀌었다.

CLI 쪽에서는 KV 캐시 조각 모음 임계치를 설정하던 --defrag-thold(-dt)가 통째로 사라졌다. 유닛 파일에 남아 있으면 기동이 바로 멈춘다.

$ llama-server -m model.gguf --defrag-thold 0.1
error: invalid argument: --defrag-thold

환경 변수 LLAMA_ARG_DEFRAG_THOLD로 넘기면 에러 없이 조용히 무시된다. 그래서 systemd 유닛과 compose 파일에서 이 옵션을 먼저 지우고 올리는 게 깔끔하다.

2. 네트워크에 노출하면 API 키를 요구한다

llama-server는 본래 --api-key를 주기 전까지 인증이 없다. 그래서 --host 0.0.0.0으로 다른 장비에서도 닿게 열어 두면, 같은 네트워크의 누구나 내 GPU를 쓸 수 있었다. 1.0은 이 구멍 중 위험한 조합 하나를 막았다.

정확히 말하면, 도구 호출이나 MCP를 켠 상태에서 호스트가 루프백이 아니고 API 키도 없으면 서버가 아예 뜨지 않는다. 예전 빌드에서 잘 돌던 명령이 1.0에서는 이렇게 끊긴다.

$ llama-server -m model.gguf --host 0.0.0.0 --port 8080 --jinja --tools all
error: server tools, MCP servers or MCP proxy are enabled on a non-loopback address without an API key

해결은 셋 중 하나다. 가장 곧은 길은 키를 주는 것이다.

$ export LLAMA_API_KEY="$(openssl rand -hex 24)"
$ llama-server -m model.gguf --host 0.0.0.0 --port 8080 --jinja --tools all --api-key "$LLAMA_API_KEY"

클라이언트는 Authorization: Bearer <키>를 실어 보내고, 키가 틀리면 401이 돌아온다.

$ curl -s http://server:8080/v1/chat/completions -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_API_KEY" \
  -d '{"messages":[{"role":"user","content":"ping"}]}' | head -c 80

격리된 사내망이라 키 없이 돌리겠다면 --allow-unauthenticated-tools로 명시적으로 열 수 있다. 이 플래그를 붙여야만 도구와 MCP가 루프백 밖에서 키 없이 동작한다. 세 번째는 --host 127.0.0.1로 묶고 앞단에 리버스 프록시나 SSH 터널을 두는 방법이다.

여기서 오해하기 쉬운 부분이 있다. 이 강제는 도구와 MCP를 켠 경우에만 걸린다. --tools 없이 평범한 /v1/chat/completions만 쓴다면 0.0.0.0에 열어도 서버는 뜨고, 대신 "no API key is set and CORS allows all origins" 경고만 뜬다. 노출된 포트를 그대로 쓰라는 뜻은 아니니 경고를 봤다면 키를 거는 게 맞다. 비전 파이프라인에서 사설 주소의 이미지 URL을 쓰려면 --media-allow-private-urls도 따로 열어야 한다.

3. FP8 KV 캐시로 컨텍스트 메모리 줄이기

KV 캐시는 지금까지 디코드한 토큰의 키와 값 벡터를 들고 있는 버퍼다. 컨텍스트가 길어질수록 선형으로 커져서, 긴 입력을 받는 서버에서는 이 버퍼가 VRAM을 꽤 먹는다. 1.0은 여기에 OCP FP8(e4m3) 포맷을 얹었다.

키 캐시와 값 캐시 타입을 f8_e4m3로 지정하면 켜진다.

$ llama-server -m model.gguf -c 32768 -ctk f8_e4m3 -ctv f8_e4m3 --host 127.0.0.1

FP8은 요소당 1바이트라 기본값인 f16(2바이트)의 절반 수준으로 KV 캐시가 줄어든다. 실제 절감폭은 모델과 컨텍스트 길이에 따라 다르지만, 기동 로그의 KV buffer size 줄을 f16으로 띄웠을 때와 비교하면 바로 확인된다.

$ llama-server -m model.gguf -c 32768 -ctk f8_e4m3 -ctv f8_e4m3 2>&1 | grep -i 'KV buffer'

함정이 하나 있다. FP8 KV 캐시는 백엔드마다 지원이 다르다. CPU 추론에서는 잘 동작하지만, 일부 GPU 백엔드는 값 캐시의 FP8 연산을 아직 못 받는다. Metal에서 값 캐시를 FP8로 띄우면 이런 에러로 멈춘다.

error: pre-allocated tensor (cache_k_l0 (view)) in a buffer (MTL0) that cannot run the operation (SET_ROWS)

이럴 때 돌아갈 자리가 있다. 기존 q8_0 양자화 캐시는 GPU에서 잘 돌면서 압축률도 FP8과 비슷하다. GPU 백엔드에서 FP8이 막히면 -ctk q8_0 -ctv q8_0으로 바꿔 쓰는 쪽이 현실적이다. 한 가지 더, 값 캐시를 양자화하면 프롬프트 처리는 크게 빨라지는 대신 생성 속도는 환경에 따라 조금 떨어질 수 있으니, 긴 입력 위주인지 긴 출력 위주인지 보고 정한다.

4. 호스트 메모리 MoE 전문가 캐시로 큰 모델 얹기

MoE(전문가 혼합) 모델은 레이어마다 전문가 여러 개를 두고 토큰마다 그중 몇 개만 활성화한다. 전체 파라미터는 수백억대라도 한 토큰에 실제로 도는 전문가는 소수라, 나머지 식은 전문가 가중치는 VRAM 대신 시스템 RAM에 내려 두고 필요할 때만 올려도 된다. 이 발상을 구현한 게 --n-cpu-moe다.

--n-cpu-moe N은 앞쪽 N개 레이어의 전문가 FFN 가중치를 호스트 메모리에 둔다. 라우팅과 어텐션, KV 캐시는 GPU에 남고 식은 전문가만 CPU RAM에서 PCIe로 흘러온다. N을 키우면 VRAM을 덜 쓰는 대신 토큰당 CPU 작업이 늘고, 줄이면 더 많은 전문가가 GPU에 남아 생성이 빨라진다.

$ llama-server -m Qwen3-235B-A22B-Q4_K_M.gguf -c 16384 \
  -ngl 999 --n-cpu-moe 999 \
  -ctk f8_e4m3 -ctv f8_e4m3 --host 127.0.0.1

--n-cpu-moe 999는 사실상 모든 레이어의 전문가를 CPU에 두라는 뜻이고, 전부 CPU에 몰 거면 --cpu-moe를 써도 된다. 튜닝은 간단하다. N을 큰 값에서 하나씩 줄여 VRAM이 모자라 터지기 직전까지 내린 다음, 한 칸 되돌린 값이 그 장비의 최적점이다.

1.0은 여기에 호스트 메모리 전문가 캐시를 더해, 캐시 미스가 났을 때 전문가를 GPU로 올리는 대신 CPU에서 계산할 비율을 조절하게 했다. 이 비율은 --moe-cache-cpu-share로 준다(기본 0, 0에서 1 사이).

$ llama-server -m Qwen3-235B-A22B-Q4_K_M.gguf -c 16384 \
  -ngl 999 --n-cpu-moe 40 --moe-cache-cpu-share 0.5 \
  -ctk f8_e4m3 -ctv f8_e4m3 --host 127.0.0.1

플래그 이름은 빌드에 따라 조금씩 다를 수 있으니, 올린 직후 llama-server --help | grep -i moe로 실제 노출된 옵션부터 확인하고 쓰는 게 안전하다.

FP8 KV 캐시로 컨텍스트 버퍼를 줄이고, 전문가 가중치를 호스트 메모리로 내리는 두 가지를 겹치면, 24GB급 GPU 한 장으로도 Q4 양자화한 200억 활성 규모 MoE 모델을 긴 컨텍스트로 띄울 수 있다. 정확한 한계는 모델과 양자화, 메인보드 대역폭에 따라 달라지니 위 명령을 기준으로 N과 컨텍스트를 조금씩 올려 가며 맞춘다.

올리기 전 점검

정리하면, 바인딩을 쓰는 쪽은 사라진 심볼을 nm으로 먼저 확인하고 새 이름으로 바꾼 뒤 libllama.so.1에 맞춰 다시 빌드한다. 서버만 쓰는 쪽은 유닛 파일에서 --defrag-thold를 지우고, 네트워크에 도구나 MCP를 여는 설정이면 --api-key를 추가한다. 그다음 FP8 KV 캐시와 MoE 전문가 캐시를 새로 얹을지 결정하면 된다. 가장 먼저 할 일은 지금 돌리는 명령줄에서 --defrag-thold와 키 없는 --tools 조합이 있는지 한 번 훑는 것이다.

자주 묻는 질문

llama.cpp 1.0으로 올리면 기존 systemd 유닛이 바로 깨지나?

도구나 MCP를 켜지 않은 평범한 서빙 설정이면 대개 그대로 뜬다. 다만 유닛에 --defrag-thold(-dt)가 남아 있으면 1.0은 invalid argument 에러로 기동을 멈추므로 먼저 지워야 한다. 그리고 --host 0.0.0.0에 --tools나 MCP를 켠 설정은 --api-key 없이는 더 이상 시작하지 않는다.

deprecated 함수 35개 제거에 어떻게 대응하나?

대부분 1.0 이전부터 새 이름이 들어와 있었다. llama_load_model_from_file은 llama_model_load_from_file로, llama_new_context_with_model은 llama_init_from_model로, llama_n_vocab 같은 함수는 llama_model_get_vocab()에 llama_vocab_* 적용으로 바꾼다. llama_set_warmup만 대체가 없어 더미 디코드로 직접 워밍업해야 한다. soname이 libllama.so.1로 올랐으니 다시 빌드도 필요하다.

llama-server를 0.0.0.0에 열면 무조건 API 키가 필요한가?

도구 호출이나 MCP를 켠 경우에만 강제된다. 그 조합에서 루프백이 아닌 호스트에 키가 없으면 서버가 아예 뜨지 않는다. --tools 없이 일반 채팅 엔드포인트만 쓰면 0.0.0.0에서도 뜨지만, 키 미설정 경고가 뜨므로 노출 환경에서는 키를 거는 게 맞다.

FP8 KV 캐시가 GPU에서 안 켜진다.

FP8 KV 캐시는 백엔드마다 지원이 다르다. CPU에서는 동작하지만 일부 GPU 백엔드는 값 캐시 FP8 연산을 아직 못 받고, Metal에서는 SET_ROWS 관련 에러로 멈춘다. 이럴 때는 -ctk q8_0 -ctv q8_0으로 바꾸면 GPU에서 돌면서 압축률도 비슷하다.

FP8 KV 캐시와 MoE 전문가 캐시를 같이 쓰면 얼마나 큰 모델을 돌릴 수 있나?

환경에 따라 다르지만, FP8로 KV 캐시를 절반 수준으로 줄이고 --n-cpu-moe로 전문가 가중치를 호스트 메모리에 내리면 24GB급 GPU 한 장으로 Q4 양자화한 대형 MoE 모델을 긴 컨텍스트로 띄울 수 있다. 정확한 한계는 양자화 레벨과 메인보드 대역폭에 좌우되므로 N과 컨텍스트를 조금씩 올려 맞춘다.

관련 글

댓글 0

로그인 후 댓글을 남길 수 있습니다.

아직 댓글이 없습니다.