> ## 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-.

# 속도와 메모리를 위한 Ollama 최적화

> 최대 속도를 위해 Ollama를 튜닝하십시오. 컨텍스트 윈도우, GPU 오프로드, 플래시 어텐션, KV 캐시 양자화, 병렬 요청을 다룹니다. 이 설정으로 지연 시간을 2-5x 줄일 수 있습니다.

Ollama는 로컬 모델을 실행하는 가장 빠른 방법입니다. `ollama run llama3` 명령 한 줄로 서빙이 시작됩니다. 내부적으로 llama.cpp(Apple Silicon에서는 MLX)를 래핑하며, 하드웨어 사용 방식을 제어하는 여러 환경 변수와 모델 파라미터를 노출합니다. 기본값은 일반적인 사용에는 작동하지만 상당한 성능 여력을 그대로 둡니다. 이 가이드는 중요한 모든 설정과 워크로드에 맞게 구성하는 방법을 다룹니다.

> [!NOTE]
>
> 최종 확인: 2026-10-14 — Ollama v0.33.2.

> [!NOTE]
>
> **Apple Silicon은 MLX를 사용합니다.** Ollama 0.19부터 Apple Silicon의 기본 백엔드는 llama.cpp가 아닌 Apple의 MLX 프레임워크입니다. MLX는 M 시리즈 칩에서 훨씬 빠른 추론을 제공합니다([Apple Silicon 및 MLX 최적화](#apple-silicon-and-mlx-optimization) 참조). 이 가이드의 대부분 환경 변수는 두 백엔드 모두에 적용됩니다. 동작이 다른 경우 명시적으로 설명합니다.

## 컨텍스트 윈도우 튜닝

컨텍스트 윈도우(`num_ctx`)는 모델이 단일 요청에서 처리할 수 있는 토큰 수를 제어합니다. 프롬프트와 생성된 응답을 합친 값입니다. 모델 가중치 다음으로 메모리 사용량의 가장 큰 원인입니다.

### Ollama 컨텍스트 윈도우를 증가시키는 방법

Ollama는 기본적으로 2048토큰 컨텍스트 윈도우를 사용합니다. 대부분의 최신 모델은 8K, 32K, 심지어 128K 토큰을 지원하지만, Ollama는 모델의 최댓값을 기본으로 사용하지 않습니다. 메모리 사용량을 예측 가능하게 유지하기 위해 2048을 사용합니다.

3가지 방법으로 설정할 수 있습니다. 가장 구체적인 것부터 전역까지:

**요청별 (API):**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Summarize this document..."}],
    "options": {
      "num_ctx": 32768
    }
  }'
```

**Modelfile에서 (모델별 영구 설정):**

```dockerfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_ctx 32768
```

그런 다음 커스텀 모델을 빌드하고 실행하세요:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
ollama create llama3-32k -f Modelfile
ollama run llama3-32k
```

**전역 (모든 모델, 모든 요청):**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl daemon-reload && systemctl restart ollama
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
[System.Environment]::SetEnvironmentVariable("OLLAMA_CONTEXT_LENGTH", "32768", "User")
# Restart Ollama
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# Restart Ollama
```

### 컨텍스트 윈도우 메모리 비용

KV 캐시는 컨텍스트 길이에 따라 선형적으로 증가합니다. 공식:

```
KV cache memory = 2 × num_layers × hidden_dim × num_ctx × precision_bytes
```

7B 모델(32 레이어, 4096 hidden dimension)의 f16 정밀도:

| 컨텍스트 길이 | KV 캐시 메모리 |
| - | - |
| 2,048 (기본) | \~1 GB |
| 8,192 | \~4 GB |
| 32,768 | \~16 GB |
| 128,000 | \~64 GB |

> [!TIP]
>
> 설정에서 `num_ctx`는 워크로드가 실제로 필요로 하는 만큼만 설정하세요. 2K 프롬프트를 전송하는 코딩 에이전트는 128K 컨텍스트 윈도우의 이점이 없습니다. 다른 요청을 제공하거나 더 큰 모델을 수용할 수 있는 64 GB의 KV 캐시 공간을 낭비할 뿐입니다.

## Flash attention

Flash attention은 Ollama가 제공하는 가장 무료에 가까운 성능 개선입니다. 토큰 간 어텐션 계산 방식을 재구성합니다. 전체 어텐션 행렬을 메모리에 materializing하는 대신, 빠른 SRAM에 맞는 타일 청크로 어텐션을 계산합니다. 결과:

* **30-50% 낮은 KV 캐시 메모리 사용량** — 긴 컨텍스트 길이에서 가장 큰 이점.
* **더 빠른 추론** — 특히 GPU에서, 타일 계산이 텐서 코어에 잘 매핑됩니다.
* **동일한 출력 품질** — flash attention은 표준 어텐션과 수학적으로 동일하며 근사가 아닙니다.

### Ollama에서 flash attention을 활성화하는 방법

환경 변수를 설정하세요:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_FLASH_ATTENTION=1"
sudo systemctl daemon-reload && systemctl restart ollama
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
[System.Environment]::SetEnvironmentVariable("OLLAMA_FLASH_ATTENTION", "1", "User")
# Restart Ollama
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
launchctl setenv OLLAMA_FLASH_ATTENTION 1
# Restart Ollama
```

> [!TIP]
>
> **항상 flash attention을 활성화하세요.** 특정 모델이나 플랫폼에서 호환성 문제가 발생하지 않는 한 끄할 이유가 없습니다. 이 가이드에서 가장 영향이 큰 설정입니다.

> [!NOTE]
>
> MLX 백엔드를 사용하는 Apple Silicon에서는 flash attention이 기본적으로 활성화되어 있으며 `OLLAMA_FLASH_ATTENTION` 변수는 효과가 없습니다. MLX는 항상 최적화된 어텐션 커널을 사용합니다.

## GPU 오프로드 전략

Ollama는 모델 레이어를 GPU로 자동 오프로드합니다. 전체 모델이 VRAM에 맞으면 모든 레이어가 GPU에서 실행되어 최대 속도를 제공합니다. VRAM이 부족하면 Ollama는 레이어를 GPU와 CPU로 분할합니다. GPU가 가능한 많은 레이어를 실행하고 나머지는 시스템 RAM으로 폴백합니다.

### Ollama가 GPU 레이어를 결정하는 방법

Ollama의 GPU 스케줄링은 다음 순서로 작동합니다:

1. **전체 오프로드** — 모델 가중치 + KV 캐시가 VRAM에 맞으면 모든 레이어가 GPU로 이동합니다. 이것이 가장 빠른 구성입니다.
2. **부분 오프로드** — 모델이 완전히 맞지 않으면 Ollama는 VRAM이 허용하는 만큼의 레이어를 GPU에 배치하고 나머지는 CPU에서 실행합니다. 모든 forward pass가 CPU 상주 레이어를 위해 PCIe 버스를 건너야 하므로 성능이 저하됩니다.
3. **CPU 전용** — GPU를 사용할 수 없거나 VRAM이 몇 개 레이어에도 너무 작으면 전체 모델이 CPU에서 실행됩니다.

### GPU 레이어 제어용 `num_gpu`

설정 항목 중 `num_gpu` 파라미터로 GPU로 오프로드할 레이어 수를 지정합니다. Modelfile이나 요청별로 설정하세요:

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_gpu 35
```

```bash API theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Hello"}],
    "options": {
      "num_gpu": 35
    }
  }'
```

| `num_gpu` 값 | 동작 |
| - | - |
| `-1` | 모든 레이어 GPU (전체 레이어 수와 동일) |
| `0` | GPU 오프로드 없음 — CPU 전용 |
| `1`\~`N` | 정확히 해당 수의 레이어 GPU, 나머지 CPU |
| 설정 안 함 (기본) | 사용 가능한 VRAM 기반 자동 감지 |

> [!TIP]
>
> 대부분의 경우 `num_gpu`를 설정하지 않고 Ollama가 자동 감지하도록 두세요. 특정 분할을 강제해야 할 때만 수동으로 설정하세요. 예를 들어, 더 큰 컨텍스트 윈도우를 위해 VRAM을 확보하거나 간신히 맞는 모델의 일부 레이어를 CPU에 유지합니다.

### VRAM 예산 책정

각 오프로드된 레이어는 가중치와 KV 캐시 모두를 위해 VRAM을 소비합니다. 대략적인 추정:

```
VRAM per layer ≈ (parameters_per_layer × bytes_per_weight) + (KV_cache_per_layer × num_ctx)
```

7B 모델 Q4\_K\_M(가중치당 \~4.5비트, \~32 레이어):

| 구성 요소 | 레이어당 | 32 레이어 전체 |
| - | - | - |
| 가중치 | \~0.19 GB | \~6 GB |
| KV 캐시 (f16, 8K ctx) | \~0.13 GB | \~4 GB |
| **합계** | | **\~10 GB** |

CUDA 컨텍스트와 오버헤드를 위해 1-2 GB의 VRAM 여유를 두세요.

> [!WARNING]
>
> 컨텍스트 길이를 늘리면 `num_ctx` 값이 커져서 KV 캐시가 증가하고 레이어가 VRAM에서 밀려날 수 있습니다. `num_ctx 32768`을 설정했는데 Ollama가 갑자기 레이어의 절반을 CPU로 오프로드하면 KV 캐시가 VRAM 예산을 소비한 것입니다. `num_ctx`를 줄이거나, 더 작은 양자화를 사용하거나, flash attention을 활성화하여 KV 캐시를 축소하세요.

## KV 캐시 정밀도

KV 캐시는 모든 활성 시퀀스의 모든 토큰에 대한 key와 value 텐서를 저장합니다. 기본적으로 Ollama는 `f16`(16비트 부동 소수점)을 사용합니다. 양자화 정밀도로 전환하여 약간의 품질 비용으로 메모리 사용량을 줄일 수 있습니다.

캐시 타입은 `OLLAMA_KV_CACHE_TYPE` 환경 변수로 설정하세요:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_KV_CACHE_TYPE=q8_0"
sudo systemctl daemon-reload && systemctl restart ollama
```

| 캐시 타입 | 요소당 메모리 | 품질 | 사용 시기 |
| - | - | - | - |
| `f16` (기본) | 2 바이트 | 기준선 | 최대 품질; 메모리가 충분한 경우 |
| `q8_0` | 1 바이트 | f16과 거의 동일 | 최적 균형 — KV 캐시 메모리를 절반으로 줄이고 품질 손실은 미미 |
| `q4_0` | 0.5 바이트 | 약간 저하 | 메모리 부족; 긴 컨텍스트 또는 많은 동시 시퀀스 |

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Halve KV cache memory
OLLAMA_KV_CACHE_TYPE=q8_0

# Quarter KV cache memory
OLLAMA_KV_CACHE_TYPE=q4_0
```

> [!TIP]
>
> 가장 큰 메모리 이점을 위해 `OLLAMA_KV_CACHE_TYPE=q8_0`을 `OLLAMA_FLASH_ATTENTION=1`과 결합하세요. Flash attention은 KV 캐시 풋프린트를 30-50% 줄이고 q8\_0은 다시 절반으로 줄입니다. 함께 사용하면 기본값 대비 KV 캐시 메모리를 60-75%까지 줄일 수 있습니다.

> [!WARNING]
>
> `q4_0` KV 캐시는 긴 컨텍스트에 대한 정밀한 어텐션에 의존하는 작업(needle-in-a-haystack 검색, 멀티 문서 요약, 긴 대화)에서 측정 가능한 품질 손실을 유발합니다. `q4_0`로 결정하기 전에 특정 워크로드를 테스트하세요.

## 스레드 구성

추론에 사용하는 CPU 스레드 수는 `num_thread` 파라미터로 제어합니다. 적절한 값은 CPU가 실제로 얼마나 많은 작업을 수행하는지에 따라 다릅니다.

Modelfile이나 요청별로 설정하세요:

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_thread 8
```

```bash API theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Hello"}],
    "options": {
      "num_thread": 8
    }
  }'
```

전역 설정은 `OLLAMA_NUM_THREADS` 환경 변수로 할 수 있습니다:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_NUM_THREADS=8"
sudo systemctl daemon-reload && systemctl restart ollama
```

| 시나리오 | 스레드 가이드 |
| - | - |
| 전체 GPU 오프로드 (모든 레이어 GPU) | `num_thread 2`\~`num_thread 4` — CPU는 수학이 아닌 오케스트레이션과 토큰화 처리 |
| 부분 GPU 오프로드 (일부 레이어 CPU) | 설정 `num_thread` — CPU의 물리적 코어 수로, 하이퍼스레드 제외 |
| CPU 전용 (GPU 없음) | 설정 `num_thread` — 물리적 코어 수로 |

> [!WARNING]
>
> 스레드가 많다고 항상 더 빠른 것은 아닙니다. 물리적 코어 수를 넘으면 스레드가 캐시와 메모리 대역폭을 경쟁하여 추론을 느리게 할 수 있습니다. 확실하지 않으면 물리적 코어 수로 시작하여 벤치마크하세요.

Apple Silicon에서는 GPU와 CPU가 통합 메모리를 공유하고 MLX 백엔드가 스케줄링을 처리하므로 스레드 튜닝이 덜 중요합니다. 기본값이 일반적으로 잘 작동합니다.

## 배치 크기 튜닝

파라미터 `num_batch`는 prefill 단계(프롬프트 수집)에서 Ollama가 한 번에 처리하는 토큰 수를 제어합니다. 기본값은 512입니다.

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_batch 1024
```

| 설정 | 효과 |
| - | - |
| `num_batch 512` (기본) | 짧은 프롬프트가 있는 인터랙티브 채팅에 균형 |
| `num_batch 1024` | 긴 프롬프트의 더 빠른 prefill — 대략 50-100% 빠른 first-token까지 시간 |
| `num_batch 2048` | 문서 수집의 최대 처리량 — 최대 150% 빠른 prefill |
| `num_batch 2048+` | 수확 체감; 비례적인 속도 증가 없는 더 높은 메모리 사용량 |

> [!TIP]
>
> 짧은 프롬프트(1K 토큰 미만)가 있는 인터랙티브 채팅의 경우 기본 `num_batch 512`로 충분합니다. 긴 문서를 정기적으로 수집하고 first-token까지 시간을 빠르게 하고 싶은 경우에만 증가시키세요.

> [!WARNING]
>
> 더 큰 배치 크기는 프롬프트 수집 중에 더 많은 VRAM을 소비합니다. `num_batch`를 증가시켰는데 out-of-memory 오류가 발생하면 줄이거나 `num_ctx`를 낮추세요.

## 병렬 요청

`OLLAMA_NUM_PARALLEL`은 단일 모델이 동시에 처리하는 요청 수를 제어합니다. 기본값은 1입니다. Ollama는 로드된 모델당 한 번에 하나의 요청을 처리합니다.

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Allow 4 parallel requests per model
OLLAMA_NUM_PARALLEL=4
```

| 값 | 동작 |
| - | - |
| `1` (기본) | 한 번에 하나의 요청 — 요청당 최소 지연시간 |
| `2`\~`4` | 여러 요청이 GPU 공유 — 더 높은 처리량, 약간 더 높은 요청당 지연시간 |
| `8+` | 배치 워크로드의 최대 처리량 — KV 캐시에 상당한 VRAM 필요 |

> [!NOTE]
>
> RAM과 VRAM은 `OLLAMA_NUM_PARALLEL`에 따라 확장됩니다. 각 병렬 요청은 자체 KV 캐시가 필요합니다. `num_ctx 8192`로 4개의 병렬 요청을 제공하면 단일 요청 대비 4×의 KV 캐시 메모리가 필요합니다.

### 병렬 요청을 증가시켜야 하는 시기

다음 경우 `OLLAMA_NUM_PARALLEL`을 증가시키세요:

* 동일한 모델에서 여러 사용자나 에이전트를 제공하는 경우.
* 개별 요청 지연시간보다 총 처리량이 중요한 배치 워크로드를 실행하는 경우.
* VRAM 여유가 있고 단일 요청으로 GPU 활용도가 낮은 경우.

다음 경우에는 1로 유지하세요:

* 단일 사용자나 에이전트를 제공하는 경우.
* 처리량보다 낮은 지연시간을 우선시하는 경우.
* VRAM이 부족한 경우.

## 모델 메모리 관리

### 모델 로드 상태 유지 — `OLLAMA_KEEP_ALIVE`

기본적으로 Ollama는 5분 동안 비활성 상태면 모델이 메모리에서 언로드됩니다. 다음 요청은 모델이 디스크에서 다시 로드해야 하며, 모델 크기와 디스크 속도에 따라 몇 초에서 몇 분이 걸립니다.

모델이 로드된 상태로 유지되는 시간을 제어하려면 `OLLAMA_KEEP_ALIVE`를 설정하세요:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Keep models loaded indefinitely
OLLAMA_KEEP_ALIVE=-1

# Keep models loaded for 1 hour
OLLAMA_KEEP_ALIVE=1h

# Unload models immediately after each request
OLLAMA_KEEP_ALIVE=0
```

| 값 | 동작 |
| - | - |
| `5m` (기본) | 5분 비활성 후 언로드 |
| `-1` | 무기한 로드 상태 유지 — 다시 로드 페널티 없음 |
| `0` | 각 요청 후 즉시 언로드 |
| 기간 (`1h`, `30m`, `24h`) | 마지막 요청 후 해당 기간 동안 로드 상태 유지 |

> [!TIP]
>
> 하루 종일 동일한 모델을 실행하는 전용 추론 서버의 경우 `OLLAMA_KEEP_ALIVE=-1`을 설정하세요. 모델이 메모리에 유지되고 모든 요청이 콜드 스타트 페널티 없이 즉시 응답을 받습니다.

### 로드된 모델 제한 — `OLLAMA_MAX_LOADED_MODELS`

Ollama는 여러 모델을 동시에 로드된 상태로 유지할 수 있습니다. 기본값은 3 × (GPU 수) 또는 CPU 전용의 경우 3입니다. 많은 모델을 제공하고 메모리 사용량을 제한하려면 이 값을 낮추세요:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Only keep 1 model loaded at a time
OLLAMA_MAX_LOADED_MODELS=1
```

제한에 도달하고 새 모델이 요청되면 Ollama는 가장 최근에 사용되지 않은 모델을 언로드하여 공간을 확보합니다.

## Apple Silicon 및 MLX 최적화

Ollama 0.19부터 Apple Silicon의 기본 백엔드는 Apple의 MLX 프레임워크입니다. MLX는 Apple의 통합 메모리 아키텍처에 최적화되어 있으며 M 시리즈 칩에서 llama.cpp보다 훨씬 빠른 추론을 제공합니다.

### 성능 이점

Ollama의 2026년 MLX 최적화 업데이트 벤치마크:

| 모델 | 양자화 | 토큰/초 (MLX) |
| - | - | - |
| Gemma 4 12B | NVFP4 | \~55 tok/s |
| Gemma 4 12B | Q4\_K\_M | \~46 tok/s |
| Llama 3.1 8B | Q4\_K\_M | \~70-80 tok/s |

MLX는 Apple Silicon에서 NVFP4 양자화도 지원합니다. 이는 near-BF16 품질을 4비트 메모리 풋프린트로 제공합니다. Q4 양자화의 품질 손실의 절반입니다.

### Apple Silicon 최적화 팁

1. **MLX 최적화 모델을 사용하세요.** Apple Silicon에서 모델을 pull하면 Ollama는 자동으로 MLX 백엔드를 사용합니다. 구성이 필요 없습니다.
2. **Flash attention은 항상 켜져 있습니다.** MLX는 기본적으로 최적화된 어텐션 커널을 사용합니다. `OLLAMA_FLASH_ATTENTION` 변수는 효과가 없습니다.
3. **통합 메모리는 전체 GPU 오프로드를 의미합니다.** Apple Silicon의 GPU는 전체 RAM 풀에 접근할 수 있으므로 `-ngl 999`(모든 레이어 GPU)가 모델과 KV 캐시가 통합 메모리에 맞는 한 작동합니다.
4. **메모리 예산을 늘리려면 `OLLAMA_KV_CACHE_TYPE=q8_0`** — KV 캐시를 절반으로 줄여 더 큰 모델이나 더 긴 컨텍스트를 실행할 수 있습니다.
5. **항상 켜져 있는 추론을 위해 `OLLAMA_KEEP_ALIVE=-1`** — 모델이 다시 로드 페널티 없이 통합 메모리에 유지됩니다.

> [!NOTE]
>
> 크로스 플랫폼 이동성이 필요하거나 NVIDIA GPU와 Mac에서 동일한 구성을 실행하려면 Apple Silicon에서 llama.cpp 백엔드를 사용하도록 Ollama를 강제할 수 있습니다. 백엔드 선택을 재정의하는 환경 변수는 Ollama 지원에 문의하거나 문서를 확인하세요.

## 예시 구성

### Mac Studio M2 Ultra — 128 GB 통합 메모리

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:70b-q4_K_M
PARAMETER num_ctx 32768
PARAMETER num_batch 1024
```

이 구성은 70B Q4 모델을 32K 컨텍스트 윈도우로 실행합니다. 128 GB 통합 메모리 풀은 \~40 GB 모델 가중치, \~16 GB의 KV 캐시(q8\_0)를 처리하고 4개의 병렬 요청을 위한 여유를 남깁니다. MLX는 Apple Silicon에서 최대 처리량을 제공합니다.

### NVIDIA RTX 4090 — 24 GB VRAM

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=2
OLLAMA_NUM_THREADS=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 16384
PARAMETER num_batch 1024
```

이 구성은 8B Q4 모델을 16K 컨텍스트 윈도우로 실행합니다. 24 GB VRAM은 \~5 GB 모델 가중치, flash attention을 적용한 \~4 GB KV 캐시(q8\_0)를 처리하고 2개의 병렬 요청을 위한 여유를 남깁니다. 4개의 CPU 스레드가 오케스트레이션과 토큰화를 처리합니다.

### Multi-GPU 서버 — 4× RTX 4090 (96 GB 총 VRAM)

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=8
OLLAMA_NUM_THREADS=8
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:70b-q4_K_M
PARAMETER num_ctx 8192
PARAMETER num_batch 2048
```

이 구성은 70B Q4 모델을 4개의 GPU에 걸쳐 실행합니다. Ollama는 사용 가능한 모든 GPU에 레이어를 자동 분배합니다. 96 GB 총 VRAM은 \~40 GB 모델 가중치, \~16 GB KV 캐시를 처리하고 8개의 병렬 요청을 위한 여유를 남깁니다. 큰 배치 크기는 배치 워크로드의 처리량을 극대화합니다.

### CPU 전용 서버 — 64 GB RAM, GPU 없음

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=1
OLLAMA_NUM_THREADS=16
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 8192
PARAMETER num_batch 512
PARAMETER num_gpu 0
```

이 구성은 8B Q4 모델을 전적으로 CPU에서 실행합니다. 16개의 스레드가 물리적 코어 수와 일치합니다. 작은 배치 크기와 단일 병렬 요청은 메모리 사용량을 관리 가능하게 유지합니다. 5-10 tok/s가 예상됩니다 — 인터랙티브 채팅에는 사용 가능하지만 배치 워크로드에는 아닙니다.

### 고처리량 배치 처리 — RTX 4090

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q4_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=8
OLLAMA_NUM_THREADS=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 4096
PARAMETER num_batch 2048
```

이 구성은 오프라인 배치 워크로드의 처리량을 극대화합니다. q4\_0 KV 캐시는 8개의 병렬 요청을 24 GB VRAM에서 처리할 수 있도록 메모리 사용량을 크게 줄입니다. 큰 배치 크기는 프롬프트 수집을 가속화합니다. 4K의 짧은 컨텍스트는 KV 캐시를 작게 유지합니다. 모든 병렬 요청에 걸쳐 초당 200-300 토큰이 예상됩니다.

### 낮은 지연시간 인터랙티브 서빙 — RTX 4090

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=1
OLLAMA_NUM_THREADS=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 8192
PARAMETER num_batch 512
```

이 구성은 인터랙티브 채팅의 지연시간을 최소화합니다. 단일 병렬 요청, 품질을 위한 q8\_0 KV 캐시, 적당한 배치 크기. first-token까지 시간이 500ms 미만이고 50-70 tok/s 디코드 속도가 예상됩니다.

## 일반적인 실수와 방지 방법

### 실수 1: num\_ctx를 너무 높게 설정

**문제:** "만약을 위해" `num_ctx 128000`을 설정했지만 프롬프트가 2K 토큰 미만입니다. 64 GB의 KV 캐시 메모리를 낭비했습니다.

**해결:** 실제 워크로드에 맞게 `num_ctx`를 설정하세요. 프롬프트가 4K 토큰 미만이면 `num_ctx 4096` 또는 `num_ctx 8192`를 사용하세요. API를 통해 특정 요청에 대해 나중에 증가시킬 수 있습니다.

### 실수 2: flash attention을 잊음

**문제:** flash attention이 활성화되지 않아 필요한 VRAM보다 30-50% 더 많이 사용하고 있습니다.

**해결:** 항상 `OLLAMA_FLASH_ATTENTION=1`을 설정하세요. 지원되는 하드웨어에서는 단점이 없습니다.

### 실수 3: 모델 언로드를 제어하지 않음

**문제:** 10분 휴식 후 요청을 다시 시작하면 Ollama가 디스크에서 모델을 다시 로드하므로 첫 요청이 30초 걸립니다.

**해결:** 항상 켜져 있는 추론을 위해 `OLLAMA_KEEP_ALIVE=-1`을 설정하세요. 모델이 메모리에 유지되고 모든 요청이 즉시 응답을 받습니다.

### 실수 4: GPU에서 너무 많은 스레드 사용

**문제:** 32 스레드 CPU에 `num_thread 32`를 설정했지만 모든 레이어가 GPU에 있습니다. 추가 스레드가 캐시를 경쟁하고 오케스트레이션을 느리게 합니다.

**해결:** 모든 레이어가 GPU에 있으면 `num_thread 2`\~`num_thread 4`를 사용하세요. CPU는 추론 수학이 아닌 오케스트레이션과 토큰화만 처리합니다.

### 실수 5: KV 캐시 정밀도를 무시

**문제:** VRAM이 부족하고 Ollama가 레이어를 CPU로 오프로드하지만 KV 캐시가 필요한 메모리의 2×를 사용하고 있다는 것을 고려하지 않았습니다.

**해결:** KV 캐시 메모리를 절반으로 줄이려면 `OLLAMA_KV_CACHE_TYPE=q8_0`을 설정하세요. 이것이 품질과 메모리 절약의 최적 균형입니다.

### 실수 6: OLLAMA\_NUM\_PARALLEL을 너무 높게 설정

**문제:** 24 GB GPU에 `OLLAMA_NUM_PARALLEL=16`을 설정했고 이제 각 요청은 1.5 GB의 KV 캐시만 가집니다. 요청이 실패하거나 품질이 저하됩니다.

**해결:** KV 캐시 예산을 계산하세요: `(VRAM - model_weights) / num_parallel`. 요청당 1 GB 미만이 남으면 `num_parallel`을 줄이거나 `num_ctx`를 낮추세요.

## 문제 해결

### 시작 후 Ollama가 느림

**원인:** 모델이 언로드되었고 디스크에서 다시 로드해야 했습니다.

**해결:** 모델을 무기한 로드 상태로 유지하려면 `OLLAMA_KEEP_ALIVE=-1`을 설정하세요.

### Out of memory 오류

**원인:** 모델 + KV 캐시가 사용 가능한 VRAM 또는 RAM을 초과합니다.

**해결:** `num_ctx`를 줄이고, `OLLAMA_FLASH_ATTENTION=1`을 활성화하고, `OLLAMA_KV_CACHE_TYPE=q8_0`을 설정하거나, 더 작은 양자화를 사용하세요.

### GPU가 사용되지 않음

**원인:** Ollama가 GPU를 감지하지 못했거나 VRAM이 몇 개 레이어에도 너무 작습니다.

**해결:** `ollama ps`를 확인하여 레이어가 GPU에 있는지 확인하세요. NVIDIA GPU의 경우 NVIDIA 드라이버와 CUDA 툴킷이 설치되어 있는지 확인하세요. AMD GPU의 경우 ROCm이 설치되어 있는지 확인하세요.

### 느린 CPU 추론

**원인:** 너무 많은 스레드, 또는 GPU와 CPU 간에 분할된 레이어.

**해결:** 설정 `num_thread` — 물리적 코어 수로. 가능하다면 `num_gpu`로 더 많은 레이어를 GPU로 오프로드하세요. 더 많은 레이어를 GPU에 맞추기 위해 더 작은 양자화(Q4\_K\_M 또는 Q5\_K\_M)를 사용하세요.

## 다음 단계

> **[Ollama remote access](/ko/guides/ollama-remote-access.md)**
>
> 포트를 열거나 OLLAMA\_HOST=0.0.0.0을 설정하지 않고 Tokios를 통해 팀원과 에이전트에게 Ollama 모델을 노출하세요.

> **[Hardware reference](/ko/guides/hardware-reference.md)**
>
> 로컬 LLM 추론을 위한 하드웨어 플랫폼을 비교하세요 — 사양, 모델 용량, 권장 사항.

> **[Model fit finder](/ko/guides/model-fit.md)**
>
> 하드웨어에서 실행 가능한 모델을 찾거나 대상 모델을 실행할 수 있는 하드웨어를 찾으세요.

> **[배포 테스트](/ko/guides/benchmark-your-deployment.md)**
>
> 튜닝 후 지연시간과 처리량을 측정하여 개선을 확인하세요.

## 자주 묻는 질문

> **What is the best Ollama configuration for fast inference?**
>
> flash attention을 활성화하고(`OLLAMA_FLASH_ATTENTION=1`), 컨텍스트 윈도우를 작업이 실제로 필요로 하는 만큼 설정하고(모델 최댓값이 아님), 긴 컨텍스트를 위해 양자화된 KV 캐시를 사용하고(`OLLAMA_KV_CACHE_TYPE=q8_0` 또는 `q4_0`), 모델이 완전히 GPU 오프로드되었는지 확인하세요. 정확한 명령은 위의 섹션을 참조하세요.

> **How do I reduce Ollama memory usage?**
>
> 가장 큰 3가지 레버: (1) `num_ctx`를 낮춤 — 메모리는 컨텍스트 길이에 따라 선형적으로 확장, (2) `OLLAMA_KV_CACHE_TYPE=q4_0`으로 KV 캐시를 양자화하여 최대 75% KV 절약, (3) Q4\_0처럼 Q8\_0보다 작은 양자화의 모델 가중치 사용. Flash attention은 어텐션 메모리를 30-50% 절약합니다.

> **Does Ollama use MLX on Mac?**
>
> 예 — Ollama 0.19부터 Apple Silicon의 기본 백엔드는 llama.cpp가 아닌 Apple의 MLX 프레임워크입니다. MLX는 M 시리즈 칩에서 훨씬 빠른 추론을 제공합니다(55-80 tok/s를 M2 Ultra에서, llama.cpp에서는 25-40 tok/s). MLX는 항상 최적화된 어텐션 커널을 사용하므로 `OLLAMA_FLASH_ATTENTION` 변수는 MLX에 효과가 없습니다.

> **How many parallel requests can Ollama handle?**
>
> 병렬 처리를 위해 `OLLAMA_NUM_PARALLEL`을 설정하세요(기본 1). 각 병렬 슬롯은 KV 캐시를 위해 대략 20-30%의 메모리 오버헤드를 추가합니다. 7B 모델의 경우 Q4 양자화로 8K 컨텍스트에서 4개의 병렬 슬롯이 8 GB VRAM에 여유롭게 맞습니다. 더 큰 모델이나 더 긴 컨텍스트의 경우 2로 시작하여 측정하세요.

> **Why is Ollama slow to load my model?**
>
> 모델 로드 시간은 디스크에서 가중치를 읽고 GPU로 이동하는 시간이 지배적입니다. NVMe SSD를 사용하고(HDD 제외), `OLLAMA_KEEP_ALIVE`로 요청 간 모델을 따뜻하게 유지하고, `OLLAMA_MAX_LOADED_MODELS`로 축출과 다시 로드를 피하세요. Apple Silicon에서는 NVFP4 모델이 더 작아서 더 빠르게 로드됩니다.

> **What GPU offload settings should I use?**
>
> 기본적으로 Ollama는 GPU로 오프로드할 레이어 수를 자동 선택합니다. 최대 속도를 위해 `num_gpu`를 모델의 총 레이어 수로 설정하세요(완전히 오프로드). VRAM이 부족하면 `num_ctx`를 먼저 줄이세요 — `num_gpu`를 줄이기 전에. 모델을 완전히 GPU에 유지하는 것이 부분 오프로드보다 거의 항상 빠릅니다.

## Sources

* [Ollama FAQ](https://docs.ollama.com/faq) — 환경 변수 및 구성에 대한 공식 문서
* [Ollama Modelfile reference](https://docs.ollama.com/modelfile) — 파라미터 구문 및 유효한 값
* [Ollama MLX performance update](https://ollama.com/blog/mlx-performance) — 2026년 Apple Silicon 벤치마크 및 최적화
* [Ollama GPU scheduling deep dive](https://eastondev.com/blog/en/posts/ai/ollama-gpu-scheduling/) — VRAM 관리 및 멀티 GPU 동작
* [Ollama performance tuning: batching, KV cache, and OOM](https://eastondev.com/blog/en/posts/ai/20260410-ollama-performance-optimization/) — num\_batch 벤치마크 및 메모리 계산
* [Ollama environment variables: complete reference](https://modelpiper.com/blog/ollama-environment-variables) — v0.32.5 소스에 대해 감사됨

> [!NOTE]
>
> Ollama 구성을 변경한 후 Tokios 배포를 다시 등록하여 커넥터가 새 업스트림 엔드포인트를 수집하도록 하세요. [Register Model](/ko/setup/register-model.md)을 참조하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.