> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokios.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel. > Use 'connector' for the local tokios-connector process. > Use 'deployment' for the public model name in the API model field. > Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend. > API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-. # 속도와 메모리를 위한 llama.cpp 최적화 > 최대 성능을 위해 llama.cpp를 튜닝하십시오. 플래시 어텐션, mmap 대 mlock, 스레드 튜닝, GPU 오프로드 전략, 배치 크기, KV 캐시 정밀도, MoE 전문가 배치를 다룹니다. llama.cpp는 가장 이식성이 높은 로컬 추론 런타임입니다. CPU, NVIDIA GPU, AMD GPU, Apple Silicon에서 실행되며 — 종종 동일한 바이너리에서 실행됩니다. 이러한 유연성에는 많은 플래그가 따르며, 기본값이 항상 하드웨어에 최적이지는 않습니다. 이 가이드에서는 가장 중요한 플래그와 각 플래그 뒤에 있는 트레이드오프를 다룹니다. > [!NOTE] > > Last verified: 2026-10-14 — llama.cpp build b11609. > [!NOTE] > > All flags in this guide apply to `llama-server` and `llama-cli` from llama.cpp build **b11609** (October 14, 2026). Flag names can change between builds — run `llama-server --help` to confirm what your binary supports. ## Flash attention Flash attention을 활성화하려면 `-fa` 또는 `--flash-attn on`을 사용하세요. 대부분의 벤치마크에서, 이것은 llama.cpp가 제공하는 거의 무료 성능 개선에 가장 가까운 것입니다 — 동일한 또는 더 낮은 메모리 사용량으로 더 빠른 추론을 얻을 수 있으며, 품질 비용은 무시할 수 있습니다. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -fa ``` Flash attention은 모델이 토큰 간의 어텐션 점수를 계산하는 방식을 재구성합니다. 전체 어텐션 행렬을 메모리에 구현하는 대신, 빠른 SRAM에 맞는 타일된 청크로 어텐션을 계산합니다. 결과: * **KV 캐시의 더 낮은 메모리 사용량** — 긴 컨텍스트 길이에서 가장 큰 이점. * **더 빠른 추론** — 특히 GPU에서, 타일된 계산이 텐서 코어에 잘 매핑됩니다. * **동일한 출력 품질** — flash attention은 표준 어텐션과 수학적으로 동일하며, 근사가 아닙니다. > [!TIP] > > **항상 `-fa`로 시작하세요.** 특정 모델이나 플랫폼에서 호환성 문제가 발생하지 않는 한 끄지 않을 이유가 없습니다. 이 가이드에서 가장 영향력 있는 단일 플래그입니다. ## mmap vs mlock llama.cpp는 2가지 전략 중 하나를 사용하여 모델 가중치를 메모리에 로드합니다. 기본값은 `--mmap`으로, 모델 파일을 프로세스의 가상 주소 공간에 직접 매핑합니다. 대안은 `--mlock`으로, 전체 모델을 물리적 RAM에 고정합니다. | Flag | What it does | Best for | | - | - | - | | `--mmap` (default) | Maps the file; the OS pages data in and out as needed | One-shot runs, memory-constrained machines, quick experiments | | `--mlock` | Pins every byte in physical RAM; nothing pages out | Repeated inference, dedicated inference servers, models you run all day | ### mmap이 이기는 경우 `--mmap`이 기본인 이유는 대부분의 대화형 사용에서 잘 작동하기 때문입니다. OS가 모델 페이지를 온디맨드로 로드하므로 시작이 빠르고, 페이지가 실제로 터치될 때까지 모델 파일이 RAM에 이중으로 계산되지 않습니다. 모델을 테스트하거나 짧은 세션을 실행하는 경우 기본값으로 충분합니다. ### mlock이 이기는 경우 `--mlock`은 OS가 모델 페이지를 스왑으로 축출하는 것을 방지합니다. 이것이 중요한 경우: * 하루 종일 같은 모델을 실행하며 일관된 지연 시간을 원할 때 — 페이지 폴트로 인한 콜드 스타트 페널티 없음. * 시스템이 다른 프로세스의 메모리 압박을 받고 있으며 모델 가중치를 페이지 아웃할 수 있을 때. * 스왑이 느린(또는 스왑이 없는) 머신에서 페이지 폴트가 추론을 몇 초간 중단시킬 수 있을 때. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -fa --mlock ``` > [!WARNING] > > `--mlock`은 전체 모델이 사용 가능한 물리적 RAM에 맞아야 합니다. 맞지 않으면 프로세스가 시작되지 않습니다. 활성화하기 전에 Linux에서 `free -h` 또는 macOS에서 Activity Monitor로 사용 가능한 메모리를 확인하세요. ## 스레드 튜닝 이 `-t` 플래그는 추론에 사용되는 CPU 스레드 수를 설정합니다. 올바른 값은 CPU가 실제로 얼마나 많은 작업을 수행하는지에 따라 다릅니다. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -t 8 ``` | Scenario | Thread guidance | | - | - | | Full GPU offload (all layers on GPU) | `-t 2` to `-t 4` — the CPU handles orchestration and tokenization, not math | | Partial GPU offload (some layers on CPU) | Set `-t` to the number of physical cores on your CPU — not hyperthreads | | CPU-only (no GPU) | Set `-t` to the number of physical cores | > [!TIP] > > 스레드가 많을수록 항상 빠른 것은 아닙니다. 물리적 코어 수를 초과하면 스레드가 캐시와 메모리 대역폭을 경쟁하여 추론을 느리게 할 수 있습니다. 확실하지 않으면 물리적 코어 수로 시작하여 벤치마크를 실행하세요. Apple Silicon에서는 GPU와 CPU가 통합 메모리를 공유하고 Metal 백엔드가 스케줄링을 처리하므로 스레드 튜닝이 덜 중요합니다. 기본값이 일반적으로 잘 작동합니다. ## GPU 오프로드 전략 이 `-ngl` 플래그는 GPU로 오프로드하는 모델 레이어 수를 제어합니다. GPU의 레이어가 많을수록 추론이 빨라지지만, 각 레이어는 VRAM을 소비합니다. ### 부분 오프로드 먼저 `-ngl`을 GPU 메모리에 맞출 수 있는 레이어 수로 설정하세요. 나머지 레이어는 CPU에서 실행됩니다. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -ngl 20 -fa ``` 전체 모델이 VRAM에 맞지 않을 때 부분 오프로드를 사용하세요. 높은 값으로 시작하고 메모리가 부족하지 않게 서버가 시작될 때까지 줄이세요. ### 전체 오프로드 여기서 `-ngl 999`를 설정하여 모든 레이어를 오프로드하세요. llama.cpp는 999를 "나머지 모든 레이어"로 사용합니다 — 문자 그대로 999개 레이어를 오프로드하려고 하지 않습니다. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -ngl 999 -fa ``` 전체 오프로드는 모든 포워드 패스가 GPU에서 실행되므로 가장 빠른 추론 속도를 제공합니다. 모델 가중치와 KV 캐시 모두 VRAM에 맞아야 합니다. ### 레이어당 메모리 예산 오프로드된 각 레이어는 가중치와 KV 캐시 모두를 위해 VRAM을 소비합니다. 대략적인 추정: ``` VRAM per layer ≈ (parameter_count_per_layer × bytes_per_weight) + KV_cache_per_layer ``` 7B 모델에 Q4\_K\_M 양자화(가중치당 \~4.5비트, \~40개 레이어)를 사용하면: | Component | Per layer | 40 layers total | | - | - | - | | Weights | \~0.15 GB | \~6 GB | | KV cache (f16, 4K ctx) | \~0.05 GB | \~2 GB | | **Total** | | **\~8 GB** | CUDA 컨텍스트와 오버헤드를 위해 1-2 GB의 VRAM 여유를 두세요. ## 배치 크기 튜닝 두 개의 플래그가 prefill 단계에서 llama.cpp가 한 번에 처리하는 토큰 수를 제어합니다: | Flag | What it controls | | - | - | | `-b` (batch size) | Total tokens processed in one batch during prompt ingestion | | `-ub` (UBatch size) | Maximum tokens per micro-batch within a single batch | ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -b 512 -ub 512 -fa ``` ### 상호 작용 방식 * **`-b`** 는 외부 제한을 설정합니다. 프롬프트가 `-b`보다 많은 토큰을 가지면 llama.cpp가 여러 배치로 분할합니다. * **`-ub`** 는 내부 청크 크기를 설정합니다. llama.cpp는 배치를 최대 `-ub` 토큰의 마이크로 배치로 처리합니다. * `-ub`는 `-b`보다 작거나 같아야 합니다. ### 트레이드오프 | Setting | Effect | | - | - | | Larger `-b` (512-2048) | Faster prefill for long prompts — more tokens processed per forward pass | | Larger `-b` | More VRAM/RAM consumed during prompt ingestion | | Smaller `-b` (128-256) | Lower memory usage, slower prefill | | `-ub` equal to `-b` | Simplest configuration; one micro-batch covers the full batch | | `-ub` smaller than `-b` | Caps per-micro-batch memory; useful when `-b` is large but VRAM is tight | > [!TIP] > > 짧은 프롬프트(1K 토큰 미만)의 대화형 채팅의 경우 기본 `-b 512`로 충분합니다. 긴 문서를 정기적으로 수집하고 더 빠른 첫 토큰 도달 시간을 원할 때만 증가시키세요. ## KV 캐시 정밀도 KV 캐시는 모든 활성 시퀀스의 모든 토큰에 대한 키와 값 텐서를 저장합니다. 기본적으로 llama.cpp는 키와 값 모두에 f16(16비트 부동 소수점)을 사용합니다. 양자화된 정밀도로 전환하여 약간의 품질 비용으로 메모리 사용량을 줄일 수 있습니다. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -fa \ --cache-type-k q8_0 --cache-type-v q8_0 ``` | Precision | Memory per element | Quality | When to use | | - | - | - | - | | `f16` (default) | 2 bytes | Baseline | Maximum quality; you have plenty of memory | | `q8_0` | 1 byte | Near-identical to f16 | Best balance — halves KV cache memory with negligible quality loss | | `q4_0` | 0.5 bytes | Slight degradation | Tight memory; long context or many concurrent sequences | 키와 값을 독립적으로 설정할 수 있습니다. 일반적인 패턴은 양쪽 모두에 `q8_0`을 사용하는 것으로, 대부분의 벤치마크에서 1% 미만의 품질 차이로 KV 캐시 메모리를 절반으로 줄입니다. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Aggressive: quarter the KV cache memory llama-server -m model.gguf -fa \ --cache-type-k q4_0 --cache-type-v q4_0 ``` > [!WARNING] > > `q4_0` KV 캐시는 긴 컨텍스트에 대한 정밀한 어텐션에 의존하는 작업에서 측정 가능한 품질 손실을 유발합니다 — needle-in-a-haystack 검색, 다중 문서 요약, 긴 대화. `q4_0`로 결정하기 전에 특정 워크로드를 테스트하세요. ## MoE 최적화 Qwen3.5-35B-A3B나 Mixtral 같은 Mixture-of-experts 모델은 각 레이어에 많은 수의 전문가 서브네트워크를 저장하지만 토큰당 몇 개만 활성화합니다. 전문가 가중치는 비활성 상태일 때도 메모리에 존재하므로 MoE 모델은 활성 매개변수 수에 비해 불균형하게 큽니다. 다중 GPU 시스템에서 GPU 메모리가 부족할 때 전문가 레이어를 CPU에 배치할 수 있습니다: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -ngl 999 --n-cpu-moe 4 -fa ``` `--n-cpu-moe `는 지정된 수의 전문가 서브레이어를 CPU에 유지하고 모델의 나머지는 GPU에서 실행합니다. 이것은 약간의 지연 시간 증가와 VRAM에 더 큰 모델을 맞추는 것을 트레이드오프합니다. | Scenario | Configuration | | - | - | | MoE fits entirely in VRAM | `-ngl 999` — no CPU experts needed | | MoE almost fits, a few experts overflow | `--n-cpu-moe 2` to `--n-cpu-moe 8` | | MoE is too large for any reasonable GPU setup | Combine `--n-cpu-moe` with partial `-ngl` | > [!TIP] > > 우선 `--n-cpu-moe 0`(모든 전문가 GPU)으로 시작하고 VRAM이 부족할 때만 증가시키세요. CPU로 이동하는 각 전문가는 포워드 패스 동안 PCIe 버스를 통해 데이터를 이동해야 하므로 지연 시간을 추가합니다. ## 예제 구성 ### Apple Silicon — M-series Mac에 최적화 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf \ -fa \ --mlock \ -b 512 \ -ub 512 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ -ngl 999 \ --port 8080 ``` 이것은 통합 메모리에 모델을 고정하고, flash attention을 활성화하고, 메모리 예산을 늘리기 위해 KV 캐시를 양자화합니다. Apple Silicon의 통합 메모리는 GPU가 전체 RAM 풀에 접근할 수 있으므로 모델과 KV 캐시가 맞는 한 전체 오프로드(`-ngl 999`)가 작동합니다. > [!NOTE] > > llama.cpp는 Apple Silicon에서 잘 실행되지만, Mac에서만 배포하는 경우 [MLX](https://github.com/ml-explore/mlx)가 Apple의 Metal 백엔드에 최적화되어 있어 같은 모델에 대해 더 빠른 추론을 제공할 수 있습니다. 크로스 플랫폼 이식성이나 OpenAI 호환 서버가 필요할 때 llama.cpp를 사용하세요. ### GPU 오프로드 — NVIDIA 또는 AMD 외장 GPU ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf \ -fa \ -ngl 999 \ -b 512 \ -ub 512 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ -t 4 \ --port 8080 ``` Flash attention과 양자화된 KV 캐시를 갖춘 전체 GPU 오프로드. 4개의 CPU 스레드가 오케스트레이션과 토큰화를 처리합니다. 모델이 맞지 않으면 `-ngl`을 줄이세요 — 전체 레이어 수로 시작하여 5씩 줄여가며 로드되는지 확인하세요. ### CPU 전용 — GPU 없음 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf \ -t 8 \ -b 256 \ -ub 256 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ --port 8080 ``` GPU 오프로드 없이 CPU가 모든 작업을 수행합니다. 스레드 수가 물리적 코어 수와 일치합니다. 더 작은 배치 크기가 메모리 사용량을 관리 가능하게 유지합니다. 모델 가중치를 Q4\_K\_M 또는 Q5\_K\_M 양자화로 사용하여 풋프린트를 작게 유지하세요. ## 다음 단계 > **[llama.cpp remote access](/ko/guides/llama-cpp-remote-access.md)** > > Tokios를 통해 포트 없이 llama.cpp 서버를 팀원과 에이전트에게 노출하세요. > **[Speculative decoding](/ko/guides/speculative-decoding.md)** > > 드래프트 모델, n-grams, EAGLE로 디코드를 가속 — llama.cpp 백엔드와 작동합니다. > **[Test your deployment](/ko/guides/benchmark-your-deployment.md)** > > 튜닝 후 지연 시간과 처리량을 측정하여 개선을 확인하세요. > **[KV cache and context](/ko/concepts/kv-cache-and-context.md)** > > 모델 아키텍처와 런타임 전반에서 KV 캐시가 작동하는 방식에 대한 자세한 설명. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.