llama.cpp 1.0.0 업그레이드: API 변경, FP8 KV 캐시와 서버 보안

llama.cpp와 ggml을 1.0.0으로 업그레이드하면서 로컬 코딩 에이전트의 오류를 방지하는 방법을 설명합니다. 제거된 C API와 --defrag-thold를 수정하고 FP8 KV 캐시의 메모리 절감 효과를 비교하며 MoE 전문가 캐시를 조정합니다. llama-server의 도구 인증, 비공개 URL 접근 제한, 버전 고정 방법도 다룹니다. Ollama와 LM Studio 사용자가 언제 업데이트해야 하는지도 확인할 수 있습니다.

목차
llama.cpp 1.0.0 업그레이드: API 변경, FP8 KV 캐시와 서버 보안

llama.cpp 1.0.0으로 업그레이드하기 전에 C 바인딩, 실행 옵션, llama-server의 보안 설정을 확인해야 합니다. 2026년 11월 13일 출시된 이 버전은 사용 중단된 API를 제거하고 FP8 KV 캐시와 새로운 MoE 전문가 캐시 제어 기능을 추가했습니다. 서버 도구와 비공개 미디어 URL에 대한 명시적 보안 허용 옵션도 도입했습니다. 로컬 코딩 모델을 llama-server로 제공한다면 먼저 테스트 환경을 업그레이드하고 일반 응답과 도구 호출이 모두 작동하는지 확인하세요.

이번 릴리스부터 libllama와 libggml의 버전 관리 규칙도 명확해졌습니다. 앞으로 공개 C API의 호환성을 깨는 변경은 MAJOR 버전 증가가 필요합니다.

이 규칙으로 향후 의존성 업데이트의 위험을 판단하기 쉬워집니다. 다만 모델 출력, 추론 속도, GPU 백엔드 동작 또는 모든 HTTP 엔드포인트의 동작까지 동일하게 유지된다는 뜻은 아닙니다.

llama.cpp 1.0.0에서는 무엇이 바뀌었나요?

이번 변경은 llama.cpp를 애플리케이션에 직접 통합하는 개발자, llama-server 운영자, 로컬 추론의 메모리 사용량을 최적화하는 개발자에게 영향을 줍니다.

영역1.0.0 변경 사항필요한 조치
버전 관리공개 C API 및 ABI의 비호환 변경은 MAJOR 버전 증가로 구분프로덕션에서 릴리스나 커밋 고정
C API사용 중단된 함수 35개와 llama_set_warmup 제거바인딩 수정 후 다시 빌드
컨텍스트 설정defrag_thold와 --defrag-thold 제거오래된 설정 삭제
추측 디코딩NextN API를 llama.h로 이동하고 상태 관련 함수 이름 변경include와 함수 참조 업데이트
KV 캐시K와 V 캐시에 f8_e4m3 지원 추가메모리, 품질, 백엔드 호환성 측정
MoE 추론GPU 전문가 캐시와 CPU의 일부 캐시 미스 처리 지원GPU 가용성과 캐시 크기 및 CPU 비율 확인
서버 보안도구 인증과 비공개 미디어 URL 접근 제한네트워크 노출과 인증 설정 점검
모델 지원Kimi-K3.1-Pro, Ripple, xing4_0 및 멀티모달 기능 추가모델 변환과 로딩 조건 확인
음성 APIOpenAI 호환 /v1/audio/speech 추가지원되는 음성 모델로 테스트

자세한 내용은 v1.0.0 공식 릴리스 노트와 버전 관리 정책 발표에 나와 있습니다.

프로젝트는 150개가 넘는 모델 아키텍처 변형을 지원한다고 발표했습니다. 하지만 모든 체크포인트와 기능이 모든 백엔드에서 동작한다는 보장은 아닙니다.

앞으로 시맨틱 버전 관리는 어떻게 적용되나요?

새로운 호환성 정책은 llama.cpp와 ggml의 ./include에 있는 공개 C 인터페이스에 적용됩니다.

관리자는 버전 변경을 세 가지로 구분합니다.

버전 구분적용 조건예시
MAJOR공개 C API와 호환되지 않는 변경1.x.x에서 2.0.0
MINOR하위 호환 기능, 새 백엔드, 모델 또는 API 추가1.0.0에서 1.1.0
PATCHAPI 변경이 없는 버그 수정1.0.0에서 1.0.1

표의 버전은 규칙을 설명하기 위한 예시입니다. 앞으로 출시될 버전을 예고한 것은 아닙니다.

libllama에 의존하는 애플리케이션에서는 동일한 MAJOR 버전 안에서 공개 함수 시그니처가 예고 없이 바뀔 위험이 줄어듭니다.

그러나 내부 헤더, 문서화되지 않은 심벌, CLI 인수, HTTP 응답의 세부 구조, 모델 동작까지 같은 호환성 정책이 적용되는 것은 아닙니다.

llama.cpp 버전은 어떻게 고정하나요?

llama.cpp를 애플리케이션의 의존성으로 빌드할 때는 정확한 릴리스 태그나 변경되지 않는 커밋을 사용합니다.

공식 빌드 가이드는 Git으로 소스를 가져오고 CMake로 빌드하는 방법을 설명합니다. 여기에 v1.0.0 태그를 선택하는 단계를 추가합니다.

Bash 예시입니다.

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git fetch --tags
git checkout v1.0.0

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

이 명령은 문서에 나온 기본 CPU 빌드 절차를 따릅니다. 플랫폼에 따라 다른 백엔드가 기본으로 활성화될 수도 있습니다. 실제 실행 장치를 판단하기 전에 빌드 구성을 확인하세요.

표준 빌드에서 서버 실행 파일의 경로는 ./build/bin/llama-server입니다. 일부 플랫폼이나 CMake 생성기에서는 결과물 경로가 다를 수 있습니다.

GPU가 필요하다면 해당 백엔드의 공식 CMake 옵션을 추가하세요.

프로덕션에서는 릴리스 태그, Git 커밋 해시, 빌드 옵션, 실행 백엔드를 기록합니다. 정상 작동하는 바이너리를 교체하기 전에 새 빌드를 검증하세요.

애플리케이션이 자체 llama.cpp 소스를 포함한다면 래퍼나 애플리케이션 버전도 고정해야 합니다. 내부에 포함된 llama.cpp 리비전과 버전 번호가 다를 수 있습니다.

제거된 API와 명령줄 옵션은 무엇인가요?

업그레이드 과정에서 가장 먼저 처리할 항목은 오래된 C 인터페이스와 조각 모음 임계값 설정입니다.

PR #30565의 API 정리에서는 사용 중단된 함수 35개, llama_set_warmup, 기존 조각 모음 임계값 설정을 제거했습니다.

다음 항목을 확인하세요.

  • llama_set_warmup 호출을 제거합니다.
  • 컨텍스트 구성에서 defrag_thold를 삭제합니다.
  • 시작 스크립트에서 --defrag-thold를 제거합니다.
  • 해당하는 경우 llama_set_embd_state_src를 llama_set_ctx_state_src로 변경합니다.
  • llama.h로 이동한 NextN API의 include와 선언을 업데이트합니다.

제거된 함수 35개에 각각 일대일 대체 함수가 있다는 뜻은 아닙니다. v1.0.0의 헤더 변경 사항을 실제 바인딩에서 사용하는 심벌과 비교하세요.

—defrag-thold를 사용하는 스크립트 수정

이전 버전에서는 다음과 같이 서버를 시작했을 수 있습니다.

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --defrag-thold 0.1

1.0.0에서는 제거된 옵션을 제외합니다.

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768

다른 임계값을 선택할 필요가 없습니다. 매개변수 자체가 제거되었습니다. 문서에 없는 대체 옵션을 임의로 추가하지 마세요.

셸 스크립트, Docker 구성, 서비스 정의, 애플리케이션 소스에서 오래된 이름을 검색합니다.

grep -RInE \
  'defrag[_-]thold|llama_set_warmup|llama_set_embd_state_src' \
  ./scripts ./config ./src

검색 디렉터리는 실제 프로젝트 구조에 맞게 변경하세요. 존재하지 않는 경로는 명령에서 제외합니다.

환경 변수나 래퍼 설정이 오래된 실행 옵션을 자동으로 생성하는지도 확인해야 합니다.

C와 Python 바인딩 업데이트

llama.h를 직접 참조하는 애플리케이션이라면 다시 빌드하기 전에 코드를 v1.0.0 헤더와 비교합니다.

CMake 기반 애플리케이션은 새 라이브러리에 맞춰 다시 빌드하고 컴파일러와 링커의 출력을 확인하세요.

Python 래퍼를 사용할 때는 해당 버전이 llama.cpp 1.0.0을 명시적으로 지원하는지 먼저 확인합니다.

llama.cpp 바이너리를 교체한다고 해서 Python 확장 모듈에 컴파일된 함수 정의까지 자동으로 갱신되지는 않습니다.

래퍼가 자체적으로 llama.cpp 소스를 포함한다면 래퍼에서 제공하는 업데이트 절차를 따르세요. 호환성을 확인하지 않고 공유 라이브러리만 수동으로 교체하지 마세요.

import 성공은 초기 점검에 불과합니다. 모델을 로드하고 토큰을 생성한 다음, 애플리케이션에서 사용하는 컨텍스트 상태나 추측 디코딩 기능을 테스트해야 합니다.

llama.cpp 1.0.0에서 FP8 KV 캐시를 활성화하는 방법

Attention의 key와 value를 FP8 형식으로 저장하려면 -ctk f8_e4m3 -ctv f8_e4m3를 지정합니다.

KV 캐시는 이전 토큰에서 계산한 정보를 보관합니다. 덕분에 모델은 전체 이전 컨텍스트를 다시 계산하지 않고 다음 토큰을 생성할 수 있습니다.

일반적으로 컨텍스트가 길수록 KV 캐시에 필요한 메모리도 늘어납니다.

FP8은 값 하나를 저장할 때 8 bits를 사용합니다. FP16은 16 bits를 사용합니다. 텐서 크기가 같다면 K/V 원시 데이터의 저장 공간이 이론적으로 거의 절반으로 줄어들 수 있습니다.

이 계산에는 메타데이터, 스케일 정보, 메모리 정렬, 모델 가중치, 연산 버퍼 등이 포함되지 않습니다. 따라서 전체 VRAM 사용량이 절반이 된다는 의미는 아닙니다.

먼저 FP16을 기준으로 측정하기

두 테스트에서 동일한 모델과 컨텍스트 크기를 사용하세요.

먼저 FP16으로 서버를 시작합니다.

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  -ctk f16 \
  -ctv f16

로그에 표시된 KV 버퍼 할당량을 기록하세요. 사용 가능한 장치 메모리, 프롬프트 처리 속도, 토큰 생성 속도도 측정합니다.

서버를 중지한 후 FP8으로 다시 시작합니다.

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  -ctk f8_e4m3 \
  -ctv f8_e4m3

이번 릴리스에서는 FP8 KV 캐시에 선택적으로 적용할 수 있는 정적 per-tensor scale도 지원합니다.

시작 로그에서 선택된 캐시 타입과 메모리 할당량을 확인하세요. 명령줄 값이 인식되더라도 GPU 백엔드의 모든 최적화 연산 경로가 지원된다고 단정할 수는 없습니다.

FP8을 사용하면 컨텍스트 길이를 두 배로 늘릴 수 있나요?

반드시 그런 것은 아닙니다.

FP8은 KV 텐서에 필요한 저장 공간을 줄입니다. 그러나 컨텍스트 길이에는 모델이 지원하는 한계와 사용 가능한 메모리의 제약이 여전히 적용됩니다.

가상의 작업에서 FP16 KV 캐시가 8 GiB를 사용한다고 가정해 보겠습니다. 같은 차원의 텐서를 FP8로 저장하면 원시 데이터가 약 4 GiB로 줄어들 수 있습니다.

이는 이론적 메모리 계산이며 llama.cpp에서 직접 측정한 결과가 아닙니다.

확보한 메모리로 더 긴 컨텍스트나 더 많은 동시 요청을 처리할 수도 있습니다. 하지만 모델이 지원하는 유효 컨텍스트 한계를 넘어설 수는 없습니다.

FP8은 정밀도가 낮은 표현 방식이기도 합니다. 공식 릴리스 자료는 코딩 품질이나 도구 호출 정확도에 대한 보편적인 FP8 평가 결과를 제시하지 않습니다.

코딩 에이전트에서는 두 캐시 형식을 동일한 저장소 작업으로 비교하세요.

  1. 긴 소스 파일에서 필요한 심벌을 찾습니다.
  2. 여러 파일에 걸친 변경을 작성합니다.
  3. 구조화된 도구 호출을 생성합니다.
  4. 긴 대화를 여러 차례 진행한 후 작업을 이어갑니다.

초당 생성 토큰 수뿐 아니라 코드의 정확성과 도구 인수 파싱 결과도 확인해야 합니다.

새로운 MoE 전문가 캐시는 어떻게 동작하나요?

MoE 캐시는 Mixture-of-Experts 모델의 전문가 가중치 일부를 GPU 메모리 대신 시스템 RAM에 저장할 때 도움이 될 수 있습니다.

MoE 모델은 토큰마다 일부 전문가만 선택합니다. 필요한 가중치를 RAM에서 GPU로 반복 전송하면 디코딩 비용이 커질 수 있습니다.

새 캐시는 자주 사용하는 CPU 상주 전문가를 GPU 메모리에 유지합니다. 캐시 미스 중 일부를 CPU에서 직접 계산하도록 설정할 수도 있습니다.

이는 FP8 KV 캐시와 별개의 기능입니다. MoE 캐시는 전문가 가중치를 관리하고 KV 캐시는 Attention 상태를 저장합니다.

공식 MoE 캐시 가이드는 다음 옵션을 설명합니다.

옵션기능기본값
-cmoe모든 MoE 전문가 가중치를 CPU 메모리에 유지지정하지 않으면 비활성화
--moe-cache-mib NCPU 상주 전문가를 위한 N MiB의 GPU 캐시 할당0, 비활성화
--moe-cache-cpu-share F캐시가 가득 찬 뒤 미스의 비율 F를 CPU에서 계산0

CPU share의 지원 범위는 0부터 1까지입니다.

캐시는 다음과 같이 동작합니다.

  • 캐시 히트는 GPU에서 처리합니다.
  • 캐시가 가득 차기 전에는 캐시 미스에 해당하는 전문가를 GPU로 전송합니다.
  • 캐시가 가득 차면 설정된 비율의 미스를 CPU가 계산합니다.
  • 나머지 미스는 GPU에서 처리할 수 있도록 가중치를 전송합니다.
  • 큰 배치에서는 필요한 전문가를 여전히 전송할 수 있습니다.

CPU가 RAM에서 전문가 가중치를 읽는 속도가 GPU 전송보다 빠르다면 CPU 계산이 도움이 될 수 있습니다.

반면 pinned host memory를 사용하면 GPU로의 전송이 더 효율적일 수 있습니다. 이미 전송 대역폭을 충분히 활용하고 있다면 CPU share를 높여도 얻는 이점이 작을 수 있습니다.

RAM에 있는 MoE 전문가를 GPU에 캐시하는 예시

이 설정에는 지원되는 GPU 백엔드와 전문가 캐시에 사용할 수 있는 충분한 GPU 메모리가 필요합니다.

CPU 전용 빌드에서는 여기서 설명하는 GPU 전문가 캐시를 제공할 수 없습니다.

필요한 CUDA 개발 환경이 준비된 NVIDIA 시스템에서는 공식 CUDA 빌드 안내에 따라 실행합니다.

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

다른 GPU 플랫폼을 사용한다면 해당 백엔드의 공식 빌드 옵션을 사용하세요.

호환되는 MoE 모델과 GPU 지원 빌드의 실행 예시는 다음과 같습니다.

./build/bin/llama-server \
  -m /path/to/moe-model.gguf \
  -cmoe \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  --moe-cache-mib 2048 \
  --moe-cache-cpu-share 0.5

-cmoe는 MoE 전문가 가중치를 CPU 메모리에 배치합니다. --moe-cache-mib 2048는 선택된 전문가를 위한 GPU 캐시 2,048 MiB를 요청합니다.

0.5는 캐시가 가득 찬 후 발생하는 캐시 미스의 50%를 CPU에서 처리한다는 뜻입니다.

캐시가 가득 차기 전에는 미스한 전문가를 계속 GPU로 전송합니다. 캐시 히트 역시 GPU에서 처리합니다.

이 값들은 설정 예시일 뿐 모든 시스템에 권장되는 최적값은 아닙니다.

GPU에는 전문가 캐시 외에도 모델 레이어, KV 캐시, 연산 버퍼를 위한 메모리가 필요합니다. 전문가 캐시를 크게 할당하면 다른 용도에 사용할 공간이 줄어듭니다.

요청한 캐시를 할당할 수 없다면 크기를 줄이거나 가중치 배치를 다시 확인하세요. 모델이 너무 커서 실행되지 않는 문제를 자동으로 해결하는 기능은 아닙니다.

튜닝 스크립트로 적절한 설정 찾기

프로젝트는 실제 하드웨어에 맞는 캐시 설정을 찾기 위한 튜닝 스크립트를 제공합니다.

llama.cpp 저장소에서 다음을 실행합니다.

python3 scripts/moe-cache-tune.py -- \
  ./build/bin/llama-server \
  -m /path/to/moe-model.gguf \
  -cmoe \
  -t 8 \
  -c 32768

공식 튜닝 스크립트는 다양한 캐시 크기와 CPU share를 사용하여 서버를 실행합니다.

공식 가이드는 총 6회의 측정을 설명합니다. 두 가지 캐시 크기와 CPU share 0, 0.5, 0.95를 조합합니다.

스크립트는 측정 결과를 기반으로 다른 구성의 성능을 추정합니다. 실제 측정 속도, 예상 처리량, 추천 인수를 출력합니다.

모델, CPU 스레드 수, 컨텍스트 크기, 전문가 가중치 배치 옵션은 실제 환경에 맞게 유지하세요. 이 설정들은 남는 GPU 메모리와 추론 속도에 영향을 줍니다.

해당 캐시는 주로 작은 배치의 디코딩을 대상으로 합니다. 큰 배치에서는 전문가 가중치를 계속 GPU로 전송해야 할 수 있습니다.

Dense 모델이거나 모든 전문가가 이미 GPU 메모리에 들어간다면 호스트 메모리 전문가 캐시의 이점은 작을 가능성이 높습니다. 이 경우 기본 비활성화 설정으로 시작하세요.

llama-server의 보안은 어떻게 바뀌었나요?

1.0.0에서는 인증 없는 서버 도구 접근과 비공개 미디어 URL 접근에 대한 명시적 허용 옵션이 추가되었습니다.

특히 다른 컴퓨터에서 서버에 접속할 수 있는 환경에서는 이 설정을 주의 깊게 확인해야 합니다.

—allow-unauthenticated-tools

--allow-unauthenticated-tools는 API key 없이 루프백이 아닌 주소에서 서버 도구, MCP 서버 또는 MCP 프록시를 사용하도록 허용하는 옵션입니다.

공식 서버 매개변수 문서에 따르면 이 권한은 기본적으로 비활성화되어 있습니다. 신뢰할 수 있는 네트워크에서만 사용하도록 안내합니다.

127.0.0.1에 바인딩하면 로컬 컴퓨터에서만 접속할 수 있습니다. 0.0.0.0에 바인딩하면 다른 네트워크 인터페이스에서도 접속할 수 있습니다.

따라서 외부 네트워크 접근, 활성화된 서버 도구 또는 MCP, API key가 없는 구성이 함께 사용된다면 보안 검토가 필요합니다.

허용 옵션은 다음과 같습니다.

--allow-unauthenticated-tools

업그레이드 오류를 해결하려고 이 옵션을 습관적으로 추가하지 마세요. 보안에 민감한 서버 기능을 인증 없이 사용하도록 명시적으로 허용합니다.

이 설정은 서버 측 도구와 MCP 노출을 제어합니다. 모델이 구조화된 tool_calls 응답을 생성하는 기능은 에이전트 작업의 다른 부분입니다.

같은 컴퓨터에서 개발한다면 로컬 연결을 권장합니다.

./build/bin/llama-server \
  -m /path/to/model.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  --jinja

원격 클라이언트에는 문서화된 --api-key 인증 방식과 적절한 네트워크 접근 제한을 사용하세요.

Bash에서 키를 화면에 표시하지 않고 입력합니다.

read -rs LLAMA_SERVER_API_KEY && export LLAMA_SERVER_API_KEY

이후 환경 변수를 참조하여 서버를 시작합니다.

./build/bin/llama-server \
  -m /path/to/model.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  --jinja \
  --api-key "$LLAMA_SERVER_API_KEY"

서버에는 적절한 네트워크 접근 제어도 적용하세요. API key만으로 모든 공개 배포 환경의 안전을 보장할 수는 없습니다.

—media-allow-private-urls

두 번째 변경은 이미지 참조처럼 서버로 전송되는 HTTP(S) 미디어 URL에 관한 것입니다.

기본적으로 서버는 로컬 또는 비공개 네트워크 주소를 가리키는 미디어 URL에 접근할 수 없습니다.

이를 명시적으로 허용하는 옵션은 다음과 같습니다.

--media-allow-private-urls

활성화하면 서버가 로컬 또는 비공개 주소의 HTTP(S) 미디어 리소스를 가져올 수 있습니다.

신뢰할 수 있는 애플리케이션이 내부 서버에 이미지를 저장하는 경우 유용할 수 있습니다. 그러나 신뢰할 수 없는 사용자가 URL을 제어할 수 있다면 SSRF(서버 측 요청 위조) 위험이 커집니다.

가능하면 지원되는 형식으로 이미지 데이터를 직접 보내거나 접근이 통제된 미디어 서버를 사용하세요.

비공개 URL 접근이 꼭 필요하다면 요청을 보낼 수 있는 사용자와 서버에서 접근 가능한 목적지를 제한해야 합니다. 신뢰할 수 없는 URL을 허용하기 위한 임시 해결책으로 사용하지 마세요.

기타 보안 수정 사항

이번 릴리스에는 다음과 같은 수정도 포함됩니다.

  • --cors-origins 검증과 origin 비교 개선.
  • DNS rebinding 공격 방어.
  • CORS 프록시를 통한 SSRF 문제 수정.
  • 하위 서버 인스턴스에 대한 브라우저 직접 접근 제한.
  • HF_TOKEN을 전송할 수 있는 목적지 제한.
  • 클라이언트 연결 종료 또는 시간 초과 시 MCP 도구 호출 취소.

이제 HF_TOKEN 전송 대상은 huggingface.co 호스트로 제한됩니다.

코딩 에이전트에서는 클라이언트 연결이 끊어진 후 불필요한 MCP 도구 호출이 계속 실행되지 않도록 하는 것이 중요합니다.

다만 취소 알림을 보낸다고 해서 외부 도구가 이미 수행한 작업을 자동으로 되돌릴 수 있는 것은 아닙니다.

자세한 변경 내용은 PR #32113, PR #32115, v1.0.0 릴리스 노트를 확인하세요.

업그레이드 후 로컬 코딩 에이전트 백엔드 확인 방법

Claude Code, OpenCode 또는 다른 코딩 클라이언트를 다시 연결하기 전에 서버에서 모델 생성이 정상적으로 작동하는지 먼저 확인하세요.

도구 호출에 적합한 지시 수행 모델을 사용하여 루프백 전용 서버를 시작합니다.

./build/bin/llama-server \
  -m /path/to/coding-model.gguf \
  --alias local-coder \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  --jinja

모델 자체가 클라이언트에서 요구하는 도구 호출 동작을 지원해야 합니다.

--jinja는 채팅 템플릿 처리를 활성화합니다. 도구 사용 능력이 없는 모델에 그 능력을 새로 추가하는 것은 아닙니다.

curl로 모델 목록을 확인합니다.

curl --fail-with-body \
  http://127.0.0.1:8080/v1/models

응답에서 설정한 모델 별칭을 확인할 수 있어야 합니다.

다음으로 간단한 채팅 요청을 전송합니다.

curl --fail-with-body \
  http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "local-coder",
    "messages": [
      {
        "role": "user",
        "content": "Explain what a Git diff shows in one sentence."
      }
    ],
    "max_tokens": 100
  }'

응답의 choices에 모델 출력이 포함되는지 확인합니다.

이 과정이 성공하면 코딩 클라이언트에서 문서화된 사용자 지정 제공자 설정을 사용하세요. 로컬 OpenAI 호환 API의 Base URL은 다음과 같습니다.

http://127.0.0.1:8080/v1

OpenAI Chat Completions를 지원한다고 해서 Anthropic Messages API나 OpenAI Responses API와 완전히 호환되는 것은 아닙니다.

Claude Code를 로컬 서버에 연결하려면 프로토콜 어댑터나 다른 지원 경로가 필요할 수 있습니다. OpenCode는 모델과 API 설정이 일치할 때 호환되는 사용자 지정 제공자를 사용할 수 있습니다.

실제 저장소에서 작업하기 전에 파일 읽기, 편집 제안, 도구 호출을 각각 한 번 확인하세요.

일반 텍스트 응답이 성공하더라도 구조화된 도구 인수, 파일 수정, 긴 세션까지 제대로 작동한다는 뜻은 아닙니다.

관련 모델 접근 방법은 Kimi K3.1 Pro의 Claude Code 및 Codex 설정 가이드를 참고하세요. Kimi K3.1 Pro 공개 가중치와 라이선스 가이드에서는 로컬 하드웨어와 호스팅 API의 요구 사항을 비교할 수 있습니다.

Ollama와 LM Studio 사용자도 업데이트해야 하나요?

Ollama나 LM Studio를 완성된 애플리케이션으로 사용한다면 내부 llama.cpp 라이브러리를 직접 교체하지 마세요.

이 애플리케이션들은 자체 런타임 버전, 패키징, 통합 테스트를 관리합니다.

llama.cpp 1.0.0이 출시되었다고 해서 모든 하위 애플리케이션에 해당 버전이 이미 포함되었다고 판단할 수는 없습니다.

각 애플리케이션의 릴리스 노트와 공식 업데이트 방식을 통해 실제 포함된 엔진 버전을 확인하세요.

특히 다음 변경 사항을 살펴보세요.

  • 업데이트 내역에 llama.cpp 1.0.0 또는 관련 엔진 변경이 명시되어 있는 경우.
  • 새로운 KV 캐시 형식이나 MoE 캐시 옵션이 추가된 경우.
  • 서버 도구 또는 MCP의 인증 요구 사항이 달라진 경우.
  • 업데이트 후 모델 로딩이나 도구 호출 동작이 달라진 경우.

일반적인 데스크톱 채팅 용도라면 특정 수정 사항이나 새로운 기능이 필요한 상황이 아닌 한 현재 정상 작동하는 지원 버전을 계속 사용해도 됩니다.

반면 Ollama 또는 LM Studio를 코딩 에이전트의 백엔드로 활용한다면 애플리케이션 업데이트 후 클라이언트부터 서버까지 전체 경로를 테스트해야 합니다.

언제 호스팅 API로 전환하는 것이 좋을까요?

선택한 모델을 필요한 컨텍스트 길이와 속도로 실행할 수 있다면 로컬 추론은 여전히 유용합니다.

FP8 KV 캐시는 메모리 압박을 줄일 수 있습니다. MoE 캐시는 RAM에 전문가 가중치를 보관하는 일부 환경에서 성능에 도움이 될 수 있습니다. 그러나 두 기능 모두 모든 메모리 제한을 해결하거나 코딩 작업의 속도 향상을 보장하지는 않습니다.

모델 가중치, Attention 캐시, 동시 요청이 하드웨어의 메모리 한계를 초과한다면 더 작은 로컬 모델과 호스팅 모델을 비교하세요.

호스팅 API를 사용하면 해당 모델의 GPU 메모리를 직접 관리할 필요가 줄어듭니다. 대신 네트워크 의존성, 사용량에 따른 비용, 제공자 의존성이 발생합니다.

BetterToken은 여러 모델을 사용량 기반 과금 API로 이용할 수 있는 선택지 중 하나입니다. 로컬 llama.cpp 실행 환경이나 해당 서버의 보안 기능을 제공하는 것은 아닙니다.

호스팅 모델을 선택하기 전에 현재 요금 페이지에서 모델과 작업량에 따른 비용을 확인하세요.

로컬과 호스팅 모델을 단계적으로 전환하려면 각각 별도로 테스트한 제공자 구성을 유지하세요. 모델 ID, 도구 형식, 인증 설정이 두 엔드포인트에서 동일하게 작동한다고 가정해서는 안 됩니다.

안전한 업그레이드를 위한 체크리스트

프로덕션의 로컬 코딩 백엔드를 llama.cpp 1.0.0으로 전환하기 전에 다음 항목을 확인하세요.

  1. v1.0.0 소스나 정확한 빌드 결과물을 고정합니다.
  2. --defrag-thold와 사용 중단된 C API 호출을 제거합니다.
  3. 새로운 공개 헤더에 맞춰 네이티브 바인딩을 다시 빌드합니다.
  4. 기존 FP16 KV 캐시 설정으로 먼저 테스트합니다.
  5. FP8 KV 캐시를 별도로 테스트하고 메모리, 속도, 코딩 정확도를 비교합니다.
  6. 지원되는 GPU 백엔드와 CPU 상주 전문가 가중치가 있을 때만 MoE 캐시를 조정합니다.
  7. 도구 인증과 비공개 미디어 URL 제한을 확인합니다.
  8. /v1/models, 채팅 생성, 도구 호출, 코딩 클라이언트를 검증합니다.
  9. 문제가 발생했을 때 되돌릴 수 있도록 이전 바이너리와 설정을 보관합니다.

llama.cpp 1.0.0은 공개 C 라이브러리의 호환성 범위를 더 명확하게 정의합니다. 그러나 실제 업그레이드의 안전성은 바인딩, 하드웨어, 서버의 네트워크 노출, 에이전트의 작업 흐름을 검증하는 데 달려 있습니다.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.

무료로 시작하기