Bases de dados vetoriais (Pinecone, Qdrant, Weaviate)
Nesta página
Objetivos
- Compreender por que as bases de dados vetoriais são necessárias
- Comparar Pinecone, Qdrant, Weaviate, Chroma e pgvector
- Implementar a pesquisa com cada uma delas
Por que uma base de dados vetorial?
O índice NumPy da lição anterior funciona perfeitamente para alguns milhares de documentos, pois uma varredura exaustiva de dez mil vetores permanece impercetível. Com um milhão, esse mesmo cálculo gera um segundo de latência por consulta, e a matriz já não cabe confortavelmente na memória.
Quatro necessidades surgem em conjunto. A pesquisa ANN (Approximate Nearest Neighbors) abandona a garantia de um resultado exato em favor de uma resposta em milissegundos sobre milhões de vetores — um compromisso quase sempre aceitável, já que devolver o quinto melhor documento em vez do quarto não altera nada na experiência do utilizador. A filtragem por metadados, combinada com a pesquisa vetorial, permite restringir uma consulta a uma categoria, idioma ou intervalo de datas sem pós-processamento. A persistência e as atualizações em tempo real evitam reconstruir um ficheiro inteiro apenas para adicionar um documento. Por fim, a escalabilidade horizontal é o que distingue um protótipo de um serviço de produção.
Pinecone
O Pinecone é um serviço gerido: não provisiona servidores, cria um índice especificando a sua dimensão e métrica, e o restante é tratado por si. Note o filtro categorie passado diretamente para query — a pesquisa vetorial e a filtragem são executadas em conjunto, não sequencialmente.
from pinecone import Pinecone
from openai import OpenAI
pc = Pinecone(api_key="your-pinecone-key")
openai_client = OpenAI()
# Create an index
pc.create_index(
name="my-corpus",
dimension=3072,
metric="cosine",
spec={"serverless": {"cloud": "aws", "region": "eu-west-1"}}
)
index = pc.Index("my-corpus")
# Index documents
documents = [
{"id": "doc1", "texte": "Python Installation Guide",
"categorie": "tutorial"},
{"id": "doc2", "texte": "Deploying a Flask Application",
"categorie": "tutorial"},
{"id": "doc3", "texte": "Q1 2026 Quarterly Report",
"categorie": "report"},
]
# Generate embeddings
textes = [d["texte"] for d in documents]
response = openai_client.embeddings.create(
input=textes,
model="text-embedding-3-large"
)
# Upsert into Pinecone
vecteurs = [
{
"id": doc["id"],
"values": emb.embedding,
"metadata": {"texte": doc["texte"], "categorie": doc["categorie"]}
}
for doc, emb in zip(documents, response.data)
]
index.upsert(vectors=vecteurs)
# Search
query_emb = openai_client.embeddings.create(
input="how to install Python",
model="text-embedding-3-large"
).data[0].embedding
resultats = index.query(
vector=query_emb,
top_k=3,
include_metadata=True,
filter={"categorie": {"$eq": "tutorial"}}
)
for match in resultats.matches:
print(f"[{match.score:.3f}] {match.metadata['texte']}")
A dimensão declarada na criação é definitiva: mudar de text-embedding-3-large para text-embedding-3-small exige recriar o índice. Decida, portanto, o modelo antes, e não depois.
Qdrant
O Qdrant é open source, autoalojado e oferece excelente desempenho. O vocabulário difere — falamos de coleções, pontos e payloads, enquanto o Pinecone fala de índices, vetores e metadados — mas o esquema permanece idêntico. Note que o exemplo chama a API de embeddings documento a documento dentro do ciclo: isso é aceitável para três documentos, mas pense em voltar aos lotes assim que o corpus crescer.
from qdrant_client import QdrantClient
from qdrant_client.models import (
Distance, VectorParams, PointStruct, Filter,
FieldCondition, MatchValue
)
from openai import OpenAI
qclient = QdrantClient(url="http://localhost:6333")
openai_client = OpenAI()
# Create a collection
qclient.create_collection(
collection_name="my-corpus",
vectors_config=VectorParams(
size=3072,
distance=Distance.COSINE
)
)
# Index documents
points = []
for i, doc in enumerate(documents):
emb = openai_client.embeddings.create(
input=doc["texte"],
model="text-embedding-3-large"
).data[0].embedding
points.append(PointStruct(
id=i,
vector=emb,
payload={"texte": doc["texte"], "categorie": doc["categorie"]}
))
qclient.upsert(collection_name="my-corpus", points=points)
# Search with filter
query_emb = openai_client.embeddings.create(
input="deploy a web application",
model="text-embedding-3-large"
).data[0].embedding
resultats = qclient.search(
collection_name="my-corpus",
query_vector=query_emb,
limit=3,
query_filter=Filter(
must=[FieldCondition(
key="categorie",
match=MatchValue(value="tutorial")
)]
)
)
for r in resultats:
print(f"[{r.score:.3f}] {r.payload['texte']}")
Weaviate
O Weaviate destaca-se pela sua pesquisa híbrida nativa, que revisitaremos na lição 9. O seu modelo de dados é mais estruturado do que o dos concorrentes: declara explicitamente as propriedades e os seus tipos antes de inserir qualquer coisa, o que aproxima a experiência da de uma base de dados clássica.
import weaviate
from openai import OpenAI
wclient = weaviate.connect_to_local()
openai_client = OpenAI()
# Create a collection
from weaviate.classes.config import Property, DataType
collection = wclient.collections.create(
name="Document",
properties=[
Property(name="texte", data_type=DataType.TEXT),
Property(name="categorie", data_type=DataType.TEXT),
]
)
# Index
for doc in documents:
emb = openai_client.embeddings.create(
input=doc["texte"],
model="text-embedding-3-large"
).data[0].embedding
collection.data.insert(
properties={"texte": doc["texte"], "categorie": doc["categorie"]},
vector=emb
)
# Search
query_emb = openai_client.embeddings.create(
input="install Python",
model="text-embedding-3-large"
).data[0].embedding
resultats = collection.query.near_vector(
near_vector=query_emb,
limit=3
)
Chroma e pgvector
O Chroma visa a prototipagem rápida: um cliente persistente apontado para uma pasta local, uma coleção criada no momento, sem infraestrutura. É a opção que o leva de um índice NumPy a uma base de dados real sem alterar o seu ambiente de trabalho.
import chromadb
from openai import OpenAI
chroma = chromadb.PersistentClient(path="./chroma_db")
openai_client = OpenAI()
collection = chroma.get_or_create_collection("my-corpus")
# Index
for doc in documents:
emb = openai_client.embeddings.create(
input=doc["texte"],
model="text-embedding-3-large"
).data[0].embedding
collection.add(
ids=[doc["id"]],
embeddings=[emb],
documents=[doc["texte"]],
metadatas=[{"categorie": doc["categorie"]}]
)
# Search
query_emb = openai_client.embeddings.create(
input="how to install Python",
model="text-embedding-3-large"
).data[0].embedding
resultats = collection.query(query_embeddings=[query_emb], n_results=3)
O pgvector aborda uma situação muito diferente: os seus documentos já estão no PostgreSQL, com as suas junções, controlos de acesso e cópias de segurança. Em vez de introduzir um segundo sistema para sincronizar, a extensão adiciona um tipo vector e operadores de distância à base de dados existente. O operador <=> calcula a distância do cosseno, e o índice HNSW é o que torna a consulta utilizável além de algumas milhares de linhas.
-- pgvector extension
CREATE EXTENSION vector;
CREATE TABLE documents (
id SERIAL PRIMARY KEY,
texte TEXT,
categorie TEXT,
embedding vector(3072)
);
-- HNSW index for performance
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops);
-- Search for the 5 nearest neighbors
SELECT id, texte, 1 - (embedding <=> $1::vector) AS score
FROM documents
ORDER BY embedding <=> $1::vector
LIMIT 5;
Comparação
| Critério | Pinecone | Qdrant | Weaviate | Chroma | pgvector |
|---|---|---|---|---|---|
| Tipo | Gerido | Open source | Open source | Open source | Extensão |
| Alojamento | Nuvem | Autoalojado/Nuvem | Autoalojado/Nuvem | Local/Incorporado | PostgreSQL |
| Pesquisa híbrida | ✅ | ✅ | ✅ Nativa | ❌ | Via SQL |
| Produção | ✅ | ✅ | ✅ | ⚠️ Prototipagem | ✅ |
| Facilidade de uso | ✅✅ | ✅ | ✅ | ✅✅ | ✅ |
A escolha depende menos do desempenho bruto, que é muito próximo na prática, do que do seu contexto: uma equipa que já executa PostgreSQL tem todo o interesse em manter-se nele, uma equipa sem operações escolherá uma solução gerida, e uma equipa que deve alojar na Europa por razões regulamentares voltará para soluções autoalojadas.
Pontos-chave
- Chroma para prototipagem rápida
- pgvector se já tiver PostgreSQL
- Pinecone para uma solução gerida, sem infraestrutura
- Qdrant para autoalojamento de alto desempenho
- Weaviate para pesquisa híbrida nativa