# llama.cpp sunucusunu OpenAI uyumlu bir API olarak çalıştırma

> llama.cpp'yi CPU veya NVIDIA CUDA için kaynaktan derleyin, GGUF modelleri API anahtarlı llama-server ile sunun, systemd ile çalıştırıp Caddy ile HTTPS ekleyin.

Zorluk: Orta\
Denendiği sistemler: Ubuntu 24.04 LTS, Ubuntu 26.04 LTS, Debian 12, Debian 13

llama.cpp, büyük dil modellerini GGUF biçiminde CPU ve GPU'larda çalıştırmak için geliştirilmiş, açık kaynaklı bir C/C++ motorudur. `llama-server` programı OpenAI uyumlu bir HTTP API'si (`/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`) ve küçük, yerleşik bir web arayüzü sunar. Bu rehber **llama.cpp'yi CMake ile kaynaktan derler** (CPU için veya NVIDIA CUDA ile), `llama-server`'ı Hugging Face'ten indirilen bir modelle test eder, onu `127.0.0.1` üzerinde API anahtarıyla **ayrı bir kullanıcı altında systemd servisi** olarak çalıştırır ve **Caddy** ile HTTPS üzerinden yayınlar. Resmi konteyner imajlarıyla bir Docker alternatifi de yer alır.

> **Not**
>
> llama.cpp README dosyası GitHub sürümler sayfasında hazır derlenmiş dosyalar ve bir kurulum betiği de sunar. Burada gösterildiği gibi kaynaktan derlemek, CUDA seçeneklerini seçmenizi ve kendi takviminizle güncellemenizi sağlar.

## Ön koşullar

- **Ubuntu 24.04 LTS**, **Ubuntu 26.04 LTS**, **Debian 12** veya **Debian 13** çalıştıran bir sunucu.
- `sudo` yetkisi olan, root olmayan bir kullanıcı; [Yeni bir Linux sunucusunu güvenli hale getirin](/guides/secure-a-new-linux-server) ve [SSH anahtarlarını ayarlayın](/guides/ssh-keys) rehberlerine bakın.
- İsteğe bağlı, GPU'ya aktarma için: çalışan bir sürücüye sahip NVIDIA GPU (`nvidia-smi` GPU'nuzu gösterir). [vLLM kurulumu](/guides/install-vllm) rehberinin 1. adımı sürücünün NVIDIA deposundan nasıl kurulacağını gösterir; uygun donanım için [GPU sunucuları](/gpu-servers) sayfasına bakın.
- Sunucu dışındaki istemcilerin API'ye ihtiyacı varsa sunucuyu gösteren `llm.example.com` gibi bir alan adı ve [Caddy ile reverse proxy](/guides/caddy-reverse-proxy) rehberine göre kurulmuş Caddy.

| Kaynak | En düşük (resmi) | Önerilen başlangıç |
|---|---|---|
| CPU | Yayınlanmamış | 4 vCPU; üretim fiziksel çekirdekleri kullanır |
| RAM | Yayınlanmamış | En az GGUF dosya boyutu, artı bağlam ve sistem için 2 ila 4 GB |
| GPU (isteğe bağlı) | CUDA derlemesi için CUDA toolkit kurulu bir NVIDIA GPU | Tüm katmanların GPU'da çalışması için modeli alacak kadar VRAM |
| Disk | Yayınlanmamış | Kaynak kod, derleme ve birkaç küçük model için 20 GB |

llama.cpp projesi en düşük gereksinim yayınlamaz. Önerilen değerler, model dosyasının belleğe sığması gerektiği pratik kuralına dayanan temkinli bir başlangıç noktasıdır, ölçüm sonucu değildir. Daha büyük bağlam boyutları ve daha fazla paralel slot daha fazla bellek ister.

## Adım 1 — Derleme araçlarını kurun

llama.cpp bir C/C++ derleyicisi, CMake ve Git ister. OpenSSL geliştirme paketini de kurun: `-hf` ile Hugging Face'ten yapılan indirmelerin kullandığı HTTPS desteği OpenSSL ile derlenir ve kütüphane mevcutsa varsayılan olarak etkindir.

```bash
sudo apt update
sudo apt install build-essential cmake git libssl-dev
```

Depoyu, sahibi yönetici kullanıcınız olan `/opt/llama.cpp` klasörüne klonlayın:

```bash
sudo mkdir -p /opt/llama.cpp && sudo chown $USER:$USER /opt/llama.cpp
git clone https://github.com/ggml-org/llama.cpp /opt/llama.cpp
cd /opt/llama.cpp
```

## Adım 2 — llama.cpp'yi derleyin

CPU derlemesini veya sunucuda NVIDIA GPU varsa CUDA derlemesini seçin. CUDA derlemesi `nvcc` derleyicisini sağlayan CUDA toolkit'e ihtiyaç duyar; bu paket sürücüyle aynı NVIDIA deposundan gelir.

**CPU**

```bash
cd /opt/llama.cpp
cmake -B build
cmake --build build --config Release -j $(nproc)
```
**NVIDIA CUDA**

```bash
sudo apt install cuda-toolkit
export PATH=/usr/local/cuda/bin:$PATH
nvcc --version
cd /opt/llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)
```

Derleme birkaç dakika sürer. CUDA derlemelerinde, derleme belgeleri işlemi GPU'nuzun compute capability değeriyle sınırlamanıza izin verir, örneğin `-DCMAKE_CUDA_ARCHITECTURES="86;89"`; bu derlemeyi kısaltır. NVIDIA kurulum rehberi toolkit'i `/usr/local/cuda-13.4` gibi sürümlü bir klasöre koyar; `/usr/local/cuda` normalde kurulu sürümü gösterir. Derlenen dosyalar `build/bin` içine yazılır. Sunucu programının çalıştığını kontrol edin:

```bash
./build/bin/llama-server --version
```

## Adım 3 — Bir GGUF modeliyle ilk testi yapın

`llama-server` bir modeli ya `-m` ile yerel bir GGUF dosyasından ya da `-hf user/model[:quant]` ile doğrudan Hugging Face'ten yükler; nicemleme etiketi verilmezse `Q4_K_M` dosyasını veya depodaki ilk dosyayı seçer. Projenin README dosyası örnek olarak küçük `ggml-org/Qwen3.5-0.8B-GGUF` modelini kullanır; ilk test için idealdir:

```bash
cd /opt/llama.cpp
./build/bin/llama-server -hf ggml-org/Qwen3.5-0.8B-GGUF --host 127.0.0.1 --port 8080 -c 8192
```

Sunucu modeli Hugging Face önbelleğinize (`~/.cache/huggingface/hub`) indirir, yükler ve `127.0.0.1:8080` üzerinde dinlediğini yazar. İkinci bir SSH oturumunda uç noktaları test edin:

```bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models
curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Write a haiku about servers"}]}'
```

`/health` model yüklendiğinde `{"status":"ok"}` döndürür (yüklenirken 503), sohbet isteği ise bir JSON yanıtı döndürür. Test sunucusunu `Ctrl+C` ile durdurun. En önemli seçenekler:

| Seçenek | Varsayılan | Amaç |
|---|---|---|
| `-m`, `--model` | yok | Yerel bir GGUF dosyasının yolu |
| `-hf`, `--hf-repo` | yok | Hugging Face'ten `user/model[:quant]` biçiminde model indirir |
| `-c`, `--ctx-size` | `0` (modelden alınır) | Token cinsinden bağlam boyutu; bellek kullanımını sınırlamak için açıkça ayarlayın |
| `-t`, `--threads` | `-1` (otomatik) | Üretim için kullanılan CPU iş parçacıkları |
| `-ngl`, `--n-gpu-layers` | `auto` | VRAM'de tutulan katmanlar: bir sayı, `auto` veya `all` |
| `-np`, `--parallel` | `-1` (otomatik) | Paralel istekler için sunucu slot sayısı |
| `--host`, `--port` | `127.0.0.1`, `8080` | Dinleme adresi ve portu |
| `--api-key` | yok | API anahtarı veya virgülle ayrılmış anahtarlar; `LLAMA_API_KEY` ile de verilir |
| `--no-webui` | web arayüzü açık | Yerleşik web arayüzünü kapatır |

Her seçeneğin bir ortam değişkeni de vardır (örneğin `LLAMA_ARG_CTX_SIZE`); hepsi sunucu README dosyasında listelenir.

## Adım 4 — Servis kullanıcısını ve API anahtarını oluşturun

Sunucuyu kendi model klasörü olan, yetkisiz ayrı bir kullanıcıyla çalıştırın ve API anahtarını süreç listesinde görünmemesi için yalnızca root'un okuyabildiği bir ortam dosyasında tutun:

```bash
sudo useradd --system --create-home --home-dir /var/lib/llama --shell /usr/sbin/nologin llama
sudo install -d -o llama -g llama /var/lib/llama/models
echo "LLAMA_API_KEY=$(openssl rand -hex 32)" | sudo tee /etc/llama-server.env > /dev/null
echo "LLAMA_CACHE=/var/lib/llama/models" | sudo tee -a /etc/llama-server.env > /dev/null
sudo chmod 600 /etc/llama-server.env
sudo cat /etc/llama-server.env
```

`LLAMA_CACHE`, llama.cpp'ye `-hf` indirmelerini nereye kaydedeceğini söyler; böylece servis modellerini `/var/lib/llama/models` içinde tutar. API anahtarını not edin; istemcilerin buna ihtiyacı olacak. Servis modeli kendi klasörüne yeniden indirir; bu yüzden test kopyasını daha sonra `~/.cache/huggingface/hub` içinden silebilirsiniz.

## Adım 5 — llama-server'ı systemd ile çalıştırın

`/etc/systemd/system/llama-server.service` dosyasını oluşturun:

```ini
[Unit]
Description=llama.cpp server
After=network-online.target
Wants=network-online.target

[Service]
User=llama
Group=llama
EnvironmentFile=/etc/llama-server.env
ExecStart=/opt/llama.cpp/build/bin/llama-server -hf ggml-org/Qwen3.5-0.8B-GGUF --host 127.0.0.1 --port 8080 -c 8192
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

Sunucuya kendiniz kopyaladığınız bir GGUF dosyasını sunmak için dosyayı `/var/lib/llama/models` içine koyun, sahibini `llama` kullanıcısı yapın ve `-hf ggml-org/Qwen3.5-0.8B-GGUF` yerine `-m /var/lib/llama/models/your-model.gguf` yazın. Servisi etkinleştirip başlatın ve model yüklenene kadar logu izleyin:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now llama-server
sudo journalctl -u llama-server -f
```

Şimdi API anahtarının zorunlu olduğunu kontrol edin. İlk istek `401` ile başarısız olmalı, ikincisi modeli listelemelidir:

```bash
KEY=$(sudo grep LLAMA_API_KEY /etc/llama-server.env | cut -d= -f2)
curl -i http://127.0.0.1:8080/v1/models
curl http://127.0.0.1:8080/v1/models -H "Authorization: Bearer $KEY"
```

Anahtar ayarlıyken API uç noktaları anahtar ister; `/health` ise izleme araçlarının sunucuyu kimlik bilgisi olmadan denetleyebilmesi için herkese açık kalır.

## Adım 6 — API'yi Caddy ile HTTPS üzerinden yayınlayın

`/etc/caddy/Caddyfile` dosyasına bir site bloğu ekleyin, Caddy'yi yeniden yükleyin ve güvenlik duvarında yalnızca SSH ve web trafiğine izin verin:

```caddyfile
llm.example.com {
    reverse_proxy 127.0.0.1:8080
}
```

```bash
sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```

OpenAI uyumlu istemciler artık temel adres olarak `https://llm.example.com/v1`, API anahtarı olarak da sizin anahtarınızı kullanır. Caddy, akışlı yanıtların server-sent events verisini ek ayar gerektirmeden iletir. Nginx tercih ediyorsanız [Nginx ve Certbot](/guides/nginx-reverse-proxy-certbot) rehberini izleyin ve API konumu için proxy tamponlamayı (buffering) kapatın.

> **Uyarı**
>
> Herkese açık bir sunucuda `llama-server`'ı API anahtarı ve güvenlik duvarı olmadan asla `--host 0.0.0.0` ile başlatmayın. Porta ulaşan herkes CPU veya GPU'nuzu kendi istekleri için kullanabilir.

## llama-server'ı Docker ile çalıştırma

Proje, konteyner imajlarını GitHub Container Registry üzerinde yayınlar: CPU için `ghcr.io/ggml-org/llama.cpp:server`, NVIDIA GPU'lar için `:server-cuda` (CUDA 12) ve `:server-cuda13`, ayrıca ROCm, Vulkan ve Intel çeşitleri. Sunucu imajı zaten konteynerin tüm adreslerinde dinler; bu yüzden portu yalnızca loopback adresinde yayınlayın. `/opt/llama-server/compose.yaml` dosyasını ve `LLAMA_API_KEY=` ile `openssl rand -hex 32` çıktısını içeren bir `.env` dosyası oluşturun (`chmod 600 .env`):

```yaml
services:
  llama-server:
    image: ghcr.io/ggml-org/llama.cpp:server
    command: ["-hf", "ggml-org/Qwen3.5-0.8B-GGUF", "--port", "8080", "-c", "8192"]
    environment:
      LLAMA_API_KEY: "${LLAMA_API_KEY}"
      LLAMA_CACHE: "/models"
    volumes:
      - ./models:/models
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped
```

```bash
cd /opt/llama-server
docker compose up -d
docker compose logs -f
```

NVIDIA GPU'lar için `ghcr.io/ggml-org/llama.cpp:server-cuda` imajını kullanın, NVIDIA Container Toolkit'i kurun ([vLLM kurulumu](/guides/install-vllm) rehberinin 2. adımı) ve servise `driver: nvidia`, `count: all` ve `capabilities: [gpu]` içeren bir `deploy.resources.reservations.devices` bloğu ekleyin. Belgeler, GPU imajlarının CI tarafından derlendiğini ve bunun ötesinde test edilmediğini belirtir. 8080 portunda Docker'ı ya da systemd servisini kullanın, ikisini birden değil.

## Yedekleme ve geri yükleme

Derlemenin kendisi her zaman yeniden oluşturulabilir. Saklamanız gereken yapılandırmadır; indirmeler yavaşsa veya dosyalar size aitse modeller de:

```bash
sudo mkdir -p /opt/backups
sudo tar czf /opt/backups/llama-server-$(date +%F).tar.gz /etc/llama-server.env /etc/systemd/system/llama-server.service /var/lib/llama/models
```

Arşiv API anahtarınızı içerir; onu anahtarın kendisi kadar özenle saklayın. Yeni bir sunucuya geri yüklemek için llama.cpp'yi 1. ve 2. adımlardaki gibi derleyin, 4. adımdaki `llama` kullanıcısını oluşturun, ardından arşivi açıp servisi yeniden başlatın:

```bash
sudo tar xzf /opt/backups/llama-server-YYYY-MM-DD.tar.gz -C /
sudo chown -R llama:llama /var/lib/llama
sudo systemctl daemon-reload
sudo systemctl enable --now llama-server
```

Arşivi sunucunun dışına da kopyalayın.

## llama.cpp'yi güncelleme

llama.cpp hızlı değişir ve GitHub sürümler sayfasında sık sık numaralı derlemeler yayınlar; güncellemeden önce sunucu seçeneklerindeki değişiklikler için sürüm notlarını okuyun. En son kodu çekin, aynı seçeneklerle yeniden derleyin (CMake bunları `build` klasöründe saklar) ve servisi yeniden başlatın:

```bash
cd /opt/llama.cpp
git pull
cmake -B build
cmake --build build --config Release -j $(nproc)
sudo systemctl restart llama-server
```

Yeni sürüm sorun çıkarırsa önceki sürüm etiketine `git checkout` ile dönüp yeniden derleyin. Docker kurulumunda `docker compose pull` ve `docker compose up -d` çalıştırın.

## Sorun giderme

### CMake CUDA'yı bulamıyor veya nvcc bulunamıyor

CUDA toolkit eksik ya da `PATH` içinde değil. `cuda-toolkit` paketini NVIDIA deposundan kurun, `export PATH=/usr/local/cuda/bin:$PATH` çalıştırın ve `nvcc --version` ile kontrol edin. Ardından `build` klasörünü silip `-DGGML_CUDA=ON` ile yeniden yapılandırın.

### API'den 401 Unauthorized

Sunucuda bir API anahtarı var ve istek anahtarı göndermedi ya da farklı bir anahtar gönderdi. `Authorization: Bearer` başlığının ardından `/etc/llama-server.env` içindeki anahtarı gönderin. OpenAI istemci kütüphanelerinde anahtarı `api_key` olarak ayarlayın.

### -hf ile indirmeler başarısız oluyor

llama.cpp HTTPS desteği olmadan derlenmiş; genellikle `libssl-dev` kurulu olmadığı için. Paketi kurun, `build` klasörünü silin ve yeniden derleyin. Erişimi kısıtlı (gated) veya özel depolar için `/etc/llama-server.env` dosyasına Hugging Face erişim token'ı içeren `HF_TOKEN=` satırını ekleyin.

### Model yüklenirken out of memory veya failed to allocate

Model ve bağlamı RAM'e veya VRAM'e sığmıyor. `-c` değerini düşürün, daha küçük bir nicemleme seçin (örneğin `:Q8_0` yerine `:Q4_K_M`), daha küçük bir model kullanın, `-np` değerini azaltın ya da modelin bir kısmı RAM'de kalsın diye `-ngl` değerini modelin katman sayısının altında bir sayıya ayarlayın.

### Servis permission denied ile başarısız oluyor

`llama` kullanıcısı ikili dosyayı okuyamıyor veya önbelleğine yazamıyor. `sudo -u llama ls /opt/llama.cpp/build/bin` ve `sudo -u llama touch /var/lib/llama/models/test` ile kontrol edin, sahipliği `sudo chown -R llama:llama /var/lib/llama` ile düzeltin.

## Sonraki adımlar

- Bir sohbet arayüzü bağlayın: [Open WebUI](/guides/open-webui-ollama), `https://llm.example.com/v1` adresini OpenAI uyumlu bir bağlantı olarak ekleyebilir.
- Yönetilen yaklaşımla karşılaştırmak için [Ollama kurulumu](/guides/install-ollama) rehberine bakın.
- NVIDIA GPU'larda yüksek kapasiteli sunum için [vLLM kurulumu](/guides/install-vllm) rehberine bakın.
- Kendi API'niz için sunucuları [LLM API hosting](/llm-api-hosting) sayfasında karşılaştırın.
- Tüm seçenekler için https://github.com/ggml-org/llama.cpp/tree/master/tools/server adresindeki sunucu belgelerini okuyun.

## Sık sorulan sorular

### llama.cpp ile Ollama arasındaki fark nedir?

llama.cpp çıkarım motorudur, llama-server ise onun HTTP sunucusudur. GGUF dosyasını, bağlam boyutunu, iş parçacıklarını ve GPU katmanlarını kendiniz seçersiniz. Ollama bunun üzerine bir model kütüphanesi ve kendi yönetim katmanını ekler. Bu ayarlar üzerinde doğrudan denetim istediğinizde llama-server kullanın.

### llama-server için GPU gerekli mi?

Hayır. llama.cpp GGUF modellerini CPU üzerinde çalıştırır. CUDA derlemesi katmanları bir NVIDIA GPU'ya aktarır ve varsayılan -ngl auto ayarıyla VRAM'e sığan kadar katmanı oraya yerleştirir.

### llama-server API'si korumalı mı?

Yalnızca --api-key, --api-key-file veya LLAMA_API_KEY değişkeniyle bir API anahtarı ayarlarsanız. Anahtar ayarlıyken API istekleri Authorization: Bearer başlığı ister, health uç noktası ise izleme için herkese açık kalır. Her durumda sunucuyu 127.0.0.1 üzerinde, bir reverse proxy arkasında tutun.

### -hf ile indirilen modeller nerede saklanır?

Sunucuyu çalıştıran kullanıcının Hugging Face önbelleğinde, varsayılan olarak ~/.cache/huggingface/hub içinde. Başka bir klasör kullanmak için bu rehberin servis kullanıcısı için yaptığı gibi LLAMA_CACHE değişkenini ayarlayın.

### Sunucum ne kadar büyük bir modeli çalıştırabilir?

llama.cpp projesi gereksinim yayınlamaz. Pratik bir kural olarak RAM veya VRAM'de en az GGUF dosyasının boyutu kadar alan ve bağlam için ek bellek gerekir; bu yüzden küçük, nicemlenmiş bir model ve sabit bir bağlam boyutuyla başlayın.

---

Kaynak: <https://hyperdc.com/tr/guides/tutorials/llama-cpp-server>\
Son güncelleme: 2026-10-09