Onyx'i Docker ile Kurmaya Dair Eksiksiz Kılavuz

Onyx, dil modellerini belgeler, uygulamalar ve bilgi tabanlarıyla birleştirmek üzere tasarlanmış açık kaynaklı bir yapay zeka platformudur. Ekip sohbeti, kurumsal arama motoru, RAG sistemi ve ajanlar ve araçlarla donatılmış bir çalışma alanı olarak kullanılabilir.

Platform, yönetilen bir hizmet olarak sözleşme kapsamında alınabilir, ancak kendi altyapınıza da kurulabilir. İkinci durumda, Docker Compose, en erişilebilir yöntemlerden biridir.Çünkü bu sayede arayüzü, API'yi, veritabanlarını, indeksleme işlemlerini ve diğer tüm bileşenleri, bağımlılıklarının tamamını manuel olarak kurmanıza gerek kalmadan çalıştırabilirsiniz.

Bu kılavuzda, Onyx'i Docker ile nasıl kuracağımızı, Lite ve Standard modları arasındaki farkları, konteynerleri nasıl yöneteceğimizi ve örneği internette yayınlamadan önce hangi adımları atmamız gerektiğini göreceğiz.

Onyx nedir ve hangi hizmetlere bağlanabilir?

Onyx, kullanıcıların yapay zeka modellerini kullanarak belgelerden ve uygulamalardan bilgi sorgulamasına olanak tanıyan kurumsal bir sohbet ve arama platformudur. Ticari sağlayıcılarla ve kendi altyapısında barındırılan modellerle bağlantı kurabilir.

Başlıca işlevleri şunlardır:

• Farklı sağlayıcılardan modellerle sohbet edin.
• Eylemleri gerçekleştirebilen aracılar ve araçlar.
• Bilgi kaynaklarını senkronize etmek için kullanılan bağlantı elemanları.
• Anahtar kelimeler ve vektörler kullanan hibrit arama.
• RAG'ın belgelere dayalı yanıtları.
• Derinlemesine araştırma ve internet araması.
• Eylemler ve MCP aracılığıyla araçlarla entegrasyon.
• Dosya yükleme ve projelere göre düzenleme.
• Kullanıcı yönetimi ve kimlik doğrulama sistemleri.

Onyx, kullanacağınız üretken modeli mutlaka içermez. Kurulumdan sonra, OpenAI, Anthropic, Gemini, Ollama, LiteLLM veya vLLM gibi bir sağlayıcıyı yapılandırmanız gerekecektir.

Onyx Lite mı yoksa Standard mı: Hangi sürümü yüklemeliyim?

Mevcut yükleyici, iki mod arasında seçim yapmanıza olanak tanır. Bu karar önemlidir çünkü her biri farklı bir mimari ve işlev kümesi sunar.

Özellik	Onyx Lite	Onyx Standard
Modellerle sohbet edin	Evet	Evet
Aracılar ve araçlar	Evet	Evet
Dosya Yükleme	Evet	Evet
Projeler	Evet	Evet
Harici kaynaklarla bağlantı kuranlar	HAYIR	Evet
RAG Dizini Oluşturma ve Arama	HAYIR	Evet
OpenSearch	HAYIR	Evet
Redis	HAYIR	Evet
İndeksleme için model sunucuları	HAYIR	Evet
Arka plan süreçleri	API'ye entegre edilmiştir.	Bağımsız konteynerler
Önerilen kullanım	Test etme, sohbet ve küçük ekipler	RAG, bağlantı elemanları ve kuruluşlar

Onyx Lite Platformu test etmek, sohbet özelliklerini kullanmak veya sınırlı kaynaklara sahip bir sunucuda çalışmak için en iyi seçenektir. Dosyaları, önbelleği ve oturumları PostgreSQL'de depolar ve tam arama altyapısını çalıştırmaz.

Onyx Standard Bu, bağlantı noktalarını kullanmak, dokümantasyonu senkronize etmek ve kurumsal bir arama sistemi oluşturmak için tasarlanmıştır. OpenSearch, Redis, arka plan işlemleri, nesne depolama ve indeksleme sırasında kullanılan sunucuları eklediği için önemli ölçüde daha fazla bellek ve depolama alanı gerektirir.

Onyx'i Docker ile kurmak için gerekenler

Onyx, Docker kullanılarak Linux, macOS veya Windows işletim sistemlerinde çalıştırılabilir. Üretim sunucusu için genellikle güncel bir Linux dağıtımı kullanmak tercih edilir.

Resmi gereksinimler seçilen moda bağlıdır:

Mod	minimum CPU	minimum RAM	minimum disk alanı	Tercih edilen yapılandırma
Onyx Lite	2 vCPU	2 GB	10 GB	4 sanal işlemci, 4 GB RAM ve 50 GB
Onyx Standard	4 vCPU	10 GB	32 GB artı dizinlenmiş veriler için ayrılan alan	8 veya daha fazla sanal işlemci ve 16 GB veya daha fazla RAM

Standart modda, dokümantasyonda dizinlenen belgelerin boyutunu tahmin etmeniz ve bolca bir pay eklemeniz önerilir. Gerçek kaynak tüketimi, içerik miktarına, yerleştirmelere, eşzamanlılığa ve OpenSearch yapılandırmasına bağlıdır.

Başlamadan önce şunlara ihtiyacınız olacak:

• Sunucuyu yönetme yetkisine sahip bir hesap.
• Docker Engine ve Docker Compose eklentisi.
• Görselleri ve modelleri indirmek için internet bağlantısı gereklidir.
• Manuel kurulum yapacaksanız Git kullanın.
• Python ve uv Onyx CLI'yı doğrudan yüklemek istiyorsanız.
• Uygulamayı yayınlayacaksanız, bir alan adı ve DNS ayarlarına erişim gereklidir.

Docker ve Compose'u şu komutlarla kontrol edin:

docker --version
docker compose version

Linux'ta ayrıca kullanıcınızın Docker'ı çalıştırabildiğinden veya kullanabildiğinden emin olmanız gerekir. sudo gerektiğinde.

Önerilen yükleyici ile Onyx nasıl kurulur?

Şu anda önerilen yöntem, birlikte verilen kılavuzlu kurulum programını kullanmaktır. Onyx CLIBu işlem bilgisayarın kaynaklarını kontrol eder, Lite ve Standard seçenekleri arasında seçim yapmanıza olanak tanır, imajları indirir, konteynerleri başlatır ve tüm hizmetler kullanılabilir hale gelene kadar bekler.

Eğer zaten yüklüyse uv, Çalıştırmak:

uv tool install onyx-cli
onyx-cli deploy install

Asistan size şu soruları soracak:

• Hangi modu yüklemek istersiniz: Lite mı yoksa Standart mı?
• Onyx'in hangi sürümünü kullanmak istiyorsunuz?
• Ortam hangi yapılandırmayı kullanmalı?

Yeni bir kurulumda, dağıtım dosyaları şu klasörde saklanır:

~/.config/onyx

Bu dizin, yığın yönetiminde kullanılan yapılandırma dosyalarını içerir. Bunu başka bir dizinle karıştırmayın. onyx_dataBu, yükleyicinin önceki sürümleri tarafından oluşturulmuş bir klasördür. Onyx CLI bu eski kurulumları algılayıp benimseyebilir, ancak artık yeni bir kurulum için varsayılan yol değildir.

Onyx'i resmi script ile nasıl kurarsınız?

Resmi sayfada yayınlanan komutu da kullanabilirsiniz:

curl -fsSL https://onyx.app/install_onyx.sh | bash

Bu betik, Onyx CLI yükleyicisinin bir sarmalayıcısıdır. Bu nedenle, aynı türde yönlendirilmiş dağıtım üretir ve artık bağımsız bir sistem olarak tanımlanmamalıdır.

İnternetten indirdiğiniz herhangi bir komut dosyasını doğrudan çalıştırmadan önce kaydedebilir ve içeriğini inceleyebilirsiniz:

curl -fsSLo install_onyx.sh https://onyx.app/install_onyx.sh
less install_onyx.sh
bash install_onyx.sh

Kurulum programı ortamı kontrol eder, gerektiğinde uyumlu Linux sistemlerine Docker'ı kurar ve konteynerler sağlıklı hale gelene kadar bekler.

İşlem tamamlandığında, erişebileceğiniz adresi gösterecektir. Alan adı olmayan yerel bir kurulumda, bu adres genellikle şöyledir:

http://localhost:3000

Onyx ağdaki başka bir sunucuda çalışıyorsa, onun yerini alır. localhost İlgili IP adresi üzerinden. Kimlik doğrulama ve HTTPS yapılandırması yapılmadan portu herkese açık hale getirmeyin.

Docker Compose kullanarak Onyx'i manuel olarak nasıl kurarsınız?

Manuel kurulum, Compose dosyalarını doğrudan incelemek veya Onyx'i kendi dağıtım hattınıza entegre etmek istiyorsanız kullanışlıdır. Ancak, güncellemeleri ve yapılandırma değişikliklerini kendiniz yönetmeniz gerekir.

Öncelikle resmi depoyu klonlayın:

git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose

Yayınlanan imajlarla standart dağıtımı başlatmak için:

docker compose up -d

Görüntüleri kaynak koddan derlemek istiyorsanız:

docker compose up -d --build --force-recreate

Koddan derleme daha fazla zaman ve kaynak tüketir. Standart bir kurulum için, daha önce yayınlanmış olan resmi imajları kullanmak tercih edilir.

Konteynerler başlatıldıktan sonra, Onyx'in hazırlık sürecini tamamlaması gerekir. Durumunu şu komutla kontrol edin:

docker compose ps

Kayıtları takip etmek için:

docker compose logs -f

Tüm hizmetler hazır olduğunda, açın:

http://localhost:3000

Onyx Lite'ı manuel olarak nasıl dağıtabilirsiniz?

Onyx Lite, gereksiz hizmetleri devre dışı bırakan ek bir Compose dosyası aracılığıyla etkinleştirilir:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.onyx-lite.yml \
  up -d

Bu mod yalnızca gerekli hizmetleri başlatır:

• api_serverAynı zamanda arka plan çalışmalarını da yönetir.
• web_serverArayüze karşılık gelen.
• relational_dbPostgreSQL tabanlı.
• nginxBu, ters proxy görevi görür.

Lite sürümü, senkronize edilmiş kaynaklarda bağlantı noktalarını, OpenSearch'ü veya RAG aramasını içermez. Dosyaları yükleyebilir ve projeleri kullanabilirsiniz, ancak harici uygulamalardan gelen belgeleri indekslemeniz gerektiğinde Standart dağıtımın yerini almaz.

Onyx Standard hangi hizmetleri kullanıyor?

Sürümler arasında tam mimari değişebilir, bu nedenle eski bir Compose dosyasını kopyalamak veya PostgreSQL, Redis veya diğer bileşenlerin imajlarını manuel olarak düzeltmek önerilmez.

Genel olarak, Onyx Standard şunları içerir:

• Ana mantığı içeren bir API sunucusu.
• Bir web arayüzü.
• PostgreSQL ilişkisel bir veritabanı olarak.
• Bağlayıcılar ve indeksleme için arka plan işlemleri.
• Önbellekleme ve oturumlar için Redis.
• Vektör ve anahtar kelime araması için OpenSearch.
• İndeksleme ve veri alma sırasında kullanılan model sunucular.
• MinIO veya uyumlu bir arka uç kullanarak nesne depolama.
• Nginx'i ters proxy olarak kullanmak.

Her zaman yüklediğiniz Onyx sürümüyle birlikte gelen dosyaları kullanın. Veritabanı sürümlerini ayrı ayrı değiştirmek uyumsuzluklara veya başarısız geçişlere neden olabilir.

İlk kurulum nasıl tamamlanır?

Yeni bir kurulumda ilk kayıt olan kişi yönetici olur. Bu nedenle, başkalarının sunucuya erişmesine izin vermeden önce bu adımı tamamlamanız gerekir.

Giriş yaptıktan sonra:

1. Yönetici hesabı için güçlü bir parola oluşturun.
2. Yönetim paneline girin.
3. Bir dil modeli sağlayıcısı yapılandırın.
4. İlgili kimlik bilgilerini ekleyin.
5. Varsayılan bir model seçin.
6. Bir deneme görüşmesi yapın.
7. Eğer Standard sürümünü kullanıyorsanız, bir bağlayıcı oluşturun ve indekslemeyi kontrol edin.

Onyx, Ollama, vLLM veya LiteLLM gibi ticari servis sağlayıcılarla ve kendi sunucularıyla çalışabilir. Onyx'in kendi sunucularını kullanması, modelin otomatik olarak yerel olduğu anlamına gelmez: OpenAI, Anthropic veya Gemini'yi yapılandırırsanız, gerekli istekler o sağlayıcıya gönderilecektir.

Onyx'i CLI kullanarak nasıl yönetirsiniz?

Mevcut yükleyicinin avantajlarından biri, tüm dağıtım yaşam döngüsünü yönetmek için özel komutlar sağlamasıdır:

onyx-cli deploy status
onyx-cli deploy logs
onyx-cli deploy stop
onyx-cli deploy upgrade

Başlıca işlevleri şunlardır:

• statusHizmetlerin durumunu kontrol edin.
• logsDağıtım günlüklerini görüntüler.
• stop: Kapsayıcıları kaldırmadan durdurur.
• upgradeYönetilen kurulumu günceller.
• uninstallDağıtımı ortadan kaldırır.

Koşma uninstall Geçici bir hatayı gidermek için. Herhangi bir silme işleminden önce, hangi verilerin ve birimlerin saklanacağını kontrol edin ve ayrı bir yedekleme yapın.

Manuel kurulum nasıl güncellenir?

Docker Compose dosyalarını doğrudan yönetiyorsanız, güncelleme yapmadan önce yeni sürümün sürüm notlarını inceleyin. Ardından, değişiklikleri ve ilgili imajları depodan indirin.

Dağıtım dizininden başlayarak, olağan süreç şunları içerir:

git pull
docker compose pull
docker compose up -d

Yeni bir sürümü test etmeden otomatik olarak üretim ortamına dağıtmayın. Bazı güncellemeler veritabanı geçişlerini, ortam değişkenlerinde değişiklikleri veya hizmetlerde değişiklikleri içerebilir.

Onyx CLI kullanılarak oluşturulan bir kurulum için tercihen şunu kullanın:

onyx-cli deploy upgrade

Kalıcılık ve yedeklemeler

Docker Compose, kapsayıcılar yeniden oluşturulduktan sonra veritabanını, indeksleri, dosyaları ve diğer verileri korumak için birimler kullanır. Ancak, Kalıcı depolama birimi, yedekleme ile aynı şey değildir..

Dağıtımı güncellemeden veya değiştirmeden önce:

• Kaydedilen ayarların bir kopyasını oluşturun. ~/.config/onyx.
• Yüklediğiniz PostgreSQL sürümüyle uyumlu bir araç kullanarak PostgreSQL'i yedekleyin.
• Dosyalardan veya nesne depolama alanından arka uç verilerini korur.
• Servisin kurtarılması için gerekli ortam değişkenlerini ve gizli bilgileri saklayın.
• Yedeklemelerin geri yüklenebildiğini periyodik olarak kontrol edin.
• Ana sunucunun dışında en az bir kopya saklayın.

Bağlantılı kaynaklardan bazıları yeniden indekslenebilir, ancak veritabanı kullanıcılar, ayarlar, konuşmalar ve yedekleme yapılmadan kurtarılamayacak diğer verileri içerir.

Alan adı ve HTTPS nasıl kurulur?

Onyx'e internetten erişilebilecekse, DNS kaydı sunucunun genel IP adresine işaret eden bir alan adı yapılandırın. Ardından şu değişkeni ayarlayın:

WEB_DOMAIN=onyx.ejemplo.com

Bu depoda, Docker dağıtımlarında Let's Encrypt sertifikası edinmek için kullanılan bir komut dosyası bulunmaktadır:

./init-letsencrypt.sh

Çalıştırmadan önce, ortam dosyalarını kontrol edin ve etki alanının sunucuya doğru şekilde çözümlendiğini doğrulayın. Ayrıca 80 ve 443 numaralı bağlantı noktalarının da kullanılabilir olması gerekir.

Üretim ortamını doğrudan şu gibi bir adres kullanarak yayınlamayın: http://IP:3000HTTPS olmadan, kimlik bilgileri ve veriler iletim sırasında açığa çıkabilir.

Onyx'i yayınlamadan önce nasıl koruyabilirsiniz?

E-posta ve parola ile kimlik doğrulama varsayılan olarak etkinleştirilmiştir. İlk kayıt olan hesap yönetici ayrıcalıklarına sahip olur.

Bir ekip tarafından kullanılan bir kurulum için:

• Yönetici hesabını hemen kaydedin.
• Benzersiz ve güçlü bir parola kullanın.
• Güvenlik duvarını kullanarak erişimi kısıtlayın.
• Harici bağlantılara izin vermeden önce HTTPS'yi etkinleştirin.
• Gerektiğinde OAuth, OIDC veya SAML'yi yapılandırın.
• İzin verilen e-posta alan adlarını sınırlayın.
• İhtiyaç kalmadığında açık olan günlük kaydını devre dışı bırakın.
• Model ve konektör tedarikçilerinin anahtarlarını koruyun.
• Onyx, Docker ve işletim sistemini güncelleyin.
• MCP aracıları, eylemleri ve araçları için izinleri gözden geçirin.

Mevcut sürümler, yönetim panelinden bazı güvenlik ayarlarını yapılandırmanıza olanak tanır. Kurumsal ortamlarda, RBAC, izin senkronizasyonu veya ek gizli şifreleme gibi bazı gelişmiş özellikler için Kurumsal sürüm gerekebilir.

Depolama tüketimini nasıl izleyebilirim?

Standart modda, OpenSearch arama için kullanılan indeksleri depolar. Disk kullanımı kritik bir eşiğe (varsayılan olarak %95) ulaştığında, OpenSearch indeksleri salt okunur olarak işaretleyebilir ve yazmayı durdurabilir.

Boş alan olup olmadığını düzenli olarak kontrol edin:

df -h
docker system df

Ayrıca, disk birimlerinin boyutunu kontrol edebilir ve artık kullanılmayan Docker imajlarını silebilirsiniz:

docker image prune

Bu komut kalan görüntüleri kaldırır, ancak kaldırılacak öğeleri her zaman gözden geçirmelisiniz. Etkilenen kapsayıcıları, görüntüleri ve birimleri önceden kontrol etmeden üretim sunucusunda agresif Docker temizleme komutları kullanmayın.

Onyx, Plesk üzerinden kurulabilir mi?

Plesk, tek tek konteynerler oluşturmanıza ve yönetmenize olanak tanır, ancak Onyx çeşitli servislerden, ağlardan, bağımlılıklardan ve birimlerden oluşan bir yığındır. Plesk arayüzünden konteyner konteyner yeniden oluşturmak hataya açıktır ve güncellemeleri zorlaştırır.

Sunucunuz Plesk kullanıyorsa, aşağıdaki adımları izlemeniz tercih edilir:

1. Sunucuya SSH kullanarak erişin.
2. Docker ve Docker Compose'un kullanılabilir olduğundan emin olun.
3. Onyx'i Onyx CLI veya resmi Compose dosyalarını kullanarak yükleyin.
4. Plesk'i yalnızca alan adı, DNS veya proxy için kullanıyorsanız, her iki sistemi de doğru şekilde entegre etmeyi biliyorsanız kullanın.

Bu kombinasyonu kullanmadan önce, sunucu sağlayıcısının Docker yönetimini desteklediğinden ve portların, ağların ve kaynakların Plesk tarafından yönetilen diğer hizmetlerle çakışmadığından emin olun.

Onyx'i Docker ile kurarken yapılan yaygın hatalar

Konteynerler henüz mevcut değil.

Durumu ve kayıtları kontrol edin:

onyx-cli deploy status
onyx-cli deploy logs

Manuel kurulum için şunu kullanın:

docker compose ps
docker compose logs --tail=200

En yaygın nedenler yetersiz bellek, alan eksikliği, Docker izinleri veya başlatılması tamamlanmamış bağımlı bir hizmettir.

3000 numaralı liman zaten dolu.

Hangi işlemin portu kullandığını kontrol edin veya Compose yapılandırmasındaki eşlemeyi değiştirin. Proxy'yi ve ona bağlı değişkenleri kontrol etmeden bir konteynerin portunu değiştirmeyin.

Onyx Lite bağlantı noktalarını göstermiyor.

Bu bir hata değil. Lite sürümü, kaynak kullanımını azaltmak için bağlantı noktalarını, OpenSearch'ü ve RAG aramasını devre dışı bırakır. Harici kaynakları senkronize etmek istiyorsanız Standart sürümü kullanın.

OpenSearch yazma işlemlerini kabul etmeyi durduruyor.

Kullanılabilir alanı kontrol edin. Disk kritik eşiğe ulaştıysa, öncelikle depolama alanını boşaltın veya genişletin. Ardından, salt okunur kilidi kaldırmadan önce OpenSearch belgelerini inceleyin.

Arayüz açılıyor ancak sohbet yanıt vermiyor.

Yönetici panelinden geçerli bir sağlayıcı ve model yapılandırdığınızdan emin olun. Ayrıca bakiyenizi, API anahtarınızı ve sağlayıcıyla bağlantınızı kontrol edin.

Sunucunun belleği tükendi.

Doğru modu seçtiğinizden emin olun. Küçük bir sunucu için Lite modunu kullanın. Standart mod en az 10 GB RAM gerektirir ve indekslenen belge sayısı arttıkça çok daha fazla RAM'e ihtiyaç duyabilir.

Bir güncelleme, hizmetlerin uyumsuz hale gelmesine neden oldu.

Sürüm notlarını, geçişleri ve ortam dosyalarını inceleyin. Kılavuzlu yükleyiciyi kullandıysanız, yükseltmeyi manuel komutlarla karıştırmak yerine Onyx CLI'yı kullanarak yönetin.

Onyx'i Docker ile kurmak, bir kuruluşun belgelerine ve uygulamalarına bağlı bir yapay zeka ortamı dağıtmanıza olanak tanır. Sohbet ve ajan testleri için Onyx Lite, basit ve düşük güç tüketimli bir mimari sunar. Harici kaynakları indekslemek ve RAG araması kullanmak için Standart dağıtımı seçmeli ve yeterli kaynak ayırmalısınız.

Kurulumu sürdürmenin en kolay yolu, kurulumu, günlükleri, durumu ve güncellemeleri yöneten Onyx CLI'yı kullanmaktır. Üretim ortamında ayrıca kimlik doğrulama, HTTPS, yedeklemeler ve depolama izleme ayarlarını da yapılandırmanız gerekir.