2026'da Qdrant'ı Self-Host Etme: Depolama, API Anahtarları ve Yedekler

Qdrant'ı self-host etmek, ilk docker run komutunda değil, ilk redeploy işleminde ilgi çekici hâle gelir. Depolama izinleri başarısız olursa veya istemci yalnızca 6333 yönlendirilmişken 6334'ü kullanırsa Docker yine de işlemin tamamen sağlıklı olduğunu bildirebilir. Aşağıdaki deployment gözlemlenebilir davranışlar etrafında düzenlenmiştir: amaçlanan vector size ile bir collection oluşturmak, payload içeren point'ler eklemek, filtrelenmiş bir nearest-neighbor sorgusu çalıştırmak ve bir collection snapshot'ını geri yüklemek.

Qdrant'ın kullanım amacı nettir: embedding'ler ve retrieval sistemleri için vector database. Bu tanım, hangi bileşenlerin public kalması, hangilerinin private tutulması ve bir backup'ın neleri yeniden oluşturması gerektiğini ortaya koyar.

Docker'a dokunmadan önce Qdrant'ı haritalandırın

Production mimarisinin yanlışlıkla Qdrant image'ı tarafından belirlenmesine izin vermeyin. Image, 6333 üzerinde çalışan bir process sağlar; storage, routing ve harici gereksinimler için yine bilinçli lifecycle'lar gerekir. Local runtime gereksinimi, vector dimension'ları, payload'lar ve index'ler için yeterli RAM ve disk alanıdır. Bunları image default'u olarak bırakmak yerine beklenen kapasiteyi, sahipliği ve failure mode'u dokümante edin.

Deployment; amaçlanan vector size ile bir collection oluşturabildiğinde, payload içeren point'ler ekleyebildiğinde, filtrelenmiş bir nearest-neighbor sorgusu çalıştırabildiğinde ve bir collection snapshot'ını geri yükleyebildiğinde daha kapsamlı testlere hazırdır. Log'larda transaction'ı takip edin; vector dimension'larını, HNSW construction'ı, payload index'lerini, collection replica'larını ve memory-mapped data ile kullanılabilir RAM arasındaki farkı izleyin. Bu gözlemler, mevcut topolojinin doğru component'i izole edip etmediğini gösterir.

HTTPS konusunda yanıltmadan Qdrant'ı yönlendirin

Kullanıcılar callback veya istemci ayarlarını kaydetmeden önce nihai Qdrant hostname'ini seçin. Ardından REST'i yalnızca istemciler gerçekten ihtiyaç duyduğunda public tutun ve gRPC'yi private bırakın. Platform route'u TLS'i bir kez sonlandırmalı ve private port 6333'ü hedeflemelidir.

Acceptance transaction'ı dışarıdan çalıştırın. İstemci Qdrant'a hiç ulaşamıyorsa DNS ve certificate kontrolleri için SSL doğrulama kontrol listesini kullanın. İstek Qdrant'a ulaşıyor ancak storage izinleri başarısız oluyor veya istemci yalnızca 6333 yönlendirilmişken 6334'ü kullanıyorsa proxy redirect'lerini değiştirmeyi bırakın ve bunun yerine uygulamaya özgü sınırı inceleyin.

Local komutu incelenebilir bir service'e dönüştürün

Her önemli seçeneği açıkça gösteren bir komut kullanın. Bu baseline, Qdrant'ı host loopback'e bind eder, bilinen data mount'larını ekler ve ilk gerekli ayarı sağlar. Dışarı açmadan önce local gereksinimi doğrulayın: vector dimension'ları, payload'lar ve index'ler için yeterli RAM ve disk alanı.

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 127.0.0.1:6333:6333 \
  -v qdrant-data:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY=replace-with-a-long-random-value \
  qdrant/qdrant:latest

Değişken tag'leri test edilmiş bir version veya digest ile değiştirin. Başlangıçtan sonra docker logs --tail 200 qdrant komutunu inceleyin ve process'in 6333 üzerinde dinlediğini doğrulayın. Ardından Qdrant acceptance action'ını çalıştırın; root-page yanıtı, tüm senaryonun başarıyla tamamlandığını kanıtlayamaz: amaçlanan vector size ile bir collection oluşturmak, payload içeren point'ler eklemek, filtrelenmiş bir nearest-neighbor sorgusu çalıştırmak ve bir collection snapshot'ını geri yüklemek gerekir.

Tahmin yürütmeden Qdrant'ı upgrade edin

Capacity test'leri, / adresine tekrarlanan bir istek göndermek yerine vector dimension'larını, HNSW construction'ı, payload index'lerini, collection replica'larını ve memory-mapped data ile kullanılabilir RAM arasındaki farkı test etmelidir. “Amaçlanan vector size ile bir collection oluştur, payload içeren point'ler ekle, filtrelenmiş bir nearest-neighbor sorgusu çalıştır ve bir collection snapshot'ını geri yükle” senaryosunu gerçekçi concurrency ile çalıştırın; latency, error rate ve storage büyümesini kaydedin.

Upgrade planlaması şu riski hesaba katmalıdır: collection snapshot'ları, storage format uyumluluğu ve client library davranışı, server version değişikliğinden önce test edilmelidir. Yeni release'i temsili input ile test edin, ardından acceptance transaction'ı tekrarlayın ve sonucu karşılaştırın. Storage izinleri başarısız oluyorsa veya istemci yalnızca 6333 yönlendirilmişken 6334'ü kullanıyorsa başarısız transaction'ı kaydedin ve ingress'in sorumlu olduğunu varsaymak yerine ilk etkilenen sınırı inceleyin.

Qdrant smoke test'ini release kontrolüne dönüştürün

Qdrant için bir release candidate, sabit bir senaryoyu tamamlayarak trafik almaya hak kazanır: amaçlanan vector size ile bir collection oluşturmak, payload içeren point'ler eklemek, filtrelenmiş bir nearest-neighbor sorgusu çalıştırmak ve bir collection snapshot'ını geri yüklemek. Bu senaryo için image digest'ini, secret içermeyen etkin configuration'ı, public origin'i ve timestamp'leri kaydedin. Test verileri disposable olmalı, ancak kullanıcılarla aynı path'i test edecek kadar gerçekçi olmalıdır.

Runtime'ı değiştirdikten sonra testi çalıştırın; ardından service'i Qdrant snapshot'larından ve persistent storage directory'den yeniden oluşturun. Recovery, bir snapshot aynı point count'u, vector configuration'ı ve temsili query sonuçlarını koruyarak collection'ı yeniden oluşturduğunda başarılıdır. Vector dimension'ları, HNSW construction'ı, payload index'lerini, collection replica'larını ve memory-mapped data ile kullanılabilir RAM arasındaki farkı önceki release ile karşılaştırın; anlamlı sapmaları promotion'dan önce araştırın.

Son olarak şu kontrollü failure durumunu test edin: storage izinlerinin başarısız olması veya yalnızca 6333 yönlendirilmişken istemcinin 6334'ü kullanması gibi bu sınırla ilişkili resource ya da format limitine yakın, zararsız bir input gönderin. Qdrant'ın failure'ı açıkladığını, mevcut state'e zarar vermediğini ve geçerli koşul geri döndüğünde çalışmaya devam ettiğini doğrulayın. Redact edilmiş bir log alıntısını ve recovery süresini kaydedin. Bu kontroller birlikte yalnızca process uptime'ını değil, behavior, durability ve operability'yi de kapsar.

Qdrant'ın replacement sonrasında ayakta kaldığını kanıtlayın

Qdrant için redeploy güvenliği, Qdrant snapshot'ları ve persistent storage directory ile başlar. Bootstrap işleminden önce /qdrant/storage dizinini mount edin, zararsız örnek veriler yazın ve bu path'in gerçekten persistent olduğunu kanıtlamak için container'ı değiştirin. Zararsız örnek veriler mevcutken container'ı değiştirerek path'i test edin; bu işlem, mount'ların bir üst veya bir alt dizine işaret ettiğini ortaya çıkarır.

Ardından disaster recovery'yi boş bir host üzerinde test edin. Gerektiğinde application-consistent database export kullanın ve bir snapshot'ın aynı point count, vector configuration ve temsili query sonuçlarıyla collection'ı yeniden oluşturduğunu doğrulayın. Restore edilmiş database backup rehberi, yalnızca bir archive file oluşturulduğunu kontrol etmekten daha güçlü bir hedef sunar.

Credentials, roller ve dışa açık yüzeyler

Qdrant için değerli surface her zaman landing page değildir. En büyük hata, authentication olmadan çalışan bir API'yi internete açmaktır. Buna bilinçli şekilde karşı koyun: ingestion service'lerine kapsamı sınırlandırılmış API erişimi verin ve tam administrative API'yi private bir route üzerinde tutun.

QDRANT__SERVICE__API_KEY değerini Qdrant'taki rolüne uygun şekilde ele alın: hassas değerleri Git dışında tutun, rotation etkilerini dokümante edin ve production'da public bir örneği asla kullanmayın. Image destekliyorsa unprivileged container user kullanın ve ilgisiz hiçbir credential'ı mount etmeyin. Güvenilmeyen işlerin vector dimension'larını, HNSW construction'ı, payload index'lerini, collection replica'larını ve memory-mapped data ile kullanılabilir RAM arasındaki farkı tüketebileceği noktalarda ingress katmanında rate veya size limit'leri uygulayın.

Tekrarlanabilir infrastructure işlerini Dockup'a taşıyın

Dockup, değiştirilebilir platform parçalarını üstlenebilir: trafiği 6333 portuna yönlendirebilir, domain ve certificate sağlayabilir, secret'ları inject edebilir, persistent storage'ı bağlayabilir ve Qdrant'ı managed veya private olarak bağlı service'lere bağlayabilir. Bunu Dockup infrastructure'ı üzerinde veya bağladığınız bir server'da gerçekleştirebilir.

Qdrant acceptance çalışmaları açıkça tanımlı kalır. One-click deployment sonrasında REST'i yalnızca istemciler gerçekten ihtiyaç duyduğunda public tutun ve gRPC'yi private bırakın; local gereksinimi — vector dimension'ları, payload'lar ve index'ler için yeterli RAM ve disk alanını — doğrulayın ve şu senaryoyu çalıştırın: amaçlanan vector size ile bir collection oluşturmak, payload içeren point'ler eklemek, filtrelenmiş bir nearest-neighbor sorgusu çalıştırmak ve bir collection snapshot'ını geri yüklemek. Bu ayrım bilinçlidir: Dockup, uygulama rollerinin, provider credential'larının veya restore politikasının kendiliğinden seçildiği izlenimini vermeden tekrarlanan infrastructure kurulumunu ortadan kaldırır.

Sık sorulan sorular

Production deployment için Qdrant'ın neye ihtiyacı vardır?

Qdrant container'ını tek bir HTTPS origin üzerinden 6333 portuna yönlendirin. Local runtime gereksinimi, vector dimension'ları, payload'lar ve index'ler için yeterli RAM ve disk alanıdır. Amaçlanan vector size ile bir collection oluşturabildiğiniz, payload içeren point'ler ekleyebildiğiniz, filtrelenmiş bir nearest-neighbor sorgusu çalıştırabildiğiniz ve bir collection snapshot'ını geri yükleyebildiğinizden emin olmadan Qdrant'ı hazır kabul etmeyin.

Qdrant verilerinin hangileri backup'a dahil edilmelidir?

/qdrant/storage dizinini persistent hâle getirin ve Qdrant snapshot'larını ve persistent storage directory'yi aynı recovery manifest'ine dahil edin. Temiz bir Qdrant restore işlemi, yalnızca bir snapshot aynı point count, vector configuration ve temsili query sonuçlarıyla collection'ı yeniden oluşturduğunda başarılı sayılır.

Qdrant'ın reverse proxy arkasında HTTPS kullanması gerekir mi?

Public Qdrant origin için HTTPS kullanın ve 6333 portunu internal route üzerinde tutun. Qdrant ayarını doğru uygulayın: REST'i yalnızca istemciler gerçekten ihtiyaç duyduğunda public tutun ve gRPC'yi private bırakın. Qdrant için HTTPS, credentials veya user content'in aktarım sırasında korunmasını ve origin'e duyarlı istemci davranışının tutarlı kalmasını sağlar.

Bir Qdrant upgrade'i nasıl test edilmelidir?

Mevcut Qdrant state'ini izole bir deployment'a restore edin, candidate version'ı uygulayın ve acceptance transaction'ı tekrarlayın. Özellikle dikkatli olun; collection snapshot'ları, storage format uyumluluğu ve client library davranışı, server version değişikliğinden önce test edilmelidir. Data migration ve rollback sınırı anlaşılana kadar önceki Qdrant image'ını koruyun.