Qdrant: inițializare client și creare colecții în Python în Baze de Date Vectoriale & Căutare Semantică

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")   # sau path="./qdrant_db", sau ":memory:"

if not client.collection_exists("articole_dexblog"):
    client.create_collection(
        collection_name="articole_dexblog",
        vectors_config=models.VectorParams(size=1536, distance=models.Distance.COSINE),
    )

Qdrant este un motor open-source de căutare vectorială, scris în Rust, disponibil și ca serviciu (Qdrant Cloud). Clientul Python oficial se instalează cu pip install qdrant-client.

Clientul poate rula în trei moduri: în memorie (QdrantClient(":memory:"), pentru teste), local pe disc (QdrantClient(path="./qdrant_db"), fără server) sau conectat la un server prin url și, opțional, api_key. Se dă un singur mod: location, url, host sau path.

Datele stau în colecții. O colecție are configurația vectorilor (dimensiune și metrică: Cosine, Dot, Euclid, Manhattan; mai mulți vectori cu nume pe același punct, dacă e nevoie), configurația HNSW, cuantizarea opțională și setările de memorie. Implicit HNSW are m = 16 și ef_construct = 100.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
collection_name	Numele colecției.
vectors_config	VectorParams(size=..., distance=...) sau un dicționar de vectori cu nume.
hnsw_config	HnswConfigDiff(m=..., ef_construct=...); opțional.
quantization_config	Cuantizare scalară, binară, PQ sau TurboQuant; opțional.
collection_exists(nume)	Verifică existența colecției; recreate_collection este depreciat.
payload (memory)	Locul payload-ului (RAM sau disc) se setează, de la Qdrant 1.19, prin configurația de memorie; on_disk_payload este depreciat.

Exemple practice și scenarii reale

Exemplul 1: Client în memorie pentru teste

client = QdrantClient(":memory:")

Exemplul 2: Conectare la un server cu cheie API

client = QdrantClient(url="http://localhost:6333", api_key="secret")

Exemplul 3: Pornirea serverului cu Docker

docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

Greșeli frecvente și capcane

• Apelezi create_collection la fiecare pornire. Folosește collection_exists() înainte; recreate_collection este depreciat și șterge datele.
• Dai și url, și path. Clientul acceptă un singur mod de conectare.
• Creezi indecșii de payload după ce ai încărcat datele. Documentația cere crearea lor imediat după colecție, ca HNSW să construiască muchiile pentru filtrare.

Noțiuni și module înrudite

• qdrant-upsert-payload
• qdrant-search-filtering
• concepte-vector-db
• quantization-scalar-product