استضافة Qdrant على خادم VPS

لماذا تستضيف ‎Qdrant‎ ذاتيًا على خادم ‎VPS‎

المتطلبات والموارد الموصى بها لخادم ‎VPS‎

• ‎RAM‎: كحدٍّ أدنى 1 غيغابايت للاختبار، و2 غيغابايت لبضع مئات الآلاف من المتجهات، و4–8 غيغابايت فوق المليون متجه ذي أبعاد عالية (فهرس ‎HNSW‎ يقيم في الذاكرة).
• التخزين: من 20 إلى 50 غيغابايت من قرص ‎SSD NVMe‎ لاستمرارية المجموعات واللقطات.
• ‎CPU‎: معالج افتراضي واحد إلى اثنين (‎vCPU‎) يكفيان لحركة مرور معتدلة؛ أضِف أنوية إن كنت تُفهرس باستمرار.
• ‎Docker‎ و‎Docker Compose‎ مثبَّتان على الخادم.
• المنفذ ‎6333‎ (‎REST‎) والمنفذ ‎6334‎ (‎gRPC‎) في متناول تطبيقك؛ و80/443 للوكيل العكسي العام.
• سجل ‎DNS A‎ (مثل ‎vectors.mydomain.com‎) إن كنت ستعرض واجهة ‎API‎ عبر ‎HTTPS‎.

تثبيت ‎Qdrant‎ بـ‎Docker Compose‎

1. 01

   إنشاء المجلد وملف ‎compose.yml‎

   على الخادم، أنشئ مجلدًا مخصصًا: ‎mkdir -p /opt/qdrant && cd /opt/qdrant‎. أنشئ ملف ‎compose.yml‎ التالي:

   services:
     qdrant:
       image: qdrant/qdrant:latest
       restart: unless-stopped
       ports:
         - "127.0.0.1:6333:6333"
         - "127.0.0.1:6334:6334"
       volumes:
         - ./qdrant_storage:/qdrant/storage
       environment:
         - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}

   ربط المنافذ بـ‎127.0.0.1‎ يمنع أي تعرّض مباشر على الإنترنت؛ ولا يصل إليها سوى الوكيل العكسي.

2. 02

   توليد مفتاح ‎API‎ وتشغيل الحاوية

   أنشئ ملف ‎.env‎ بمفتاحك:

   echo "QDRANT_API_KEY=$(openssl rand -hex 32)" > .env

   شغّل ‎Qdrant‎:

   docker compose up -d

3. 03

   التحقق من صحة النسخة

   انتظر بضع ثوانٍ ثم تحقق من نقطة نهاية الصحة:

   curl -s http://localhost:6333/healthz
   # المتوقع: {"title":"qdrant - vector search engine","version":"..."}

4. 04

   إنشاء أول مجموعة

   أنشئ مجموعة اختبارية بمتجهات من البُعد 384:

   curl -s -X PUT http://localhost:6333/collections/test \
     -H 'Content-Type: application/json' \
     -H "api-key: $(grep QDRANT_API_KEY .env | cut -d= -f2)" \
     -d '{"vectors":{"size":384,"distance":"Cosine"}}'

تأمين الوصول: مفتاح ‎API‎ و‎TLS‎

vectors.mydomain.com {
    reverse_proxy localhost:6333
}

location / {
    proxy_pass http://127.0.0.1:6333;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

اختبار المصادقة والوكيل العكسي

1. 05

   التحقق من رفض الوصول بلا مفتاح

   curl -s https://vectors.mydomain.com/collections
   # المتوقع: {"status":{"error":"Unauthorized",...}}

2. 06

   استدعاء مُصادَق عليه بمفتاح ‎API‎

   curl -s https://vectors.mydomain.com/collections \
     -H "api-key: YOUR_KEY"
   # المتوقع: {"result":{"collections":[]},"status":"ok",...}

3. 07

   التحقق من شهادة ‎TLS‎

   curl -sv https://vectors.mydomain.com/healthz 2>&1 | grep 'SSL connection\|issuer'
   # المتوقع: سطور تُؤكّد ‎Let's Encrypt‎ و‎TLS 1.3‎

إنشاء مجموعة وإدراج المتجهات بعميل ‎Python v1‎

1. 08

   تثبيت العميل الرسمي

   pip install qdrant-client>=1.7

2. 09

   الاتصال بمفتاح ‎API‎

   from qdrant_client import QdrantClient
   
   client = QdrantClient(
       url="https://vectors.mydomain.com",
       api_key="YOUR_KEY",
   )

3. 10

   إنشاء مجموعة بـ‎VectorParams‎

   from qdrant_client.models import Distance, VectorParams
   
   client.recreate_collection(
       collection_name="documents",
       vectors_config=VectorParams(size=384, distance=Distance.COSINE),
   )

4. 11

   إدراج النقاط مع الحمولة والاستعلام

   from qdrant_client.models import PointStruct
   
   client.upsert(
       collection_name="documents",
       points=[
           PointStruct(
               id=1,
               vector=[0.1, 0.2, ...],
               payload={"title": "دليل Qdrant", "lang": "ar"},
           ),
       ],
   )
   
   results = client.search(
       collection_name="documents",
       query_vector=[0.1, 0.21, ...],
       limit=5,
       with_payload=True,
   )
   for r in results:
       print(r.score, r.payload)

تحسين الأداء: ضبط ‎HNSW‎

معاملات ‎HNSW‎ الرئيسية

مرّر الجدول أفقيًا

تقليل بصمة الذاكرة: التكميم القياسي والثنائي

• التكميم القياسي (‎uint8‎): يضغط كل إحداثية ‎float32‎ (4 بايت) إلى ‎uint8‎ (بايت واحد)، بتخفيض ‎RAM‎ نحو 4 أضعاف. خسارة طفيفة في الدقة تُعوَّض بالإفراط في العيّنات (‎oversampling‎).
• التكميم الثنائي: تخفيض يصل إلى 32× ببينرة كل بُعد. مثالي للنماذج المدرَّبة للتكميم الثنائي.
• المعامل ‎on_disk‎: يخزّن المتجهات الأصلية على القرص ولا يُبقي في ‎RAM‎ سوى الفهرس المُكمَّم. ضروري على خادم ‎VPS‎ محدود الذاكرة.
• ‎Oversampling‎: مع ‎oversampling=2.0‎ عند الاستعلام، تسترجع ‎Qdrant‎ ضعف المرشحين من الفهرس المُكمَّم ثم تعيد ترتيبهم بالمتجهات الأصلية.

النسخ الاحتياطي والاستعادة بلقطات ‎Qdrant‎

1. 12

   إنشاء لقطة لمجموعة

   curl -s -X POST https://vectors.mydomain.com/collections/documents/snapshots \
     -H "api-key: YOUR_KEY"

2. 13

   سرد اللقطات المتاحة

   curl -s https://vectors.mydomain.com/collections/documents/snapshots \
     -H "api-key: YOUR_KEY"

3. 14

   تنزيل اللقطة

   curl -O https://vectors.mydomain.com/collections/documents/snapshots/SNAPSHOT_NAME \
     -H "api-key: YOUR_KEY"

   انسخ ملف ‎.snapshot‎ إلى تخزين خارجي للنسخ الاحتياطي خارج الموقع.

4. 15

   الاستعادة من لقطة

   curl -s -X PUT https://vectors.mydomain.com/collections/documents/snapshots/upload \
     -H "api-key: YOUR_KEY" \
     -H 'Content-Type: multipart/form-data' \
     -F [email protected]

استكشاف الأخطاء الشائعة وإصلاحها

• ‎Connection refused‎ على المنفذ 6333: تحقق من تشغيل الحاوية (‎docker compose ps‎) وعدم حجب المنفذ بواسطة ‎ufw‎.
• خطأ ‎OOM‎ / إيقاف الحاوية قسرًا: قلّل ‎ef_construct‎ أو فعّل التكميم القياسي لتخفيض بصمة ‎RAM‎ للفهرس.
• بطء عند الإقلاع أو التحميل الأول: فهرس ‎HNSW‎ يُحمَّل من القرص عند الوصول الأول؛ استخدم ‎SSD NVMe‎ وأجرِ استعلامًا تجريبيًا بعد التشغيل.
• ‎Unauthorized 403‎: المفتاح في ترويسة ‎api-key‎ لا يطابق ‎QDRANT__SERVICE__API_KEY‎؛ تحقق من غياب المسافات أو أحرف السطر الجديد.
• تراجع الاسترجاع بعد تفعيل التكميم الثنائي: رفع ‎oversampling‎ إلى 3.0 أو 4.0 وتفعيل ‎rescore=True‎.

اقتران ‎Qdrant‎ بـ‎Ollama‎ لمنظومة ‎RAG‎ قائمة بذاتها بالكامل