LocalAI'ı Docker Compose ile OpenAI uyumlu bir API olarak kurma

LocalAI; dil, görsel, konuşma ve embedding modellerini OpenAI API'siyle uyumlu bir REST API üzerinden sunan açık kaynaklı bir motordur. OpenAI API'si için yazılmış uygulamalar yalnızca temel adreslerini değiştirerek onu kullanabilir. Bir web arayüzü ve model galerisi içerir; bir model kurduğunuzda gereken çıkarım arka ucunu da indirir. Bu rehber LocalAI'ı resmi imajlardan Docker Compose ile çalıştırır, her istek için bir API anahtarı zorunlu kılar, galeriden bir model kurar, API'yi test eder, Caddy ile HTTPS üzerinden yayınlar ve yedekleme, güncelleme ile sorun gidermeyi anlatır.

Adım 1 — İmajı seçin

LocalAI aynı etiketleri Docker Hub (localai/localai) ve Quay (quay.io/go-skynet/local-ai) üzerinde yayınlar. Belgelerdeki örnekler Docker Hub'ı kullanır:

Bir sürümü sabitlemek için latest yerine GitHub'daki LocalAI sürümler sayfasından bir sürüm etiketi yazın. Eski rehberler önceden yapılandırılmış modeller içeren hepsi bir arada (-aio-) imajlardan söz eder; güncel konteyner belgeleri yalnızca yukarıdaki standart imajları listeler, bu yüzden bu rehber onları kullanır ve modelleri galeriden kurar.

Adım 2 — Proje klasörünü ve API anahtarını oluşturun

LocalAI'ın kullandığı dört klasörle birlikte proje klasörünü (konteyner yolları tam olarak /models, /backends, /configuration ve /data olmalıdır) ve .env içinde bir anahtar oluşturun:

sudo mkdir -p /opt/localai && sudo chown $USER:$USER /opt/localai
cd /opt/localai
mkdir -p models backends configuration data
echo "LOCALAI_API_KEY=$(openssl rand -hex 32)" > .env
chmod 600 .env

LOCALAI_API_KEY tek bir anahtar veya virgülle ayrılmış bir liste kabul eder. Klasik API anahtarları tam yönetici erişimi verir; anahtarı bir root parolası gibi koruyun.

Adım 3 — Compose dosyasını yazın

/opt/localai/compose.yaml dosyasını oluşturun. Bu dört bağlı klasörün dışındaki dosyalar konteyner yeniden oluşturulduğunda kaybolur; bu yüzden LocalAI'ın saklaması gereken her şey bunların içine gider:

services:
  localai:
    image: localai/localai:latest
    environment:
      LOCALAI_API_KEY: "${LOCALAI_API_KEY}"
    volumes:
      - ./models:/models
      - ./backends:/backends
      - ./configuration:/configuration
      - ./data:/data
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped

NVIDIA GPU için imajı localai/localai:latest-gpu-nvidia-cuda-12 (veya CUDA 13 etiketi) olarak değiştirin ve servise image: ile aynı girinti düzeyinde bir GPU rezervasyonu ekleyin:

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Adım 4 — LocalAI'ı başlatın ve API anahtarını kontrol edin

cd /opt/localai
docker compose up -d
docker compose logs -f localai

Log önce CPU özelliklerinin algılanmasını, ardından API adresini yazar. İzlemeyi bırakmak için Ctrl+C tuşlarına basın. Anahtarı kabuğunuza yükleyin ve sunucunun yanıt verdiğini ve anahtarı zorunlu tuttuğunu kontrol edin:

export LOCALAI_API_KEY=$(grep LOCALAI_API_KEY .env | cut -d= -f2)
curl -i http://127.0.0.1:8080/readyz
curl -i http://127.0.0.1:8080/v1/models
curl http://127.0.0.1:8080/v1/models -H "Authorization: Bearer $LOCALAI_API_KEY"

/readyz herkese açık bir sağlık denetimidir ve 200 döndürür. İkinci istek WWW-Authenticate: Bearer başlığıyla 401 döndürür, üçüncüsü ise boş bir model listesi döndürür. İstemciler anahtarı bearer token olarak veya x-api-key başlığıyla gönderebilir.

Adım 5 — Galeriden bir model kurun

En kolay yol web arayüzüdür. Bilgisayarınızdan bir SSH tüneli açın, tarayıcıda http://localhost:8080 adresine gidin ve giriş ekranında API anahtarınızı girin:

ssh -L 8080:127.0.0.1:8080 user@203.0.113.10

Models ve ardından Explore bölümüne gidin, qwen3-4b gibi bir model arayın (LocalAI hızlı başlangıcında kullanılan model) ve Install düğmesine tıklayın. Galeriye models.localai.io adresinden de göz atabilirsiniz. Komut satırından kurmak için galeri API'sini galeri adı ve model adıyla çağırın:

curl http://127.0.0.1:8080/models/apply \
  -H "Authorization: Bearer $LOCALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "localai@qwen3-4b"}'

Yanıt bir iş uuid değeri içerir. JOB_ID yerine bu değeri yazarak işi "processed":true bildirene kadar kontrol edin:

curl http://127.0.0.1:8080/models/jobs/JOB_ID -H "Authorization: Bearer $LOCALAI_API_KEY"

İlk kurulum modelin ihtiyaç duyduğu çıkarım arka ucunu da /opt/localai/backends içine indirir; bu yüzden sonrakilerden uzun sürer.

Adım 6 — OpenAI uyumlu API'yi test edin

Kurulan modele bir sohbet isteği gönderin:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer $LOCALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-4b", "messages": [{"role": "user", "content": "Hello!"}]}'

Yanıt choices[0].message.content alanında cevabı içerir. İlk istek modeli belleğe yüklediği için sonrakilerden yavaştır. OpenAI istemci kütüphaneleri temel adres olarak http://127.0.0.1:8080/v1, API anahtarı olarak da sizin anahtarınızla çalışır.

Adım 7 — LocalAI'ı Caddy ile HTTPS üzerinden yayınlayın

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

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

İstemciler artık temel adres olarak https://ai.example.com/v1 kullanır. Caddy web arayüzünü, akışlı yanıtları ve WebSocket bağlantılarını ek ayar gerektirmeden iletir.

İsteğe bağlı: ortak anahtar yerine kullanıcı hesapları

Ekipler için LocalAI; yönetici ve kullanıcı rolleri, kullanıcı başına API anahtarları ve kullanım takibi sunan çok kullanıcılı bir mod sağlar. Ortama LOCALAI_AUTH: "true" ekleyin ve docker compose up -d çalıştırın. İlk giriş yapan kullanıcı otomatik olarak yönetici yapılır; bu hesabı siteyi yayınlamadan önce SSH tüneli üzerinden oluşturun ya da yönetici yapılacak adresi LOCALAI_ADMIN_EMAIL ile belirleyin. Yeni kayıtlar varsayılan olarak onay bekler (LOCALAI_REGISTRATION_MODE=approval). Kullanıcı veritabanı, bağlı data klasörünün içindeki /data/database.db dosyasında saklanır.

Yedekleme ve geri yükleme

LocalAI'ın sakladığı her şey /opt/localai içindedir: models içinde kurulu model dosyaları ve yapılandırmaları, configuration içinde API anahtarı ve ayar dosyaları, data içinde kullanıcı veritabanı ve iş durumu, ayrıca compose.yaml ve .env. Arka uçlar yeniden indirilebilir. Veritabanının tutarlı olması için konteyneri durdurun, ardından klasörü arşivleyin:

sudo mkdir -p /opt/backups
cd /opt/localai
docker compose stop
sudo tar czf /opt/backups/localai-$(date +%F).tar.gz --exclude=./backends -C /opt/localai .
docker compose start

Model dosyaları büyük olabilir. Geri yüklemeden sonra modelleri galeriden yeniden kurmayı tercih ediyorsanız --exclude=./models seçeneğini de ekleyin. Geri yüklemek için arşivi boş bir /opt/localai klasörüne açın ve yığını başlatın:

sudo mkdir -p /opt/localai
sudo tar xzf /opt/backups/localai-YYYY-MM-DD.tar.gz -C /opt/localai
cd /opt/localai
docker compose up -d

Arşivleri sunucunun dışına kopyalayın; API anahtarınızı içerirler.

LocalAI'ı güncelleme

Önce LocalAI sürümler sayfasındaki sürüm notlarını okuyun; örneğin 4.9 sürümü kimlik doğrulamayı varsayılan olarak reddetme modeline geçirdi. Yedek alın, ardından yeni imajı çekip konteyneri yeniden oluşturun. Bağlı klasörlerdeki veriler korunur:

cd /opt/localai
docker compose pull
docker compose up -d
docker image prune

Bir sürüm etiketi sabitlediyseniz çekmeden önce onu compose.yaml içinde değiştirin.

Sorun giderme

401 Unauthorized

İstek geçerli bir anahtar taşımıyor. 4.9 sürümünden bu yana açıkça herkese açık olmayan her yol anahtar ister; /v1/models, /version ve üretilen görsel ile ses dosyalarının adresleri dahil. Anahtarı Authorization: Bearer ile, x-api-key başlığıyla veya istemci kütüphanenizde API anahtarı olarak gönderin.

Auto-detected mode as legacy

Bu NVIDIA hatası LocalAI'dan değil, konteyner çalışma ortamının yapılandırmasından kaynaklanır. sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi komutunun çalıştığını kontrol edin, sudo nvidia-ctk runtime configure --runtime=docker komutunu tekrarlayın ve Docker'ı yeniden başlatın. LocalAI belgeleri ilk çözüm olarak CDI'ya (driver: nvidia.com/gpu) geçmeyi önerir.

Sunucuda GPU olduğu hâlde modeller CPU'da çalışıyor

Yığın CPU imajını kullanıyor ya da GPU rezervasyonu eksik. image: satırını, deploy bloğunu ve docker compose exec localai nvidia-smi çıktısını kontrol edin. Değişikliklerden sonra konteyneri docker compose up -d ile yeniden oluşturun.

Bir model kurulumu başarısız oluyor veya hiç bitmiyor

docker compose logs localai çıktısını okuyun. Tipik nedenler dolu bir disk (df -h /opt/localai), galeriye veya Hugging Face'e giden HTTPS trafiğinin engellenmesi ya da model kimliğindeki bir yazım hatasıdır. Başarısız modeli web arayüzünden kaldırın ve yeniden kurun.

docker compose ps uzun süre health: starting gösteriyor

İmajın sağlık denetimi, modeller ve arka uçlar inerken uzun bir başlangıç süresine izin verir. /readyz yanıt verdiği sürece sunucu çalışıyordur; denetim başarılı olduğunda durum healthy olarak değişir.

Sonraki adımlar

• LocalAI'ı Open WebUI için OpenAI uyumlu bir arka uç olarak kullanın.
• Ollama, llama.cpp sunucusu ve vLLM ile karşılaştırın.
• LLM API hosting sayfasında bir sunucu seçin.
• Arka uçlar, galeriler ve tüm ayarlar için https://localai.io adresindeki resmi belgeleri okuyun.