LocalAI Kurulumu: Docker ile Hızlı Başlangıç

Yazar:komut.io ekibi
0 Yorum

Kendi sunucunda yapay zeka modeli çalıştırmak artık hayal değil. Bulut tabanlı AI servislerine ödeme yapmak yerine, kendi donanımında tam kontrol sahibi olarak LLM (Large Language Model) çalıştırmak istiyorsan, LocalAI tam da aradığın araç. Bu yazıda Docker kullanarak LocalAI’yi sıfırdan nasıl kuracağını, yapılandıracağını ve production ortamında nasıl kullanabileceğini adım adım anlatacağım.

LocalAI Nedir ve Neden Kullanmalısın?

LocalAI, OpenAI API’si ile uyumlu, açık kaynaklı bir API sunucusudur. Yani mevcut uygulamanı OpenAI’ye bağlarken kullandığın endpoint’i LocalAI’ye yönlendirirsen, kod değişikliği yapmadan kendi sunucundaki modeli kullanabilirsin. Bu özellik tek başına bile LocalAI’yi son derece değerli kılıyor.

Birkaç somut senaryo düşün: Müşteri verilerini üçüncü parti servislere göndermek istemediğin bir proje, internet bağlantısı kısıtlı olan bir edge ortamı ya da OpenAI faturalarının kontrolden çıktığı bir startup. Bunların hepsinde LocalAI mantıklı bir tercih.

LocalAI’nin desteklediği özellikler oldukça geniş:

  • Text generation: LLaMA, Mistral, Phi, Gemma gibi modeller
  • Image generation: Stable Diffusion entegrasyonu
  • Speech to text: Whisper modeli desteği
  • Text to speech: Piper ve diğer TTS motorları
  • Embeddings: Semantic search ve RAG uygulamaları için
  • Vision: Çok modlu (multimodal) modeller

Sistem Gereksinimleri

Kuruluma geçmeden önce hangi donanımda çalıştığını netleştirmek gerekiyor. LocalAI CPU’da da çalışır ama performans beklentin buna göre şekillenmeli.

CPU ile çalıştırma:

  • Minimum RAM: 8GB (küçük modeller için)
  • Önerilen RAM: 16GB ve üzeri
  • Model boyutu: 7B parametreli model için yaklaşık 4-8GB RAM (quantization seviyesine göre)

GPU ile çalıştırma (NVIDIA):

  • CUDA 11.7 veya üzeri
  • 8GB VRAM: 7B modeller için yeterli
  • 16GB+ VRAM: 13B ve üzeri modeller için

Disk alanı:

  • LocalAI image: yaklaşık 10-15GB (backend’lere göre değişir)
  • Modeller: 7B model için 4-8GB (quantization’a bağlı)

Docker ve Docker Compose Kurulumu

Sisteminde Docker yoksa önce onu kuralım. Ubuntu/Debian üzerinde:

# Eski Docker sürümlerini temizle
sudo apt-get remove docker docker-engine docker.io containerd runc

# Gerekli paketleri kur
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Docker GPG anahtarını ekle
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Repository ekle
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker'ı kur
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Kullanıcını docker grubuna ekle (sudo olmadan çalıştırabilmek için)
sudo usermod -aG docker $USER
newgrp docker

Kurulumu doğrula:

docker --version
docker compose version

LocalAI için Dizin Yapısını Hazırla

Düzenli bir yapı kurmak, ileride yönetimi kolaylaştırır. Şu şekilde bir dizin hiyerarşisi oluşturalım:

mkdir -p /opt/localai/{models,config,images}
cd /opt/localai

Bu dizinlerin anlamları:

  • /opt/localai/models: İndireceğimiz model dosyaları burada duracak
  • /opt/localai/config: Model yapılandırma dosyaları (YAML)
  • /opt/localai/images: Image generation için çıktılar

Docker Compose ile LocalAI Kurulumu

CPU tabanlı kurulum için temel bir docker-compose.yml dosyası oluşturalım:

cat > /opt/localai/docker-compose.yml << 'EOF'
version: '3.8'

services:
  localai:
    image: localai/localai:latest-aio-cpu
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - THREADS=4
      - CONTEXT_SIZE=4096
      - DEBUG=false
      - GALLERIES=[{"name":"model-gallery","url":"github:go-skynet/model-gallery/index.yaml"},{"name":"huggingface","url":"github:go-skynet/model-gallery/huggingface.yaml"}]
    volumes:
      - /opt/localai/models:/build/models
      - /opt/localai/config:/build/config
      - /opt/localai/images:/tmp/generated/images
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/readyz"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s

EOF

NVIDIA GPU’n varsa farklı bir image kullanman gerekiyor:

cat > /opt/localai/docker-compose-gpu.yml << 'EOF'
version: '3.8'

services:
  localai:
    image: localai/localai:latest-aio-gpu-nvidia-cuda-12
    container_name: localai-gpu
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - THREADS=8
      - CONTEXT_SIZE=8192
      - DEBUG=false
    volumes:
      - /opt/localai/models:/build/models
      - /opt/localai/config:/build/config
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

EOF

Container’ı başlat:

cd /opt/localai
docker compose up -d

# Logları takip et
docker compose logs -f

İlk başlatmada LocalAI gerekli backend dosyalarını indireceği için birkaç dakika beklemen gerekebilir. Hazır olduğunu şu komutla kontrol edebilirsin:

curl http://localhost:8080/readyz

{"status":"ok"} cevabını görürsen sistem hazır demektir.

Model İndirme ve Yapılandırma

LocalAI iki farklı yöntemle model yüklemeni sağlıyor: API üzerinden galeri kullanarak ya da manuel dosya kopyalayarak. Önce API yöntemini görelim.

Galeri Üzerinden Model Kurulumu

Mevcut modelleri listele:

curl http://localhost:8080/models/available | python3 -m json.tool | head -50

Mistral 7B modelini kur:

curl http://localhost:8080/models/apply -H "Content-Type: application/json" -d '{
  "id": "mistral-openorca",
  "name": "mistral"
}'

Kurulum durumunu takip et:

# Job ID'yi al ve durumu kontrol et
curl http://localhost:8080/models/jobs/<JOB_ID>

Manuel Model Kurulumu

Hugging Face’den direkt model indirmek istiyorsan:

cd /opt/localai/models

# llama.cpp formatında (GGUF) bir model indir
# Örnek: Mistral 7B Q4_K_M quantization
wget https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf

# Daha hızlı indirme için aria2c kullanabilirsin
# sudo apt install aria2
# aria2c -x 16 -s 16 <URL>

Model Yapılandırma Dosyası

GGUF dosyasını indirdikten sonra LocalAI’nin bu modeli nasıl kullanacağını belirten bir YAML config dosyası oluşturman gerekiyor:

cat > /opt/localai/config/mistral.yaml << 'EOF'
name: mistral
backend: llama
parameters:
  model: mistral-7b-instruct-v0.2.Q4_K_M.gguf
  context_size: 4096
  threads: 4
  f16: true
  mmap: true
template:
  chat_message: |
    {{if eq .RoleName "system"}}[INST] {{.Content}} [/INST]
    {{else if eq .RoleName "user"}}[INST] {{.Content}} [/INST]
    {{else if eq .RoleName "assistant"}}{{.Content}}
    {{end}}
  chat: |
    {{.Input}}
EOF

Config dosyasını oluşturduktan sonra container’ı restart etmen gerekmiyor, LocalAI yeni config dosyalarını otomatik algılar.

API’yi Test Etme

Model hazır olduktan sonra birkaç test yapalım. LocalAI, OpenAI API formatını kullandığı için curl ile kolayca test edebilirsin:

# Modelleri listele
curl http://localhost:8080/v1/models

# Chat completion testi
curl http://localhost:8080/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{
    "model": "mistral",
    "messages": [
      {
        "role": "system",
        "content": "Sen yardımcı bir asistan. Türkçe cevap ver."
      },
      {
        "role": "user",
        "content": "Docker nedir? Kısaca açıkla."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Embeddings testi:

curl http://localhost:8080/v1/embeddings 
  -H "Content-Type: application/json" 
  -d '{
    "model": "text-embedding-ada-002",
    "input": "Bu bir test metnidir"
  }'

Python ile LocalAI Kullanımı

OpenAI Python kütüphanesini direkt LocalAI ile kullanabilirsin. Bu özellik migration’ı inanılmaz kolaylaştırıyor:

from openai import OpenAI

# LocalAI endpoint'ini kullan
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="dummy-key"  # LocalAI API key gerektirmez ama kütüphane ister
)

def chat_with_localai(user_message, system_prompt=None):
    messages = []
    
    if system_prompt:
        messages.append({"role": "system", "content": system_prompt})
    
    messages.append({"role": "user", "content": user_message})
    
    response = client.chat.completions.create(
        model="mistral",
        messages=messages,
        temperature=0.7,
        max_tokens=1000
    )
    
    return response.choices[0].message.content

# Kullanım örneği
result = chat_with_localai(
    "Linux'ta disk kullanımını nasıl izlerim?",
    system_prompt="Sen bir Linux sysadmin asistanısın. Pratik ve kısa cevaplar ver."
)
print(result)

Bu scripti çalıştırmadan önce kütüphaneyi yükle:

pip install openai
python3 localai_test.py

Nginx ile Reverse Proxy Kurulumu

Production ortamında LocalAI’yi direkt 8080 portundan yayınlamak yerine Nginx arkasına almak daha güvenli. Ayrıca SSL termination ve temel auth da ekleyebilirsin:

sudo apt install nginx apache2-utils -y

# Temel auth için kullanıcı oluştur
sudo htpasswd -c /etc/nginx/.htpasswd localai-user

# Nginx config oluştur
sudo cat > /etc/nginx/sites-available/localai << 'EOF'
server {
    listen 80;
    server_name ai.sunucun.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name ai.sunucun.com;

    ssl_certificate /etc/letsencrypt/live/ai.sunucun.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.sunucun.com/privkey.pem;

    # Büyük modeller için timeout değerlerini artır
    proxy_read_timeout 300s;
    proxy_connect_timeout 60s;
    proxy_send_timeout 300s;

    location / {
        auth_basic "LocalAI";
        auth_basic_user_file /etc/nginx/.htpasswd;

        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Streaming response için
        proxy_buffering off;
        proxy_cache off;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/localai /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Performans Optimizasyonu

Thread Ayarı

LocalAI’nin kaç CPU thread kullanacağını THREADS environment variable ile belirleyebilirsin. Genel kural: fiziksel CPU çekirdeğinin sayısı kadar thread kullan, hyperthreading çekirdeklerini dahil etme.

# CPU bilgisini öğren
nproc --all
lscpu | grep "Core(s) per socket"

# docker-compose.yml içinde environment kısmını güncelle
# Örnek: 8 fiziksel çekirdek için
THREADS=8

Quantization Seçimi

Model dosyası seçerken quantization seviyesi performans ve kalite arasındaki dengeyi belirler:

  • Q2_K: En küçük dosya, en düşük kalite
  • Q4_K_M: İyi denge noktası, çoğu kullanım için yeterli
  • Q5_K_M: Daha yüksek kalite, biraz daha fazla RAM
  • Q8_0: En yüksek kalite, neredeyse full precision

Ev sunucusu veya orta seviye VPS için Q4_K_M önerim.

Context Size

CONTEXT_SIZE veya config dosyasındaki context_size parametresi RAM kullanımını doğrudan etkiler. 4096 token çoğu chatbot kullanımı için yeterlidir. RAG uygulamaları için 8192 veya üstü düşünebilirsin.

İzleme ve Log Yönetimi

LocalAI container loglarını takip etmek için:

# Son 100 satır log
docker logs localai --tail 100

# Canlı log takibi
docker logs localai -f

# Hata loglarını filtrele
docker logs localai 2>&1 | grep -i "error|warn"

Sistem kaynak kullanımını izlemek için:

# Container kaynak kullanımı
docker stats localai

# Belirli aralıklarla kaydet
while true; do
  docker stats localai --no-stream >> /var/log/localai-stats.log
  sleep 60
done &

Prometheus ile entegrasyon istiyorsan LocalAI /metrics endpoint’i sunuyor. cAdvisor ile Docker metriklerini de toplayabilirsin ama bu konu başlı başına ayrı bir yazı.

Güvenlik Önlemleri

LocalAI’yi internet’e açmadan önce şu adımları tamamla:

API Key authentication için environment variable ekle:

# docker-compose.yml içine ekle
environment:
  - API_KEY=gizli-api-anahtarin-buraya

Firewall ile sadece gerekli portları aç:

# UFW ile sadece Nginx'e izin ver, direkt 8080 erişimini kapat
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw deny 8080/tcp
sudo ufw enable

Container’ı read-only filesystem ile çalıştırabilirsin ama model dizinleri için write izni gerektiğinden volumes dikkatli yapılandır.

Yaygın Sorunlar ve Çözümleri

Model yüklenmiyor, container beklemede kalıyor: Container ilk başlatmada backend dosyalarını indiriyor. Bağlantı hızına göre 10-30 dakika sürebilir. docker logs localai -f ile süreci izle.

Out of Memory hatası: Model için yeterli RAM yok. Daha düşük quantization (Q2_K veya Q3_K) dene ya da daha küçük parametre sayılı model seç (7B yerine 3B).

Yanıt çok yavaş geliyor: Thread sayısını artır, f16: true ayarını config’e ekle ve mmap özelliğini aktif et. GPU varsa CUDA versiyonuna geç.

Permission denied hataları: Model dizin izinlerini kontrol et:

sudo chown -R 1000:1000 /opt/localai/models
sudo chmod -R 755 /opt/localai/models

Config değişiklikleri geçerli olmuyor: Container’ı restart et ve cache’i temizle:

docker compose restart localai

Sonuç

LocalAI, kendi altyapında yapay zeka modeli çalıştırmak için olgun ve kullanımı kolay bir çözüm. Docker ile kurulum süreci oldukça straightforward ve OpenAI uyumlu API yapısı sayesinde mevcut projelerine entegre etmek minimal efor gerektiriyor.

Özellikle veri gizliliği önemli olan senaryolarda, maliyet kontrolü gerektiren yüksek hacimli uygulamalarda ve internet bağlantısına güvenmek istemediğin edge deployment’larda LocalAI güçlü bir tercih. 7B parametreli bir model, orta seviye bir sunucuda günlük kullanım için gayet yeterli yanıt kalitesi sunuyor.

Bir sonraki adım olarak birden fazla modeli aynı anda yönetmeyi, LocalAI’yi bir RAG pipeline’ına entegre etmeyi ve GPU optimizasyonlarını ele alacağım. Sorularını yorumlara bırakabilirsin, özellikle hangi model ve donanım kombinasyonunda çalıştığını merak ediyorum.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir