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

> LocalAI'ı CPU veya NVIDIA GPU üzerinde Docker Compose ile çalıştırın, API anahtarıyla koruyun, galeriden model kurun, Caddy ile HTTPS ekleyin ve yedekli tutun.

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

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.

## Ö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.
- [Ubuntu'ya Docker kurulumu](/guides/install-docker-ubuntu) veya [Debian'a Docker kurulumu](/guides/install-docker-debian) rehberiyle kurulmuş, Compose eklentili Docker Engine. LocalAI belgeleri konteyner yöntemini önerir.
- İsteğe bağlı, NVIDIA GPU'lar için: [vLLM kurulumu](/guides/install-vllm) rehberinin 1. ve 2. adımlarındaki gibi kurulmuş NVIDIA sürücüsü ve NVIDIA Container Toolkit. Uygun donanım için [GPU sunucuları](/gpu-servers) sayfasına bakın.
- Sunucuyu gösteren `ai.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; iş parçacığı sayısını fiziksel çekirdek sayısına ayarlayın |
| RAM | Yayınlanmamış | CPU üzerinde küçük, nicemlenmiş dil modelleri için 8 GB |
| GPU (isteğe bağlı) | Sürücü ve Container Toolkit ile NVIDIA; AMD ROCm, Intel ve Vulkan imajları mevcut | Kurduğunuz modeli alacak kadar VRAM |
| Disk | Yayınlanmamış | İmajlar, arka uçlar ve modeller için 50 GB boş alan |

LocalAI kurulum belgeleri sistem gereksinimi listelemez; önerilen değerler ölçüm sonucu değil, temkinli bir başlangıç noktasıdır. Her galeri modeli kendi ağırlıklarını indirir; disk alanını model başına planlayın.

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

| Donanım | İmaj |
|---|---|
| Yalnızca CPU | `localai/localai:latest` |
| NVIDIA GPU, CUDA 12 | `localai/localai:latest-gpu-nvidia-cuda-12` |
| NVIDIA GPU, CUDA 13 | `localai/localai:latest-gpu-nvidia-cuda-13` |
| AMD GPU (ROCm) | `localai/localai:latest-gpu-hipblas` |
| Intel GPU | `localai/localai:latest-gpu-intel` |
| Vulkan | `localai/localai:latest-gpu-vulkan` |

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:

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

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

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

> **Not**
>
> LocalAI'ın kendi Compose örneği CDI'ya dayanan ve NVIDIA Container Toolkit 1.14 veya daha yenisi için önerilen `driver: nvidia.com/gpu` ayarını kullanır. `driver: nvidia`, `nvidia-ctk runtime configure` ile yapılandırılan çalışma ortamıyla çalışır. Biri sisteminizde çalışmazsa diğerini deneyin.

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

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

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

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

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

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

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

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

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

> **Uyarı**
>
> 8080 portunu asla `"8080:8080"` olarak yayınlamayın ve erişilebilir bir adreste LocalAI'ı `LOCALAI_API_KEY` veya kullanıcı kimlik doğrulaması olmadan asla çalıştırmayın. Docker'ın yayınladığı portlar ufw'yi atlar; anahtar olmadan API, model kurulumu dahil her isteği kabul eder.

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

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

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

```bash
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](/guides/open-webui-ollama) için OpenAI uyumlu bir arka uç olarak kullanın.
- [Ollama](/guides/install-ollama), [llama.cpp sunucusu](/guides/llama-cpp-server) ve [vLLM](/guides/install-vllm) ile karşılaştırın.
- [LLM API hosting](/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.

## Sık sorulan sorular

### LocalAI ile Ollama arasındaki fark nedir?

İkisi de açık modelleri yerelde çalıştırır. LocalAI metin, görsel ve ses dahil birçok model türü için OpenAI uyumlu bir API'ye odaklanır ve çıkarım arka uçlarını galerisinden ihtiyaç halinde yükler. Ollama ise kendi kütüphanesi ve CLI aracıyla dil modellerine odaklanır.

### LocalAI API anahtarı gerektirir mi?

Yalnızca siz bir anahtar tanımlarsanız. LOCALAI_API_KEY veya kullanıcı kimlik doğrulaması yoksa sunucu istekleri kısıtlamaz. 4.9 sürümünden bu yana bir anahtar ayarlandığında açıkça herkese açık olmayan her yol, /v1/models ve /version dahil, anahtar ister.

### Hangi imajı kullanmalıyım, AIO imajlarına ne oldu?

Güncel konteyner belgeleri standart imajları listeler: CPU için localai/localai:latest, NVIDIA GPU'lar için latest-gpu-nvidia-cuda-12 veya latest-gpu-nvidia-cuda-13 gibi etiketler. Bu imajlar modelsiz başlar; ihtiyacınız olan modelleri galeriden kurarsınız.

### LocalAI modelleri ve verileri nerede saklar?

Konteyner içindeki /models, /backends, /configuration ve /data yollarında. Bu rehber bunları /opt/localai klasöründen bağlar; böylece konteyner güncellemelerinden sonra korunurlar ve tar ile yedeklenebilirler.

### Birden fazla kişi LocalAI'ı kendi hesaplarıyla kullanabilir mi?

Evet. Yönetici ve kullanıcı rollerine, kullanıcı başına API anahtarlarına sahip çok kullanıcılı mod için LOCALAI_AUTH=true ayarlayın. İlk giriş yapan kullanıcı yönetici olur; bu adımı siteyi yayınlamadan önce tamamlayın.

---

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