Chroma: clienți, colecții și persistență (PersistentClient) în Baze de Date Vectoriale: sintaxă, interogare și exemple

import chromadb client = chromadb.PersistentClient(path="./chroma_data") colectie = client.get_or_create_collection( name="articole", configuration={"hnsw": {"space": "cosine"}}, # implicit: l2 )

Chroma este o bază de date vectorială open-source cu clienți pentru Python și TypeScript. În Python poți porni un server în memorie (chromadb.Client() sau EphemeralClient(), fără persistență), un client care salvează pe disc (PersistentClient(path=...), implicit în .chroma), un client pentru un server Chroma separat (HttpClient) sau pentru Chroma Cloud (CloudClient).

Fiecare colecție are o funcție de embedding. Dacă nu dai una, Chroma folosește DefaultEmbeddingFunction, care rulează local modelul Sentence Transformers all-MiniLM-L6-v2 (descărcat automat la prima folosire). Funcția se aplică atunci când adaugi sau cauți documente fără vectori precalculați.

Indexul se configurează prin configuration. Pentru HNSW, space poate fi l2 (L2 la pătrat, implicit), cosine sau ip; mai există ef_construction (implicit 100), ef_search (implicit 100) și max_neighbors (implicit 16). Metrica trebuie să fie suportată de funcția de embedding a colecției.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
`PersistentClient(path=...)`	Datele se salvează automat și se reîncarcă la pornire.
`Client() / EphemeralClient()`	Client în memorie, pentru teste și experimente.
`HttpClient / CloudClient`	Conectare la un server Chroma sau la Chroma Cloud.
`configuration={"hnsw": {...}}`	`space`, `ef_construction`, `ef_search`, `max_neighbors` și altele. `ef_search` se poate schimba după creare.
`embedding_function`	Funcția care transformă textul în vectori; implicit `all-MiniLM-L6-v2`.
`get_or_create_collection / delete_collection / count()`	Gestionarea colecțiilor; `get_or_create` ignoră argumentele dacă colecția există deja.

Exemple practice și scenarii reale

Exemplul 1: Instalare

pip install chromadb

Exemplul 2: Colecție cu funcție de embedding OpenAI

from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

colectie = client.create_collection(
    name="articole-openai",
    embedding_function=OpenAIEmbeddingFunction(model_name="text-embedding-3-small"),
    configuration={"hnsw": {"space": "cosine", "ef_construction": 200}},
)

Exemplul 3: Ștergerea și numărarea

client.delete_collection(name="articole_vechi")
print(colectie.count())

Greșeli frecvente și capcane

Folosești metadata={"hnsw:space": "cosine"} din exemplele vechi. În documentația actuală metrica se setează prin configuration={"hnsw": {"space": "cosine"}}.
Uiți că metrica implicită este l2. Dacă modelul tău de embedding e gândit pentru cosinus, setează explicit space la creare.
Ai vectori calculați cu alt model decât funcția colecției și cauți cu query_texts. Interogarea va fi vectorizată cu funcția colecției; folosește query_embeddings sau aceeași funcție.

`Chroma: clienți, colecții și persistență (PersistentClient)` în Baze de Date Vectoriale & Căutare Semantică