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

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.

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.

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:

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.

cd /opt/llama.cpp
cmake -B build
cmake --build build --config Release -j $(nproc)

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:

./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:

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:

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:

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:

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:

[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:

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:

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:

llm.example.com {
    reverse_proxy 127.0.0.1:8080
}

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 rehberini izleyin ve API konumu için proxy tamponlamayı (buffering) kapatın.

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):

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

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 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:

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:

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:

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, 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 rehberine bakın.
• NVIDIA GPU'larda yüksek kapasiteli sunum için vLLM kurulumu rehberine bakın.
• Kendi API'niz için sunucuları 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.