imam-reza-agent/docs/QDRANT_CONNECTION_TEST.md

راهنمای تست اتصال به Qdrant Vector Database

نمای کلی

این سند راهنمای کاملی برای تست اتصال به پایگاه داده برداری Qdrant در پروژه اسلامی اسکولار است. تست اتصال شامل دو بخش اصلی می‌شود:

1. تست مستقل (test_qdrant_connection.py) - برای استفاده عملی
2. تست‌های pytest (tests/integration/test_qdrant_connection.py) - برای محیط توسعه

ساختار تست‌ها

۱. تست‌های واحد (Unit Tests)

test_qdrant_connection_mock_success

• هدف: تست اتصال موفق با استفاده از Mock
• ورودی‌ها: embedder ساختگی، پارامترهای اتصال
• خروجی مورد انتظار:

  ✅ تست موفق - بدون خطا
  

• چرا مهم: تست منطق اتصال بدون نیاز به Qdrant واقعی

test_qdrant_connection_missing_embedder

• هدف: تست مدیریت خطای embedder خالی
• ورودی: فراخوانی تابع بدون embedder
• خروجی مورد انتظار:

  ValueError: You must provide an 'embedder' instance to get_qdrant_store!
  

• چرا مهم: اطمینان از اعتبارسنجی ورودی‌ها

test_qdrant_connection_missing_env_vars

• هدف: تست رفتار با متغیرهای محیطی خالی
• ورودی: متغیرهای محیطی پاک شده
• خروجی مورد انتظار:

  ✅ تست موفق - اتصال با پارامترهای مستقیم
  

• چرا مهم: تست انعطاف‌پذیری تنظیمات

۲. تست‌های یکپارچه‌سازی (Integration Tests)

test_qdrant_real_connection_success

• هدف: تست اتصال واقعی به Qdrant
• پیش‌نیاز: متغیر محیطی QDRANT_URL تنظیم شده باشد
• خروجی مورد انتظار:

  Loading config from: F:\WORK\CODE\WORK\AGNO-DOVOODI\config\embeddings.yaml
  ✅ Embedder loaded: jina-embeddings-v4
  ✅ Vector store initialized
  📊 Found X collections in Qdrant:
     1. collection_name_1
     2. collection_name_2
     ...
     Total collections: X
  

• چرا مهم: تأیید اتصال واقعی به پایگاه داده

test_qdrant_real_connection_failure

• هدف: تست رفتار با خطای اتصال
• پیش‌نیاز: متغیر محیطی QDRANT_URL تنظیم نشده باشد
• ورودی: URL نامعتبر
• خروجی مورد انتظار:

  httpx.ConnectError: [Errno 11001] getaddrinfo failed
  

• چرا مهم: اطمینان از مدیریت مناسب خطاهای اتصال

test_qdrant_collection_operations

• هدف: تست عملیات مجموعه‌ها
• پیش‌نیاز: متغیر محیطی QDRANT_URL تنظیم شده باشد
• خروجی مورد انتظار:

  📋 Current collections in database (X total):
     1. collection_name_1
     2. collection_name_2
     ...
  ℹ️  Test collection test_operations_jina-embeddings-v4 does not exist (this is normal)
  ✅ Verified collection test_operations_jina-embeddings-v4 is not in database
  

• چرا مهم: تست عملیات مدیریت مجموعه‌ها

نحوه اجرای تست‌ها

اجرای تست مستقل

# از ریشه پروژه
python test_qdrant_connection.py

خروجی نمونه موفق:

🗄️  Qdrant Vector Database Connection Test
Testing connection to Qdrant vector database

🔧 Checking Environment Configuration...
==================================================
✅ QDRANT_URL: http://127.0.0.1:6333
✅ QDRANT_API_KEY: qs-8d9f-...
✅ BASE_COLLECTION_NAME: dovodi_collection
✅ JINA_API_KEY: jina_04d...
❌ OPENAI_API_KEY: Not configured

🔄 Testing Qdrant Basic Connection...
==================================================
📍 Qdrant URL: http://127.0.0.1:6333
✅ Qdrant HTTP health check: OK (endpoint: /)

🔄 Testing Qdrant Client Connection...
==================================================
Loading config from: F:\WORK\CODE\WORK\AGNO-DOVOODI\config\embeddings.yaml
✅ Embedder loaded: jina-embeddings-v4
✅ Vector store initialized
F:\WORK\CODE\WORK\AGNO-DOVOODI\.venv\Lib\site-packages\agno\vectordb\qdrant\qdrant.py:167: UserWarning: Api key is used with an insecure connection.
✅ Client connection successful
📊 Available collections: 9
📋 Collections:
   - islamic_knowledge_free
   - test_collection
   - dovodi_collection_jina-embeddings-v4
   - islamic_knowledge_jina-embeddings-v4
   - dovodi_collection
   ... and 4 more

🔄 Testing Qdrant Collection Operations...
==================================================
🧪 Testing with collection: test_connection_jina-embeddings-v4
📂 Collection exists: False
ℹ️  Note: Collection will be created on first vector operation
   This is normal behavior for Qdrant
✅ Collection access: OK (collection doesn't exist yet)

==================================================
📊 TEST RESULTS SUMMARY
==================================================
Environment Configuration: ✅ PASSED
Basic HTTP Connection: ✅ PASSED
Client Connection: ✅ PASSED
Collection Operations: ✅ PASSED

🎉 ALL TESTS PASSED!
✨ Your Qdrant vector database is connected and ready to use.

اجرای تست‌های pytest

# اجرای همه تست‌های Qdrant
pytest tests/integration/test_qdrant_connection.py -v

# اجرای تست‌های واحد فقط
pytest tests/integration/test_qdrant_connection.py -m unit -v

# اجرای تست‌های یکپارچه‌سازی فقط
pytest tests/integration/test_qdrant_connection.py -m integration -v

# اجرای تست خاص با جزئیات
pytest tests/integration/test_qdrant_connection.py::TestQdrantConnection::test_qdrant_real_connection_success -v -s

تنظیمات محیطی مورد نیاز

متغیرهای محیطی اصلی

# Qdrant connection
QDRANT_URL=http://127.0.0.1:6333          # آدرس Qdrant
QDRANT_API_KEY=your_api_key                # کلید API (اختیاری)

# Collection settings
BASE_COLLECTION_NAME=dovodi_collection     # نام پایه مجموعه

# Embedding API keys
JINA_API_KEY=your_jina_key                 # کلید API Jina
OPENAI_API_KEY=your_openai_key             # کلید API OpenAI (اختیاری)

فایل‌های تنظیمات

• config/embeddings.yaml - تنظیمات embedder
• config/production.env - تنظیمات تولید
• config/development.env - تنظیمات توسعه

انواع خروجی‌ها

✅ خروجی موفق

================== 5 passed, 1 skipped, 6 warnings in 2.65s ===================

❌ خروجی ناموفق

FAILED tests/integration/test_qdrant_connection.py::TestQdrantConnection::test_name - Error details

⚠️ خروجی هشدار

PytestUnknownMarkWarning: Unknown pytest.mark.unit

عیب‌یابی مشکلات رایج

مشکل: اتصال به Qdrant برقرار نیست

علائم:

❌ Qdrant HTTP health check: FAILED
httpx.ConnectError: [Errno 11001] getaddrinfo failed

راه‌حل‌ها:

1. بررسی اجرای Qdrant: docker ps | grep qdrant
2. بررسی URL: echo $QDRANT_URL
3. بررسی فایروال و پورت 6333

مشکل: API Key نامعتبر

علائم:

❌ Client connection test failed: Unauthorized

راه‌حل‌ها:

1. بررسی QDRANT_API_KEY در .env
2. اطمینان از صحت کلید API
3. بررسی تنظیمات امنیتی Qdrant

مشکل: Embedder بارگذاری نمی‌شود

علائم:

❌ Embedder loaded: FAILED

راه‌حل‌ها:

1. بررسی config/embeddings.yaml
2. بررسی کلیدهای API (JINA_API_KEY)
3. بررسی اتصال اینترنت برای embedderهای API-based

مشکل: مجموعه‌ها پاک نمی‌شوند

علائم:

❌ Failed to verify/clean up test collection

راه‌حل‌ها:

1. بررسی مجوزهای نوشتن در Qdrant
2. بررسی فضای دیسک کافی
3. بررسی تنظیمات Qdrant برای عملیات حذف

ساختار فایل‌ها

tests/integration/test_qdrant_connection.py  # تست‌های pytest
test_qdrant_connection.py                   # تست مستقل
docs/QDRANT_CONNECTION_TEST.md             # این سند
src/knowledge/vector_store.py              # کد اتصال Qdrant
config/embeddings.yaml                     # تنظیمات embedder

نکات مهم

1. تست‌های یکپارچه‌سازی نیاز به Qdrant واقعی دارند
2. تست‌های واحد از Mock استفاده می‌کنند
3. همه مجموعه‌های موجود در خروجی نمایش داده می‌شوند
4. خطاها به طور کامل لاگ می‌شوند
5. تنظیمات محیطی باید قبل از اجرا بررسی شوند

مثال خروجی کامل

🗄️  Qdrant Vector Database Connection Test
Testing connection to Qdrant vector database

🔧 Checking Environment Configuration...
✅ QDRANT_URL: http://127.0.0.1:6333
✅ QDRANT_API_KEY: qs-8d9f-...
✅ BASE_COLLECTION_NAME: dovodi_collection
✅ JINA_API_KEY: jina_04d...
❌ OPENAI_API_KEY: Not configured

🔄 Testing Qdrant Basic Connection...
📍 Qdrant URL: http://127.0.0.1:6333
✅ Qdrant HTTP health check: OK (endpoint: /)

🔄 Testing Qdrant Client Connection...
Loading config from: config/embeddings.yaml
✅ Embedder loaded: jina-embeddings-v4
✅ Vector store initialized
✅ Client connection successful
📊 Available collections: 9
📋 Collections:
   1. islamic_knowledge_free
   2. test_collection
   3. dovodi_collection_jina-embeddings-v4
   4. islamic_knowledge_jina-embeddings-v4
   5. dovodi_collection
   ... and 4 more

🎉 ALL TESTS PASSED!
✨ Your Qdrant vector database is connected and ready to use.