LocalAI ile OpenAI API Uyumlu Yerel Yapay Zeka Sunucusu Kurulumu

Yazar:komut.io ekibi
0 Yorum

Yapay zeka araçlarını buluta bağımlı kalmadan çalıştırmak isteyen sistem yöneticileri için LocalAI tam anlamıyla bir oyun değiştirici. OpenAI API’siyle birebir uyumlu bu açık kaynak proje sayesinde kendi sunucunda GPT benzeri modeller çalıştırabilir, gizlilik kaygılarından kurtulabilir ve aylık abonelik maliyetlerini sıfıra indirebilirsin. Bu yazıda LocalAI kurulumundan model yönetimine, API entegrasyonundan production ortamı optimizasyonuna kadar her şeyi ele alacağız.

LocalAI Nedir ve Neden Önemli?

LocalAI, Go diliyle yazılmış, OpenAI REST API spesifikasyonuyla tam uyumlu bir yerel yapay zeka sunucusudur. Temel mantığı şu: Eğer uygulamanız OpenAI SDK’sı veya API’siyle çalışıyorsa, sadece endpoint URL’ini değiştirerek LocalAI’ye yönlendirebilirsiniz. Hiçbir kod değişikliği gerekmez.

Peki bu neden bu kadar önemli? Şunları düşün:

  • Veri gizliliği: Şirket içi belgeler, müşteri verileri veya hassas bilgiler hiçbir zaman dış sunuculara gönderilmez
  • Maliyet kontrolü: OpenAI API token maliyetleri yoğun kullanımda ciddi boyutlara ulaşabilir
  • Bant genişliği bağımsızlığı: İnternet bağlantısı olmadan bile çalışır
  • Model esnekliği: Llama, Mistral, Phi, Falcon ve onlarca farklı modeli çalıştırabilirsin
  • Özelleştirme: Fine-tuning yapılmış domain spesifik modelleri kolayca entegre edebilirsin

Gerçek dünya senaryosu olarak şunu hayal et: Hukuk bürosu için belge analiz sistemi kuruyorsun. Müvekkil sözleşmelerini OpenAI’ye göndermek hem hukuki hem de etik açıdan sorunlu. LocalAI bu noktada tam ihtiyacın olan çözümü sunuyor.

Sistem Gereksinimleri ve Ön Hazırlık

LocalAI CPU üzerinde de çalışabilir ama gerçekçi kullanım için GPU şiddetle tavsiye edilir. Minimum ve önerilen konfigürasyonlar şöyle sıralanabilir:

CPU modunda:

  • RAM: Çalıştıracağın modelin boyutunun en az 2 katı (7B model için minimum 16GB)
  • Depolama: Modeller için 50GB+ boş alan
  • CPU: Modern çok çekirdekli işlemci (AVX2 desteği önemli)

GPU modunda:

  • NVIDIA GPU: CUDA 11.7+ ile minimum 8GB VRAM (7B model için), 24GB+ (70B model için)
  • CUDA Toolkit: 11.7 veya üzeri
  • RAM: GPU VRAM’in en az 2 katı sistem RAM’i

Sistem hazırlığı için önce bağımlılıkları kuralım:

# Ubuntu/Debian için
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential cmake git wget curl 
    libopenblas-dev pkg-config libgrpc++-dev 
    protobuf-compiler-grpc python3-pip

# NVIDIA GPU varsa CUDA kurulumu kontrol et
nvidia-smi
nvcc --version

# Docker ve Docker Compose (önerilen yöntem için)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo apt install -y docker-compose-plugin

Docker ile LocalAI Kurulumu

En pratik ve sorunsuz kurulum yöntemi Docker’dır. Hem CPU hem GPU versiyonlarını ele alalım:

# Çalışma dizini oluştur
mkdir -p /opt/localai/{models,config,images}
cd /opt/localai

# CPU versiyonu için docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  localai:
    image: localai/localai:latest-cpu
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/build/models
      - ./config:/build/configuration
      - ./images:/tmp/generated/images
    environment:
      - THREADS=4
      - CONTEXT_SIZE=4096
      - DEBUG=false
      - GALLERIES=github:go-skynet/model-gallery/index.yaml
    deploy:
      resources:
        limits:
          memory: 16G
EOF

# GPU versiyonu için (NVIDIA)
cat > docker-compose-gpu.yml << 'EOF'
version: '3.8'

services:
  localai:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    container_name: localai-gpu
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/build/models
      - ./config:/build/configuration
    environment:
      - THREADS=8
      - CONTEXT_SIZE=8192
      - DEBUG=false
      - GPU_LAYERS=35
      - GALLERIES=github:go-skynet/model-gallery/index.yaml
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
EOF

# Başlatma
docker compose up -d
docker compose logs -f localai

Kaynak Derleme ile Kurulum

Docker kullanmak istemiyorsan veya maksimum performans gerekiyorsa kaynak koddan derleme yapabilirsin:

# Repository'i klonla
git clone https://github.com/mudler/LocalAI.git
cd LocalAI

# GPU desteğiyle derleme (NVIDIA)
make BUILD_TYPE=cublas build

# CPU optimizasyonlu derleme (AVX2)
make BUILD_TYPE=openblas build

# Sadece CPU (en geniş uyumluluk)
make build

# Çalıştırma
./local-ai --address ":8080" 
    --models-path ./models 
    --threads 8 
    --context-size 4096 
    --f16 
    --cors

Model İndirme ve Yapılandırma

LocalAI’nin en güçlü özelliklerinden biri model galerisi sistemidir. Doğrudan API üzerinden model indirebilirsin:

# Mevcut galeri modellerini listele
curl http://localhost:8080/models/available | python3 -m json.tool | grep '"name"' | head -20

# Model galeriden Mistral-7B indir
curl http://localhost:8080/models/apply -H "Content-Type: application/json" 
    -d '{"id": "mistral-openorca"}'

# İndirme durumunu kontrol et
curl http://localhost:8080/models/jobs/<job-id>

# Manuel model indirme (GGUF formatı)
cd /opt/localai/models
wget https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf

# Yüklü modelleri listele
curl http://localhost:8080/v1/models | python3 -m json.tool

Manuel olarak indirilen modeller için yapılandırma dosyası oluşturman gerekir:

# Model config dosyası oluştur
cat > /opt/localai/config/mistral-7b.yaml << 'EOF'
name: mistral-7b
backend: llama
parameters:
  model: mistral-7b-instruct-v0.2.Q4_K_M.gguf
  temperature: 0.7
  top_p: 0.9
  top_k: 40
  max_tokens: 2048
context_size: 4096
f16: true
threads: 8
gpu_layers: 35
template:
  chat: |
    {{.Input}}
  chat_message: |
    [INST] {{if .SystemPrompt}}{{.SystemPrompt}}

    {{end}}{{.Input}} [/INST]
EOF

API Kullanımı ve OpenAI Uyumluluğu

LocalAI’nin en kritik özelliği OpenAI API uyumluluğu. Mevcut kodunu neredeyse hiç değiştirmeden kullanabilirsin:

# Chat completions - OpenAI ile aynı format
curl http://localhost:8080/v1/chat/completions 
    -H "Content-Type: application/json" 
    -d '{
      "model": "mistral-7b",
      "messages": [
        {
          "role": "system",
          "content": "Sen yardımcı bir asistansın. Türkçe yanıt ver."
        },
        {
          "role": "user",
          "content": "Linux sisteminde disk kullanımını nasıl kontrol ederim?"
        }
      ],
      "temperature": 0.7,
      "max_tokens": 500
    }'

# Embeddings API
curl http://localhost:8080/v1/embeddings 
    -H "Content-Type: application/json" 
    -d '{
      "model": "text-embedding-ada-002",
      "input": "LocalAI harika bir araçtır"
    }'

# Python SDK ile kullanım (kod değişikliği olmadan)
python3 << 'PYEOF'
from openai import OpenAI

# Sadece base_url değişiyor, api_key dummy olabilir
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="localai-key"  # LocalAI bunu doğrulamaz
)

response = client.chat.completions.create(
    model="mistral-7b",
    messages=[
        {"role": "user", "content": "Merhaba, nasılsın?"}
    ]
)

print(response.choices[0].message.content)
PYEOF

Nginx ile Reverse Proxy ve SSL

Production ortamında LocalAI’yi doğrudan expose etmek yerine Nginx reverse proxy kullanmalısın:

# Nginx kurulumu
sudo apt install -y nginx certbot python3-certbot-nginx

# LocalAI için Nginx konfigürasyonu
sudo cat > /etc/nginx/sites-available/localai << 'EOF'
upstream localai_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 80;
    server_name ai.sirketim.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ai.sirketim.com;

    ssl_certificate /etc/letsencrypt/live/ai.sirketim.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.sirketim.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # API Key authentication
    auth_request /auth;

    # Büyük yanıtlar ve uzun inference süresi için timeout artır
    proxy_read_timeout 300s;
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    
    # Streaming yanıtlar için
    proxy_buffering off;
    proxy_cache off;

    location / {
        proxy_pass http://localai_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Rate limiting
    limit_req_zone $binary_remote_addr zone=localai:10m rate=10r/m;
    
    location /v1/ {
        limit_req zone=localai burst=5 nodelay;
        proxy_pass http://localai_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}
EOF

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

# SSL sertifikası al
sudo certbot --nginx -d ai.sirketim.com

Performans Optimizasyonu ve İzleme

LocalAI’yi production’da çalıştırırken performans kritik önem taşır:

# Sistem düzeyinde optimizasyonlar
# Huge pages aktifleştir (özellikle büyük modeller için)
echo 'vm.nr_hugepages = 1024' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# CPU governor performans moduna al
for cpu in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do
    echo performance | sudo tee $cpu
done

# LocalAI metrics ve monitoring scripti
cat > /opt/localai/monitor.sh << 'SCRIPT'
#!/bin/bash
ENDPOINT="http://localhost:8080"
LOG_FILE="/var/log/localai-monitor.log"
ALERT_EMAIL="[email protected]"

check_health() {
    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$ENDPOINT/readyz")
    if [ "$HTTP_CODE" != "200" ]; then
        echo "$(date): LocalAI down! HTTP: $HTTP_CODE" >> $LOG_FILE
        # Container'ı yeniden başlat
        docker compose -f /opt/localai/docker-compose.yml restart localai
        echo "$(date): Restart triggered" >> $LOG_FILE
        # Mail gönder
        echo "LocalAI yeniden başlatıldı - $(date)" | mail -s "LocalAI Alert" $ALERT_EMAIL
    else
        echo "$(date): OK - HTTP $HTTP_CODE" >> $LOG_FILE
    fi
}

# GPU kullanım bilgisi
if command -v nvidia-smi &> /dev/null; then
    GPU_UTIL=$(nvidia-smi --query-gpu=utilization.gpu --format=csv,noheader,nounits)
    GPU_MEM=$(nvidia-smi --query-gpu=memory.used,memory.total --format=csv,noheader)
    echo "$(date): GPU Util: ${GPU_UTIL}% | Memory: $GPU_MEM" >> $LOG_FILE
fi

check_health
SCRIPT

chmod +x /opt/localai/monitor.sh

# Cron'a ekle - her 5 dakikada kontrol
(crontab -l 2>/dev/null; echo "*/5 * * * * /opt/localai/monitor.sh") | crontab -

Gerçek Dünya Senaryosu: Şirket İçi Chatbot

Bir yazılım şirketinde geliştirici destek botu kurduğunu düşün. İç wiki, confluence sayfaları ve şirket dokümantasyonu üzerine sorular yanıtlayan bir sistem:

# LocalAI + RAG (Retrieval Augmented Generation) için basit wrapper script
cat > /opt/localai/company-bot.py << 'PYEOF'
#!/usr/bin/env python3
from openai import OpenAI
import sys
import json

# Şirket içi bilgi tabanı (gerçekte vector DB kullanılır)
COMPANY_CONTEXT = """
Şirket VPN: vpn.sirketim.com, Cisco AnyConnect kullan
Git sunucusu: git.sirketim.com (Gitea)
CI/CD: jenkins.sirketim.com
Monitoring: grafana.sirketim.com
Deployment: Kubernetes cluster, kubectl ile yönetim
On-call: Slack #alerts kanalı, PagerDuty entegrasyonu
"""

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="dummy"
)

def ask_company_bot(question: str) -> str:
    response = client.chat.completions.create(
        model="mistral-7b",
        messages=[
            {
                "role": "system",
                "content": f"""Sen bir şirket içi teknik destek asistanısın.
                Aşağıdaki şirket bilgilerini kullanarak sorulara yanıt ver.
                Bilmediğin konularda #tech-support Slack kanalına yönlendir.
                
                Şirket Bilgileri:
                {COMPANY_CONTEXT}"""
            },
            {
                "role": "user",
                "content": question
            }
        ],
        temperature=0.3,
        max_tokens=500
    )
    return response.choices[0].message.content

if __name__ == "__main__":
    question = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else "Merhaba"
    print(ask_company_bot(question))
PYEOF

chmod +x /opt/localai/company-bot.py

# Test
python3 /opt/localai/company-bot.py "VPN'e nasıl bağlanırım?"
python3 /opt/localai/company-bot.py "Git repomuza nasıl erişirim?"

Çoklu Model Yönetimi ve Yük Dengeleme

Production ortamında farklı görevler için farklı modeller kullanmak yaygın bir ihtiyaçtır:

# Birden fazla LocalAI instance yük dengeleme ile
cat > /opt/localai/docker-compose-cluster.yml << 'EOF'
version: '3.8'

services:
  # Hızlı yanıt gerektiren görevler için küçük model
  localai-fast:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    ports:
      - "8081:8080"
    volumes:
      - ./models:/build/models
    environment:
      - GPU_LAYERS=35
      - THREADS=4
      - PRELOAD_MODELS=phi-2
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ['0']
              capabilities: [gpu]

  # Karmaşık görevler için büyük model
  localai-powerful:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    ports:
      - "8082:8080"
    volumes:
      - ./models:/build/models
    environment:
      - GPU_LAYERS=40
      - THREADS=8
      - PRELOAD_MODELS=mistral-7b
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ['1']
              capabilities: [gpu]
EOF

# HAProxy ile akıllı yük dengeleme
sudo apt install -y haproxy

sudo cat > /etc/haproxy/haproxy.cfg << 'EOF'
frontend localai_frontend
    bind *:8080
    default_backend localai_backends

backend localai_backends
    balance roundrobin
    option httpchk GET /readyz
    server localai1 127.0.0.1:8081 check inter 30s
    server localai2 127.0.0.1:8082 check inter 30s
EOF

sudo systemctl restart haproxy

Güvenlik Sıkılaştırması

LocalAI’yi güvenli şekilde çalıştırmak için bazı önemli adımlar var:

# API Key middleware - basit token doğrulama
# Nginx'te API key kontrolü için Lua scripti (nginx-extras gerekli)
sudo apt install -y libnginx-mod-http-lua

# Basit API key yönetimi için environment değişkeni
# LocalAI'de API_KEY ayarla
cat >> /opt/localai/docker-compose.yml << 'EOF'
    environment:
      - API_KEY=gizli-api-anahtarin-buraya
EOF

# Güvenlik duvarı kuralları
sudo ufw enable
# Sadece Nginx'ten gelen bağlantılara izin ver
sudo ufw allow from 127.0.0.1 to any port 8080
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp

# Docker network izolasyonu
docker network create --internal localai-internal
# docker-compose.yml'de network tanımla

# Log rotasyonu
cat > /etc/logrotate.d/localai << 'EOF'
/var/log/localai*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 640 root adm
}
EOF

# systemd servisi olarak çalıştırma
cat > /etc/systemd/system/localai.service << 'EOF'
[Unit]
Description=LocalAI Service
After=docker.service
Requires=docker.service

[Service]
Type=simple
WorkingDirectory=/opt/localai
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable localai
sudo systemctl start localai

Yaygın Sorunlar ve Çözümleri

LocalAI ile çalışırken karşılaşacağın sorunlar ve çözümleri şöyle özetlenebilir:

“Model not found” hatası:

  • Model dosyasının /build/models dizininde olduğunu kontrol et
  • Config dosyasında model adının dosya adıyla eşleştiğini doğrula
  • docker exec localai ls /build/models komutuyla container içini kontrol et

Yavaş inference:

  • GPU_LAYERS parametresini modele göre optimize et (7B için 32-35, 13B için 40-43)
  • THREADS değerini CPU çekirdeğinin 75%’ine ayarla
  • F16 precision’ı aktif et: f16: true
  • Küçük context size daha hızlı sonuç verir

Out of Memory hatası:

  • Daha düşük quantization kullan (Q4_K_M yerine Q3_K_S)
  • GPU_LAYERS değerini düşür, bir kısmını CPU’ya bırak
  • Paralel istek sayısını sınırla: PARALLEL_REQUESTS=1

Container her seferinde yavaş başlıyor:

  • PRELOAD_MODELS env değişkeniyle modeli startup’ta yükle
  • Bu sayede ilk istek gecikme yaşamaz

Sonuç

LocalAI, yapay zeka yeteneklerini tamamen kendi kontrolünde ve altyapında çalıştırmak isteyen sistem yöneticileri için olgun ve production’a hazır bir çözüm. OpenAI API uyumluluğu sayesinde mevcut entegrasyonları bozmadan çok hızlı geçiş yapabiliyorsun.

En önemli takeaway’ler şunlar:

  • Docker ile kur: En hızlı ve sorunsuz yöntem. GPU desteği için nvidia-docker gerektiğini unutma.
  • Modeli işe göre seç: Her şey için büyük model şart değil. Phi-2 veya Mistral-7B çoğu görev için yeterli.
  • GGUF formatı kullan: HuggingFace’ten indirirken Q4_K_M quantization genellikle kalite/hız dengesi için en iyi seçenek.
  • Nginx reverse proxy: Production’da asla LocalAI’yi direkt expose etme.
  • İzleme şart: Inference süresi, GPU kullanımı ve memory metrikleri takip etmeden production’da sorun yaşarsın.

Küçük bir şirketin sysadmin’iysen aylık OpenAI maliyetleri bile can sıkıcı boyutlara ulaşabiliyor. LocalAI ile bu maliyeti bir kez aldığın sunucu donanımına dönüştürebilir, uzun vadede hem para hem veri güvenliği kazanabilirsin. Başlangıç için 8GB VRAM’li bir GPU ve Mistral-7B ile yola çıkman yeterli; ihtiyaç büyüdükçe ölçeklendirebilirsin.

Bir yanıt yazın

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