İleri Konular

AI Yapay Zeka Servis (lokalde on-premise)

Bu Kılavuz, isimsoftware AI servisinin İleri sürümünü yerinde (on-premise) Talep Sistemi kurulumunuza yükler. Benzer makale önerileri ve bilgi tabanı araması gibi AI özelliklerini etkinleştirir. Bu sistem, kendi ağınızda çalışan küçük bir Docker yığını ile çalışır.

Ücretli eklenti. Yerinde AI servisi, Talep Sistemi kurulumunuz için ayrı olarak satılan lisanslı bir eklentidir ve çekirdek üründen bağımsızdır. Fiyatlandırma ve lisanslama için ürün sayfasına bakın.

Gereksinimler

  • isimsoftware Talep Sistemi v11.22 veya üzeri. AI servis yönetim arayüzü ve yerinde entegrasyon bağlantı noktaları 11.22 sürümünde eklendi — daha eski sürümler bu servisle iletişim kuramaz.
  • Docker Desktop (Windows) veya Docker Engine (Linux), 20.10 veya üzeri sürüm.
  • 4 GB boş RAM (2 GB Qdrant için, ~1.5 GB embedding modelleri için).
  • Sunucuda internet erişimi — Qdrant imajını çekmek, embedding modellerini ilk çalıştırmada indirmek ve (isteğe bağlı olarak) OpenAI’ye erişmek için gereklidir.
  • Açık bir TCP portu (varsayılan 5050), Talep Sistemi web sunucunuzdan erişilebilir olmalıdır.

1. Yayın paketini indirin

Lisansa ait e-posta içindeki güvenli indirme bağlantısını kullanarak isimsofrware_ai.zip dosyasını indirin. Sunucuda istediğiniz klasöre çıkarın:

unzip isimsofrware_ai.zip cd isimsofrware_ai

Paket şunları içerir:

  • ai.py, config.py, requirements.txt, Dockerfile, .dockerignore — Python kaynak kodları ve container yapılandırması. Docker ilk çalıştırmada imajı yerelde oluşturur; registry’den bir imaj çekilmez.
  • templates/ — AI container tarafından sunulan durum sayfası şablonu.
  • docker-compose.yml — iki servisli yapı (AI servisi + Qdrant).
  • .env.Örnek — gizli anahtar şablonu.
  • VERSION / version.txt — paket sürümü.
  • README.txt — bu Kılavuzun kopyası.

2. .env dosyasını oluşturun

cp .env.Örnek .env

.env dosyasını açın ve doldurun:

AI_API_KEY=<buraya rastgele 48 karakterlik hex bir anahtar girin> OPENAI_API_KEY=<OpenAI anahtarınız veya boş bırakın>

AI_API_KEY sizin oluşturduğunuz paylaşımlı bir gizli anahtardır — Talep Sistemi bu servise bununla kimlik doğrulaması yapar. Bu bir isimsoftware lisans anahtarı değildir: tamamen rastgele bir değer seçin ve 4. adımda aynı değeri Talep Sistemi içine girin.

Rastgele AI_API_KEY üretmek için:

  • Kendiniz oluşturabilirsiniz VEYA
  • Linux / macOS: openssl rand -hex 24
  • Windows PowerShell: -join (1..48 | % { '0123456789abcdef'[(Get-Random -Maximum 16)] })

OPENAI_API_KEY alanını boş bırakırsanız yalnızca yerel embedding modelleri kullanılır. Daha sonra değiştirebilirsiniz; ancak yerel modeller ile OpenAI arasında geçiş embedding boyutlarını değiştirdiği için bilgi tabanını yeniden indekslemeniz gerekir (5. adım).

3. Servisi başlatın

docker compose up -d

İlk çalıştırma birkaç dakika sürebilir:

  1. Docker AI imajını yerelde oluşturur (~1 dakika).
  2. Qdrant imajı Docker Hub’dan indirilir (~200 MB).
  3. İlk istekte embedding modeli Hugging Face üzerinden indirilir (~300 MB) ve fastembed_cache volume içine kaydedilir.

Sonraki çalıştırmalar hızlı olur — tüm içerik önbelleğe alınır.

Servisin çalıştığını doğrulayın:

docker compose ps

Her iki container da running durumunda olmalıdır.

Tarayıcıdan http://localhost:5050/ adresini açın. Açılan sayfada Qdrant bağlantısı, model cache durumu ve indeks bilgileri gibi kontroller yeşil olmalıdır.

Otomatik izleme için GET /healthz endpoint’i JSON sağlık durumu döner ve servis erişilemezse HTTP 503 verir. Bu endpoint x-API-key başlığı ister (AI_API_KEY ile aynı değer). Kimlik doğrulamasız istekler 401 döner.

4. Talep Sistemi’ni servise yönlendirin

Talep Sistemi’nde admin olarak giriş yapın ve Yönetim → AI Özellikler bölümünü açın. Kendi barındırılan AI servisi altında:

  • Servis URL: http://<ai-host>:5050
  • API Anahtarı: .env dosyasındaki AI_API_KEY ile aynı değer

<ai-host> yerine servis aynı makinedeyse localhost, değilse LAN IP/hostname yazın. Kaydet’e tıklayın — uygulama yeniden başlatmaya gerek yoktur.

Eski sürümden yükseltme? Eğer daha önce appsettings.json içinde AIUrl/AIKey

5. Bilgi Bankasını indeksleyin

Servis URL’sini kaydettiğinizde indeksleme otomatik olarak başlar — Talep Sistemi bilgi bankasındaki tüm makaleleri kuyruğa alır ve AI servisine gönderir.

İndeksleme toplu şekilde çalışır (15 dakikada birkaç yüz makale), bu yüzden büyük veri tabanlarında işlem zaman alabilir. Durumu http://<ai-host>:5050/ üzerinden izleyebilirsiniz.

Indexed data değeri arttıkça sistem çalışıyor demektir. Benzer makale önerileri ve arama, indekslenen her makale için hemen aktif olur.

Yeni eklenen veya düzenlenen makaleler otomatik olarak yeniden indekslenir. Tam yeniden indeksleme için AI ayarlarını tekrar kaydedin.

Güvenlik & ağ

Servis yerleşik şifreleme içermez ve kök sayfa (/) API anahtarı olmadan erişilebilir (yalnızca özet sağlık bilgisi içerir).

  • Güvenli ağda tutun. 5050 portunu internete açmayın, yalnızca Talep Sistemi erişebilsin.
  • x-API-key HTTP üzerinden düz metin olarak iletilir. Farklı makineler arasında güvenli olmayan ağ kullanılıyorsa reverse proxy ile HTTPS önerilir.

Yedekleme

Tüm indeks verisi qdrant_storage Docker volume içinde tutulur. Yedeklemek için:

docker compose down

ve volume’leri arşivleyin. Ancak gerekmez — indeks her zaman yeniden oluşturulabilir.

Güncelleme

  1. Yeni isimsofrware_ai.zip paketini indirin.
  2. Yeni bir klasöre çıkarın.
  3. .env dosyanızı kopyalayın.
  4. Eski servisi kapatın: docker compose down.
  5. Yeni klasörde çalıştırın: docker compose up -d --build.

Mevcut Qdrant ve cache volume’leri kullanılır, veri korunur.

Sorun giderme

isimsoftware-ai restart oluyor. Logları kontrol edin: docker compose logs isimsoftware-ai. En yaygın sebep: .env içinde AI_API_KEY eksik.

5050 portu dolu. docker-compose.yml içinde portu değiştirin (ör. 8080:5000) ve Talep Sistemi URL’sini güncelleyin.

Benzer makale gelmiyor. Servis URL’sini tarayıcıdan açın. Qdrant hatası varsa container yeniden başlatın. İndeksleme sürüyorsa bekleyin.

Yüksek bellek kullanımı. GUNICORN_WORKERS değerini 1 yapın.

pip install hatası. İnternet bağlantısı veya PyPI erişimi yok.

Kaldırma

docker compose down -v

Ardından Talep Sistemi içinde AI Özellikler kısmından servis URL’sini kaldırın.

Önceki
Kendi Barındırılan Kurulum
İleri
API Başvurusu