llama-server router mode 사용 (feat. Gemini)
Local LLM 시리즈
llama-server가 라우터 모드(Router Mode)로 동작할 때, 클라이언트가 복잡한 .gguf 전체 파일명 대신 모델이름으로 모델을 지정하게 만드는 방법은 크게 두 가지가 있다.
--models-preset--models-dir
현재 llama-server가 업데이트되면서 가장 권장되는 정석적인 방법은 TOML(ini) 설정 파일을 사용하는 것이다.
정석: --models-preset (INI 설정 파일) 사용하기
가장 깔끔하고 확실한 방법입니다. 라우터 모드를 켤 때 --models-preset 플래그를 사용하여 각 GGUF 파일에 원하는 ID(Alias)를 매핑하는 models.ini 파일을 지정하는 방식입니다.
① models.ini 파일 작성
원하는 경로에 설정 파일을 만들고, 대괄호 [모델명] 안에 클라이언트에서 호출시 사용할 Alias로 모델명를 적어준 뒤 내부에서 실제 model 경로를 지정한다.
1 | [gemma-4] |
② 라우터 모드 llama-server 실행
서버 실행시 --models-preset 으로 프리셋 설정 파일을 지정한다.
1 | ./llama-server --models-preset ./models.ini --port 8080 |
③ 클라이언트 호출
현재 제공되는 모델
1 | curl http://localhost:8080/v1/models |
이제 OpenAI 호환 API나 클라이언트(파이썬, curl, Open WebUI 등)에서 모델 이름으로 지정한 Alias를 지정해 호출한다.
1 | curl http://localhost:8080/v1/chat/completions \ |
모델 qwen-coder 호출
1 | curl http://localhost:8080/v1/chat/completions \ |
구성 예시
동일한 장비(VRAM) 안에서 가볍게 서빙할 작은 모델과 대형 모델의 리소스를 차등 분배하여 작성한 프리셋 예시입니다.
프리셋 설정
llamaserver_preset.toml 같은 텍스트 파일에 작성
1 | # 전역 설정 필드 (필요시 최상단 배치) |
서버 시작
--models-preset 옵션에 프리셋 설정 파일을 지정한다.
1 | llama-server --models-preset llamaserver_preset.toml --port 8001 --host 0.0.0.0 |
확인
llama-server 의 로그는 journalctl 명령으로 확인 가능하다.
1 | 3.19.587.902 I srv ensure_model: waiting until model name=gemma4-26b is fully loaded... |
모델 정보
1 | curl http://localhost:8080/v1/models |
다음 같은 json 출력을 얻는다
1 | {"data":[{"id":"g4coder","aliases":[],"tags":[],"object":"model","owned_by":"llamacpp","created":1780772059,"status":{"value":"unloaded","args":["/home/qkboo/.local/bin/llama-server","--host","127.0.0.1","--port","0","--repeat-penalty","1.1","--temperature","0.1","--top-k","64","--top-p","0.1","--alias","g4coder","--ctx-size","65536","--model","/home/qkboo/Models/unsloth/gemma-4-26B-A4B-it-UD-Q5_K_S.gguf","--n-gpu-layers","-1"],"preset":"[g4coder]\nrepeat-penalty = 1.1\ntemperature = 0.1\ntop-k = 64\ntop-p = 0.1\nctx-size = 65536\nmodel = /home/qkboo/Models/unsloth/gemma-4-26B-A4B-it-UD-Q5_K_S.gguf\nn-gpu-layers = -1\n\n"},"architecture":{"input_modalities":["text"],"output_modalities":["text"]}},{"id":"gemma4-26b","aliases":[],"tags":[],"object":"model","owned_by":"llamacpp","created":1780772059,"status":{"value":"unloaded","args":["/home/qkboo/.local/bin/llama-server","--host","127.0.0.1","--port","0","--repeat-penalty","1.1","--temperature","1.0","--top-k","64","--top-p","0.95","--alias","gemma4-26b","--ctx-size","12288","--model","/home/quboo/Models/unsloth/gemma-4-26B-A4B-it-UD-Q5_K_S.gguf","--n-gpu-layers","-1"],"preset":"[gemma4-26b]\nrepeat-penalty = 1.1\ntemperature = 1.0\ntop-k = 64\ntop-p = 0.95\nctx-size = 12288\nmodel = /home/quboo/Models/unsloth/gemma-4-26B-A4B-it-UD-Q5_K_S.gguf\nn-gpu-layers = -1\n\n"},"architecture":{"input_modalities":["text"],"output_modalities":["text"]}}],"object":"list"} |
llama-serrver 주요 파라미터
1. 모델 구성 및 메모리 맵핑 (Model & Memory)
| 파라미터명 | 설명 |
|---|---|
model (또는 m) |
로컬 시스템에 저장된 GGUF 모델 파일의 절대 경로를 지정합니다. |
hf |
Hugging Face 저장소에서 모델을 직접 지정할 때 사용합니다. (예: ggml-org/Qwen2.5-7B-Instruct-GGUF) |
mmap |
Memory-map 사용 여부 (1 또는 0). 활성화 시 모델 로드가 빨라지지만 OS 페이지 아웃이 발생할 수 있습니다. |
mlock |
모델을 RAM에 강제로 잠금 처리하여 스왑(Swap) 영역으로 빠지는 것을 방지합니다. (1 or 0) |
2. 하드웨어 가속 및 연산 제어 (Hardware Allocation)
| 파라미터명 | 설명 |
|---|---|
n-gpu-layers (또는 ngl) |
GPU로 오프로드할 레이어 수입니다. VRAM 용량에 맞춰 조절하며, 전체 레이어를 올리려면 대개 99 같은 큰 값을 지정합니다. |
main-gpu (또는 mg) |
멀티 GPU 환경에서 기본 가속 및 중간 연산 결과(KV)를 처리할 메인 GPU 인덱스(0, 1 등)를 지정합니다. |
split-mode (또는 sm) |
멀티 GPU 분할 방식을 정의합니다. (none, layer, row, tensor) |
threads (또는 t) |
GPU에 올라가지 않고 CPU 영역에 남은 레이어를 연산할 때 사용할 쓰레드 수입니다. |
threads-batch (또는 tb) |
프롬프트 배치 가공 시 사용할 CPU 쓰레드 수입니다. (일반적으로 threads와 동일하게 지정) |
3. 컨텍스트 및 배치 관리 (Context & Batching)
| 파라미터명 | 설명 |
|---|---|
ctx-size (또는 c) |
프롬프트 및 컨텍스트 윈도우 크기를 토큰 단위로 지정합니다. (기본값 0 시 모델 메타데이터값 추종) |
batch-size (또는 b) |
텍스트 처리를 위한 논리적 최대 배치 크기입니다. (기본값 2048) |
ubatch-size (또는 ub) |
물리적 최대 배치 크기로, 청크 단위 연산 크기를 제어합니다. (기본값 512) |
flash-attn (또는 fa) |
Flash Attention 활성화 여부입니다. 지원하는 아키텍처에서 연산 속도와 VRAM 절약에 유용합니다. |
4. 추론 및 샘플링 파라미터 (Sampling Parameters)
⚠️ 주의:
llama.cpp버전 및 클라이언트 프레임워크 연동에 따라 일부 샘플링 파라미터는 프리셋 파일에 직접 선언하기보다 클라이언트 요청(API Payload) 단에서 동적으로 전달하는 것이 구동 안정성에 더 유리할 수 있습니다.
| 파라미터명 | 설명 |
|---|---|
temp |
생성 텍스트의 다양성(확률 분포 평탄화)을 조절하는 온도 값입니다. |
top-p |
누적 확률 분포 상위 P 범위 내의 토큰들만 후보군으로 압축합니다. |
top-k |
확률이 가장 높은 상위 K개의 토큰으로 후보군을 제한합니다. |
min-p |
가장 유력한 토큰 확률 대비 최소 임계치 비율 이하인 토큰을 배제합니다. |
predict (또는 n) |
한 번의 요청으로 모델이 생성할 최대 토큰 수를 지정합니다. (-1 지정 시 무한대 생성) |
