Qdrant: inserare puncte cu vectori și payload (upsert) în Baze de Date Vectoriale & Căutare Semantică

from qdrant_client import models

client.upsert(
    collection_name="articole_dexblog",
    points=[
        models.PointStruct(
            id=101,
            vector=[0.021, -0.045, 0.089],   # lungimea = dimensiunea colecției
            payload={"titlu": "Ghid Docker", "categorie": "devops", "an": 2026,
                     "tags": ["linux", "containere"]},
        )
    ],
)

În Qdrant fiecare înregistrare este un punct: un id (întreg fără semn pe 64 de biți sau UUID), unul sau mai mulți vectori și un payload opțional (JSON: șiruri, numere, liste, obiecte imbricate).

upsert inserează punctul dacă ID-ul nu există și îl înlocuiește dacă există. Comportamentul se poate schimba cu update_mode (de exemplu update_only). Pentru volume mari se trimit loturi de puncte într-un singur apel sau se folosește upload_points.

Payload-ul nu este indexat automat. Filtrarea funcționează și fără index, dar pentru câmpurile folosite des la filtrare documentația recomandă un payload index (create_payload_index), creat înainte de încărcarea datelor, ca graful HNSW să primească muchiile suplimentare pentru filtrare.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
id	Întreg fără semn (101) sau UUID ("9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d").
vector	Lista de valori, cu exact dimensiunea declarată în colecție (sau un dicționar pentru vectori cu nume).
payload	Obiect JSON arbitrar.
wait=True	Implicit în clientul Python: răspunsul vine după ce modificările au fost aplicate. Cu False, răspunsul vine imediat după confirmarea primirii.
set_payload / overwrite_payload / delete_payload	Modifică doar payload-ul, fără a retrimite vectorul.

Exemple practice și scenarii reale

Exemplul 1: ID stabil derivat din URL

import uuid

point_id = str(uuid.uuid5(uuid.NAMESPACE_URL, url))

Exemplul 2: Actualizarea payload-ului pentru câteva puncte

client.set_payload(
    collection_name="articole_dexblog",
    payload={"vizualizari": 1500},
    points=[101],
)

Exemplul 3: Index de payload pe un câmp de filtrare

client.create_payload_index(
    collection_name="articole_dexblog",
    field_name="categorie",
    field_schema=models.PayloadSchemaType.KEYWORD,
)

Greșeli frecvente și capcane

• Folosești ID-uri șir care nu sunt UUID (de exemplu "doc_1"). Qdrant acceptă doar întregi fără semn sau UUID-uri; derivă un UUID cu uuid5.
• Te bazezi pe indexarea automată a payload-ului. Creează explicit indecșii pentru câmpurile filtrate, înainte de încărcarea datelor.
• Nu salvezi textul sursă în payload. Fără el, după căutare ai nevoie de încă o bază de date ca să afișezi fragmentul găsit.

Noțiuni și module înrudite

• qdrant-client-collections
• qdrant-search-filtering
• multitenancy-vector-namespaces