llama-server router mode 사용 (feat. Gemini)

Local LLM 시리즈

1. (Local LLM) Ollama 시작하기
2. Codex 와 Local LLM 연결하기
3. llama-server 에서 router mode 사용하기

---

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 경로를 지정한다.

[gemma-4]
model = /home/user/models/gemma-4-26b-it-q4_k_m.gguf
n_gpu_layers = 999
n_ctx = 8192

[qwen-coder]
model = /home/user/models/qwen3-coder-7b-instruct-q8_0.gguf
n_gpu_layers = 999
n_ctx = 16384

② 라우터 모드 llama-server 실행

서버 실행시 --models-preset 으로 프리셋 설정 파일을 지정한다.

./llama-server --models-preset ./models.ini --port 8080

③ 클라이언트 호출

현재 제공되는 모델

curl http://localhost:8080/v1/models

이제 OpenAI 호환 API나 클라이언트(파이썬, curl, Open WebUI 등)에서 모델 이름으로 지정한 Alias를 지정해 호출한다.

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4",
    "messages": [{"role": "user", "content": "llama-server 의 라우터 모드를 한 문장으로 설명해줘."}]
  }'

모델 qwen-coder 호출

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-coder",
    "messages": [
      {"role": "user", "content": "csv 파일을 읽는 파이썬 함수를 작성해줘."}
    ]
  }'

---

구성 예시

동일한 장비(VRAM) 안에서 가볍게 서빙할 작은 모델과 대형 모델의 리소스를 차등 분배하여 작성한 프리셋 예시입니다.

프리셋 설정

llamaserver_preset.toml 같은 텍스트 파일에 작성

# 전역 설정 필드 (필요시 최상단 배치)
version = 1

[qwen-7b-ins]
model = "/home/user/models/Qwen2.5-7B-Instruct-Q8_0.gguf"
ctx-size = 16384
n-gpu-layers = 99
flash-attn = 1
temp = 0.7
top-p = 0.95

[gemma-27b-heavy]
model = "/home/user/models/gemma-2-27b-it-Q4_K_M.gguf"
ctx-size = 8192
n-gpu-layers = 32  # 3080 Ti / 4060 등 VRAM 제약 시 일부만 GPU 이관
threads = 8        # CPU로 남은 레이어 연산을 위한 스레드 할당
mlock = 1          # 시스템 스왑 방지하여 레이턴시 저하 방어
temp = 0.3
min-p = 0.05

---

서버 시작

--models-preset 옵션에 프리셋 설정 파일을 지정한다.

$ llama-server --models-preset llamaserver_preset.toml --port 8001 --host 0.0.0.0
0.00.110.622 I log_info: verbosity = 3 (adjust with the `-lv N` CLI arg)
0.00.110.649 I system_info: n_threads = 8 (n_threads_batch = 8) / 16 | CUDA : ARCHS = 860 | USE_GRAPHS = 1 | PEER_MAX_BATCH_SIZE = 128 | CPU : SSE3 = 1 | SSSE3 = 1 | AVX = 1 | AVX2 = 1 | F16C = 1 | FMA = 1 | BMI2 = 1 | LLAMAFILE = 1 | OPENMP = 1 | REPACK = 1 |
0.00.110.650 I srv          main: n_parallel is set to auto, using n_parallel = 4 and kv_unified = true
0.00.110.658 I srv          init: running without SSL
0.00.110.676 I srv          init: using 15 threads for HTTP server
0.00.111.579 I srv   load_models: Loaded 0 cached model presets
0.00.111.743 I srv   load_models: Loaded 2 custom model presets from llamaserver_preset.toml
0.00.111.769 I srv    operator(): Available models (2) (*: custom preset)
0.00.111.769 I srv    operator():   * g4coder
0.00.111.770 I srv    operator():   * gemma4-26b
0.00.111.836 I srv          main: starting router server, no model will be loaded in this process

확인

llama-server 의 로그는 journalctl 명령으로 확인 가능하다.

3.19.587.902 I srv  ensure_model: waiting until model name=gemma4-26b is fully loaded...
[50679] 0.00.032.099 I log_info: verbosity = 3 (adjust with the `-lv N` CLI arg)
[50679] 0.00.032.100 I device_info:
[50679] 0.00.170.204 I   - CUDA0   : NVIDIA GeForce RTX 3080 Ti (11910 MiB, 11635 MiB free)
[50679] 0.00.170.209 I   - CPU     : AMD Ryzen 7 5800X3D 8-Core Processor (62168 MiB, 62168 MiB free)
[50679] 0.00.170.240 I system_info: n_threads = 8 (n_threads_batch = 8) / 16 | CUDA : ARCHS = 860 | USE_GRAPHS = 1 | PEER_MAX_BATCH_SIZE = 128 | CPU : SSE3 = 1 | SSSE3 = 1 | AVX = 1 | AVX2 = 1 | F16C = 1 | FMA = 1 | BMI2 = 1 | LLAMAFILE = 1 | OPENMP = 1 | REPACK = 1 |
[50679] 0.00.170.242 I srv          main: n_parallel is set to auto, using n_parallel = 4 and kv_unified = true
[50679] 0.00.170.254 I srv          init: running without SSL
[50679] 0.00.170.272 I srv          init: using 15 threads for HTTP server
[50679] 0.00.170.361 I srv         start: binding port with default address family
[50679] 0.00.171.553 I srv          main: loading model
[50679] 0.00.171.557 I srv    load_model: loading model '/home/Models/gemma-4-26B-A4B-it-UD-Q5_K_S.gguf'

---

모델 정보

curl http://localhost:8080/v1/models

다음 같은 json 출력을 얻는다

{"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 지정 시 무한대 생성)