اگر برای RAG فارسی، جستجوی معنایی یا چت‌بات روی اسناد خود به یک پایگاه داده برداری سریع و سبک نیاز دارید، Qdrant بهترین نقطه شروع است. این دیتابیس متن‌باز بردارها (Embeddingها) را با متادیتا ذخیره می‌کند و جستجوی شباهت را در میلی‌ثانیه با فیلترهای دقیق انجام می‌دهد. در این آموزش از نصب با Docker تا ساخت کالکشن، ذخیره امبدینگ فارسی و جستجوی معنایی در پایتون را گام‌به‌گام می‌بینید.

Qdrant چیست و چطور جستجوی معنایی را ممکن می‌کند؟

Qdrant یک پایگاه داده برداری (Vector Database) نوشته‌شده با Rust است که بردارهای عددی تولیدشده توسط مدل‌های امبدینگ را کنار متادیتای هر سند ذخیره و با الگوریتم HNSW نزدیک‌ترین بردارها را با سرعت بالا برمی‌گرداند. کافی است متن فارسی را به بردار تبدیل کنید، در Qdrant ذخیره کنید و با یک بردار پرسش، مشابه‌ترین نتایج را با فیلتر متادیتا بگیرید. در ادامه نصب، کد پایتون و مقایسه عملی را می‌خوانید.

فهرست مطالب

Qdrant چیست و چرا برای RAG لازم است؟
پیش‌نیازها و نصب Qdrant با Docker
نصب کلاینت پایتون و ساخت اولین کالکشن
تولید امبدینگ فارسی و ذخیره بردارها
جستجوی معنایی و فیلتر متادیتا
مقایسه Qdrant با Chroma و Milvus
کاربرد واقعی؛ ساخت RAG فارسی کوچک
نکات امنیتی و بهینه‌سازی
اشتباهات رایج هنگام کار با Qdrant
سوالات متداول
جمع‌بندی

Qdrant چیست و چرا برای RAG لازم است؟

در RAG (Retrieval-Augmented Generation) شما متن‌ها را تکه‌تکه (Chunk) می‌کنید، هر تکه را به بردار تبدیل می‌کنید و هنگام پرسش کاربر، نزدیک‌ترین تکه‌ها را به مدل زبانی می‌دهید. بدون دیتابیس برداری، این جستجو کند و بدون فیلتر است. Qdrant این بخش را حل می‌کند:

ذخیره بردار + متادیتا: هر نقطه (Point) شامل id، بردار vector و یک دیکشنری payload مثل عنوان، منبع، تاریخ و دسته است.
جستجوی HNSW سریع: حتی با میلیون‌ها بردار، جستجوی cosine در ده‌ها میلی‌ثانیه.
فیلتر ترکیبی: می‌توانید بگویید «فقط در دسته آموزش و تاریخ ۱۴۰۳ جستجو کن» و هم‌زمان شباهت برداری بگیرید.
سبک و بدون وابستگی سنگین: با یک کانتینر Docker بالا می‌آید و کلاینت رسمی پایتون دارد.

اگر مدل زبانی را محلی اجرا می‌کنید، آموزش اجرای مدل آفلاین با Ollama مکمل خوبی برای این پایپ‌لاین RAG است تا همه چیز روی سیستم خودتان بماند.

پیش‌نیازها و نصب Qdrant با Docker

به Docker و پایتون ۳.۹+ نیاز دارید. Qdrant بدون نیاز به نصب پیچیده، با یک دستور اجرا می‌شود و داشبورد آن روی http://localhost:6333/dashboard در دسترس است.

docker pull qdrant/qdrant

docker run -p 6333:6333 -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

پورت 6333: REST API و داشبورد
پورت 6334: gRPC برای کارهای سنگین
حجم ذخیره: با -v داده‌ها حتی پس از خاموشی کانتینر باقی می‌ماند.

برای تست سریع: مرورگر را باز کنید و http://localhost:6333/dashboard را ببینید؛ اگر کالکشن‌ها لود شد نصب موفق است. در لینوکس اگر پورت اشغال بود، docker ps و docker stop را چک کنید.

نصب کلاینت پایتون و ساخت اولین کالکشن

کلاینت رسمی qdrant-client همه کارها را با پایتون انجام می‌دهد.

pip install qdrant-client sentence-transformers

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance

client = QdrantClient(host="localhost", port=6333)

# ساخت کالکشن با 384 بعد (برای مدل MiniLM) و فاصله کسینوس
client.recreate_collection(
    collection_name="persian_docs",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

info = client.get_collection("persian_docs")
print(info.status)

size: باید دقیقاً برابر بعد خروجی مدل امبدینگ شما باشد (384، 768 یا 1024).
Distance.COSINE: برای متن فارسی و جستجوی معنایی بهترین انتخاب است.
recreate_collection: اگر کالکشن وجود داشته باشد آن را از نو می‌سازد؛ در تولید از create_collection استفاده کنید.

تولید امبدینگ فارسی و ذخیره بردارها

برای فارسی، مدل‌های چندزبانه مثل paraphrase-multilingual-MiniLM-L12-v2 یا sentence-transformers/all-MiniLM-L6-v2 تعادل خوبی بین کیفیت و سرعت دارند. اگر داده حجیم دارید، راهنمای Polars برای داده‌های حجیم به شما کمک می‌کند دیتافریم‌ها را قبل از امبدینگ سریع تمیز کنید.

from sentence_transformers import SentenceTransformer
from qdrant_client.models import PointStruct

model = SentenceTransformer("sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")

texts = [
    "آموزش Qdrant برای جستجوی معنایی در پایتون",
    "نصب Qdrant با Docker و اجرای سرور محلی",
    "مقایسه پایگاه داده برداری Qdrant و Chroma"
]

vectors = model.encode(texts, normalize_embeddings=True).tolist()

points = [
    PointStruct(
        id=i,
        vector=vectors[i],
        payload={"text": texts[i], "category": "آموزش", "lang": "fa"}
    )
    for i in range(len(texts))
]

client.upsert(collection_name="persian_docs", points=points)
print("upsert done:", len(points))

normalize_embeddings=True: با COSINE حتماً نرمال کنید تا امتیاز دقیق شود.
payload: متن اصلی و متادیتا را نگه دارید تا در نتایج بدون مراجعه به دیتابیس دیگر، متن را برگردانید.
id: می‌تواند عدد یا UUID باشد؛ یکتا بودنش مهم است.

جستجوی معنایی و فیلتر متادیتا

حالا یک پرسش جدید را امبد کنید و نزدیک‌ترین‌ها را بگیرید:

query = "چطور Qdrant را با پایتون نصب کنم؟"
q_vector = model.encode(query, normalize_embeddings=True).tolist()

results = client.search(
    collection_name="persian_docs",
    query_vector=q_vector,
    limit=3,
    with_payload=True
)

for r in results:
    print(f"{r.score:.3f} - {r.payload['text']}")

جستجو با فیلتر دسته

from qdrant_client.models import Filter, FieldCondition, MatchValue

results = client.search(
    collection_name="persian_docs",
    query_vector=q_vector,
    query_filter=Filter(must=[FieldCondition(key="category", match=MatchValue(value="آموزش"))]),
    limit=3
)

score: با COSINE بین ۰ تا ۱ است؛ بالای 0.75 یعنی بسیار مرتبط.
limit: تعداد نتایج؛ برای RAG معمولاً 3 تا 5 کافی است.
Filter: فیلتر قبل از جستجو اعمال می‌شود و سرعت را کم نمی‌کند.

مقایسه Qdrant با Chroma و Milvus

انتخاب دیتابیس به مقیاس و نیاز عملیاتی شما بستگی دارد:

معیار	Qdrant	Chroma	Milvus
زبان هسته	Rust — بسیار سریع	پایتون + SQLite	Go + C++
نصب	یک دستور Docker	pip install	Docker Compose سنگین
فیلتر متادیتا	پیشرفته و ترکیبی	ساده	پیشرفته
مقیاس	تا ده‌ها میلیون بردار روی یک نود	مناسب نمونه اولیه	میلیاردی، توزیع‌شده
مناسب برای	RAG تولیدی کوچک تا متوسط	پروتوتایپ و آموزش	سازمانی بسیار بزرگ

برای پروژه‌های فارسی با زیر ۵ میلیون سند، Qdrant بهترین تعادل سرعت، سادگی و فیلتر است. اگر نمونه اولیه کلاسی می‌سازید Chroma کافی است؛ برای میلیارد ردیف به Milvus مهاجرت کنید.

کاربرد واقعی؛ ساخت RAG فارسی کوچک در ۳۰ خط

این الگو را برای چت‌بات روی PDFها یا مقالات سایت خود به کار ببرید:

# 1) تکه‌تکه کردن متن (Chunk)
# 2) امبد و ذخیره در Qdrant (کد بالا)
# 3) بازیابی و ارسال به LLM
from qdrant_client import QdrantClient
from sentence_transformers import SentenceTransformer

client = QdrantClient(host="localhost", port=6333)
model = SentenceTransformer("paraphrase-multilingual-MiniLM-L12-v2")

def answer(question: str):
    qv = model.encode(question, normalize_embeddings=True).tolist()
    hits = client.search(collection_name="persian_docs", query_vector=qv, limit=3, with_payload=True)
    context = "\n".join([h.payload["text"] for h in hits])
    prompt = f"با توجه به متن زیر پاسخ بده:\n{context}\n\nسوال: {question}"
    return prompt  # این prompt را به Ollama یا OpenAI بدهید

print(answer("تفاوت Qdrant و Chroma چیست؟"))

Chunk: هر تکه 300 تا 500 کلمه با هم‌پوشانی 50 کلمه.
امبدینگ فارسی: حتماً مدل چندزبانه انتخاب کنید؛ مدل انگلیسی خالص افت کیفیت دارد.
اتصال به LLM: خروجی prompt را به ollama run llama3.2 یا API ابری بدهید.

نکات امنیتی و بهینه‌سازی

Qdrant را به اینترنت باز نکنید: به صورت پیش‌فرض بدون احراز هویت است؛ با فایروال فقط روی localhost نگه دارید یا API Key فعال کنید.
بعد بردار را ثابت نگه دارید: تغییر مدل امبدینگ نیاز به ساخت دوباره کالکشن دارد.
ایندکس HNSW: پارامتر m=16 و ef_construct=200 تعادل خوبی است؛ برای دقت بالاتر ef را بالا ببرید.
پشتیبان: از اسنپ‌شات Qdrant با client.create_snapshot() برای بک‌آپ روزانه استفاده کنید.
حذف و به‌روزرسانی: با client.delete یا client.set_payload بدون بازسازی کل کالکشن رکورد را ویرایش کنید.

اشتباهات رایج هنگام کار با Qdrant

عدم تطابق size: بعد بردار مدل با size کالکشن متفاوت است — خطای dimension mismatch می‌گیرید؛ اول model.get_sentence_embedding_dimension() را چاپ کنید.
فراموشی normalize: با COSINE اگر نرمال نکنید، امتیازها غیرقابل مقایسه می‌شود.
ذخیره متن بدون payload: فقط بردار ذخیره می‌کنید و بعد متن را ندارید؛ همیشه text را در payload بگذارید.
ساخت کالکشن در هر اجرا: استفاده از recreate_collection در حلقه، داده را پاک می‌کند؛ در تولید if not exists چک کنید.
چانک‌های خیلی بزرگ: تکه‌های 2000 کلمه‌ای کیفیت بازیابی را پایین می‌آورد؛ 300 تا 500 کلمه بهینه است.

سوالات متداول

آیا Qdrant بدون Docker هم اجرا می‌شود؟

بله، باینری آماده برای لینوکس دارد، اما Docker ساده‌ترین و تمیزترین روش است و به‌روزرسانی را با یک pull انجام می‌دهد. برای ویندوز WSL + Docker Desktop پیشنهاد می‌شود.

بهترین مدل امبدینگ برای فارسی چیست؟

مدل paraphrase-multilingual-MiniLM-L12-v2 سبک و دقیق است. برای کیفیت بالاتر intfloat/multilingual-e5-large را با پیشوند query: و passage: تست کنید؛ حدود 2 برابر کندتر اما دقیق‌تر است.

تفاوت Qdrant و Chroma را چطور انتخاب کنم؟

نمونه اولیه کلاسی و زیر 50 هزار سند → Chroma کافی است. پروژه تولیدی با فیلتر متادیتا، نیاز به سرعت و پایداری → Qdrant. مقیاس میلیاردی و کلاستر → Milvus.

آیا Qdrant داده را روی دیسک نگه می‌دارد؟

بله، با -v qdrant_storage:/qdrant/storage داده روی دیسک می‌ماند. بدون volume با حذف کانتینر داده پاک می‌شود. اسنپ‌شات منظم هم برای اطمینان بگیرید.

چطور Qdrant را با Ollama ترکیب کنم؟

متن‌ها را در Qdrant ذخیره کنید، هنگام پرسش نزدیک‌ترین‌ها را بازیابی کنید و متن آن‌ها را به عنوان Context به ollama run llama3.2 یا API محلی localhost:11434 بدهید. این ترکیب یک RAG کاملاً آفلاین و خصوصی می‌سازد.

جمع‌بندی

Qdrant را با یک دستور Docker روی 6333 بالا بیاورید و داشبورد را چک کنید.
با VectorParams(size=384, distance=COSINE) کالکشن بسازید و بعد مدل را عوض نکنید.
متن فارسی را با مدل چندزبانه امبد و همراه payload در Qdrant ذخیره کنید.
با search + Filter جستجوی معنایی فیلتردار انجام دهید و 3 نتیجه برتر را به LLM بدهید.
برای تولید، Qdrant را پشت فایروال نگه دارید، اسنپ‌شات بگیرید و چانک‌ها را 300 تا 500 کلمه کنید.
از نمونه RAG همین مقاله شروع کنید و سپس آن را به اسناد واقعی خود وصل کنید.

حالا نوبت شماست: Qdrant را اجرا کنید، سه متن فارسی خود را ذخیره و یک پرسش معنایی تست کنید — اگر امتیاز بالای 0.75 گرفتید، پایپ‌لاین RAG شما آماده اتصال به مدل زبانی است.

آموزش Qdrant در پایتون؛ ذخیره و جستجوی برداری برای RAG فارسی