Kurs Python · Moduł 11: RAG i systemy wieloagentowe
Vector Databases
W tej lekcji6
W poprzedniej lekcji trzymaliśmy embeddingi w macierzy NumPy. Przy pięciu dokumentach to wystarcza, ale przy milionie macierz nie mieści się w pamięci, znika po restarcie programu, a przeszukanie jej za każdym razem trwa za długo. Potrzebujemy archiwum tropów, które przetrwa noc w obozie i odpowie w milisekundach.
Vector databases to specjalizowane bazy danych zoptymalizowane do przechowywania i wyszukiwania embeddingów. To jak biblioteka z magicznym katalogiem, który znajduje podobne książki na podstawie ich treści, a nie tytułu.
Popularne Vector Databases
Schemat grupuje popularne bazy według tego, gdzie działają:
┌─────────────────────────────────────────────────────────┐
│ Vector Databases Landscape │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Pinecone │ │ Qdrant │ │ Chroma │ │
│ │ (Cloud) │ │ (Self-host) │ │ (Local) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Weaviate │ │ Milvus │ │ FAISS │ │
│ │ (Semantic) │ │ (Enterprise)│ │ (In-memory) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘Pinecone działa wyłącznie w chmurze jako usługa zarządzana, Qdrant i Milvus możesz postawić na własnym serwerze, Chroma świetnie sprawdza się lokalnie przy prototypach, a FAISS to biblioteka od Meta, która trzyma indeks w pamięci procesu.
Chroma - lokalna vector database
Chroma to lokalna vector database dla aplikacji RAG, którą instalujesz jednym pip install chromadb. Najpierw tworzymy klienta, funkcję embeddingu i kolekcję, czyli odpowiednik tabeli:
import chromadb
from chromadb.utils import embedding_functions
# Inicjalizacja klienta
client = chromadb.Client() # In-memory
# lub: client = chromadb.PersistentClient(path="./chroma_db") # Persistent
# Konfiguracja funkcji embeddingu
openai_ef = embedding_functions.OpenAIEmbeddingFunction(
api_key="twój-klucz",
model_name="text-embedding-3-small"
)
# Tworzenie kolekcji
collection = client.create_collection(
name="python_safari",
embedding_function=openai_ef,
metadata={"description": "Dokumentacja kursu Python Safari"}
)chromadb.Client() trzyma dane tylko w pamięci, a PersistentClient zapisuje je w katalogu na dysku. Kolekcja sama wywoła openai_ef dla każdego dokumentu, więc nie musisz ręcznie liczyć embeddingów. Klucza API nie wpisuj w kod jak w przykładzie: w prawdziwym projekcie czytaj go ze zmiennej środowiskowej.
Teraz dodajemy dokumenty z metadanymi i od razu wyszukujemy:
# Dodawanie dokumentów
collection.add(
documents=[
"Python to język programowania wysokiego poziomu",
"RAG łączy retrieval z generowaniem tekstu",
"Vector databases przechowują embeddings"
],
metadatas=[
{"topic": "python", "level": "beginner"},
{"topic": "ai", "level": "advanced"},
{"topic": "databases", "level": "intermediate"}
],
ids=["doc1", "doc2", "doc3"]
)
# Wyszukiwanie
results = collection.query(
query_texts=["Jak zacząć naukę programowania?"],
n_results=2,
where={"level": "beginner"} # Filtrowanie po metadanych
)
print(results)Każdy dokument potrzebuje unikalnego id. Parametr where filtruje po metadanych jeszcze przed porównaniem wektorów, więc tu przejdzie tylko dokument z level równym beginner. Wynik to słownik list, po jednej na każde pytanie.
Jeśli masz już własne wektory, na przykład z funkcji get_embedding z poprzedniej lekcji, przekaż je w parametrze embeddings, a Chroma pominie liczenie:
# Własne wektory zamiast funkcji embeddingu kolekcji
collection.add(
documents=["Słonie wędrują do wodopoju o świcie"],
embeddings=[get_embedding("Słonie wędrują do wodopoju o świcie")],
ids=["doc4"]
)Wektory muszą mieć ten sam wymiar co reszta kolekcji, dlatego używamy tego samego modelu text-embedding-3-small.
Qdrant - produkcyjny vector search
Qdrant to baza, którą uruchamiasz na serwerze albo w kontenerze Dockera. Praca z nią ma zawsze cztery kroki: połączenie z klientem, utworzenie kolekcji z konfiguracją wektorów, dodanie punktów i wyszukiwanie. Pierwsze dwa kroki wyglądają tak:
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct
import numpy as np
# Połączenie z Qdrant
client = QdrantClient(host="localhost", port=6333)
# lub: client = QdrantClient(":memory:") # In-memory
# Tworzenie kolekcji
client.create_collection(
collection_name="documents",
vectors_config=VectorParams(
size=1536, # Rozmiar embeddingu
distance=Distance.COSINE
)
)VectorParams mówi bazie, jak długie będą wektory i jaką miarą je porównywać. size musi pasować do modelu embeddingów, tu 1536 dla text-embedding-3-small.
Punkt w Qdrant to wektor plus payload, czyli dowolny słownik z danymi:
# Dodawanie punktów
def add_documents(texts: list[str], embeddings: list[list[float]]):
"""Dodaje dokumenty do Qdrant."""
points = [
PointStruct(
id=i,
vector=embedding,
payload={"text": text}
)
for i, (text, embedding) in enumerate(zip(texts, embeddings))
]
client.upsert(
collection_name="documents",
points=points
)Metoda upsert wstawia nowe punkty albo nadpisuje istniejące o tym samym id, dlatego ponowne uruchomienie nie tworzy duplikatów.
Wyszukiwanie w aktualnym kliencie Pythona robimy metodą query_points. Starsza metoda search była oznaczona jako deprecated i nowe wersje qdrant-client już jej nie mają:
# Wyszukiwanie
def search(query_embedding: list[float], limit: int = 5):
"""Wyszukuje podobne dokumenty."""
results = client.query_points(
collection_name="documents",
query=query_embedding,
limit=limit
).points
return [
{
"text": hit.payload["text"],
"score": hit.score
}
for hit in results
]query_points zwraca obiekt z listą points, a każdy trafiony punkt ma score i payload.
Filtr działa jak where w Chromie, tylko ma bardziej formalną składnię:
# Filtrowanie
from qdrant_client.models import Filter, FieldCondition, MatchValue
filtered_results = client.query_points(
collection_name="documents",
query=query_embedding,
query_filter=Filter(
must=[
FieldCondition(
key="category",
match=MatchValue(value="python")
)
]
),
limit=5
).points.pointsUwaga na pułapkę: add_documents zapisuje w payloadzie tylko text, więc filtr po category nic nie znajdzie, dopóki nie dodasz tego pola do payloadu. query_embedding to wektor pytania, który masz już policzony.
FAISS - szybkie wyszukiwanie w pamięci
FAISS to nie serwer, tylko biblioteka. Indeks żyje w pamięci Twojego procesu. Owińmy go w klasę, która pamięta też teksty dokumentów:
import faiss
import numpy as np
from dataclasses import dataclass
@dataclass
class FAISSIndex:
"""Wrapper dla FAISS."""
dimension: int
index: faiss.Index = None
documents: list[str] = None
def __post_init__(self):
# Różne typy indeksów
# Flat - dokładny, wolniejszy
self.index = faiss.IndexFlatL2(self.dimension)
# IVF - szybszy, przybliżony
# quantizer = faiss.IndexFlatL2(self.dimension)
# self.index = faiss.IndexIVFFlat(quantizer, self.dimension, 100)
self.documents = []
def add(self, embeddings: np.ndarray, documents: list[str]):
"""Dodaje wektory do indeksu."""
embeddings = np.array(embeddings).astype('float32')
self.index.add(embeddings)
self.documents.extend(documents)IndexFlatL2 porównuje pytanie z każdym wektorem, więc wynik jest dokładny. Zakomentowany IndexIVFFlat jest szybszy, ale przybliżony i przed dodaniem wektorów wymaga treningu metodą train. FAISS przyjmuje wyłącznie float32, stąd konwersja w add.
Wyszukiwanie zwraca odległości i numery najbliższych sąsiadów:
def search(self, query_embedding: np.ndarray, k: int = 5) -> list[tuple[str, float]]:
"""Wyszukuje k najbliższych sąsiadów."""
query = np.array([query_embedding]).astype('float32')
distances, indices = self.index.search(query, k)
results = []
for idx, dist in zip(indices[0], distances[0]):
if 0 <= idx < len(self.documents):
results.append((self.documents[idx], float(dist)))
return resultsMniejsza odległość L2 oznacza większe podobieństwo, odwrotnie niż przy kosinusie. Gdy prosisz o więcej wyników, niż jest wektorów, FAISS zwraca indeks -1, dlatego sprawdzamy 0 <= idx.
Test na losowych wektorach pokazuje sam mechanizm:
# Przykład użycia
faiss_index = FAISSIndex(dimension=384)
# Dodaj dokumenty
embeddings = np.random.rand(100, 384).astype('float32')
documents = [f"Dokument {i}" for i in range(100)]
faiss_index.add(embeddings, documents)
# Wyszukaj
query = np.random.rand(384).astype('float32')
results = faiss_index.search(query, k=5)W prawdziwym kodzie zamiast losowych liczb podstawisz embeddingi z modelu o 384 wymiarach.
Pinecone - managed vector database
Pinecone to usługa w chmurze: nie instalujesz serwera, tylko tworzysz indeks przez API. Przy tworzeniu podajesz wymiar, metrykę i region:
from pinecone import Pinecone, ServerlessSpec
# Inicjalizacja
pc = Pinecone(api_key="twój-klucz")
# Tworzenie indeksu
pc.create_index(
name="python-safari",
dimension=1536,
metric="cosine",
spec=ServerlessSpec(
cloud="aws",
region="us-east-1"
)
)
# Połączenie z indeksem
index = pc.Index("python-safari")ServerlessSpec oznacza indeks bezserwerowy, rozliczany za użycie.
Upsert przyjmuje listę słowników z id, wektorem i metadanymi:
# Upsert (wstaw/aktualizuj)
index.upsert(
vectors=[
{
"id": "doc1",
"values": [0.1, 0.2, ...], # 1536 wartości
"metadata": {
"text": "Python to język programowania",
"category": "programming",
"level": 1
}
}
],
namespace="tutorials"
)Zapis [0.1, 0.2, ...] to skrót myślowy: w Pythonie trzy kropki są obiektem Ellipsis, więc w prawdziwym kodzie wstawiasz pełną listę 1536 liczb. namespace dzieli indeks na niezależne przegrody.
Zapytanie łączy wektor z filtrem po metadanych:
# Wyszukiwanie
results = index.query(
vector=[0.1, 0.2, ...],
top_k=10,
include_metadata=True,
namespace="tutorials",
filter={
"category": {"$eq": "programming"},
"level": {"$lte": 3}
}
)
# Statystyki
stats = index.describe_index_stats()
print(f"Liczba wektorów: {stats['total_vector_count']}")Operatory $eq i $lte znaczą "równe" oraz "mniejsze lub równe", a describe_index_stats podaje, ile wektorów leży w indeksie.
Hybrid Search - łączenie wektorów z BM25
Wektory świetnie łapią sens, ale potrafią przegapić dokładną nazwę, na przykład numer modelu. BM25 to klasyczny algorytm wyszukiwania po słowach kluczowych. Hybrid search łączy oba wyniki:
from rank_bm25 import BM25Okapi
import numpy as np
class HybridSearch:
"""Łączy semantic search z keyword search."""
def __init__(self, documents: list[str], embeddings: np.ndarray):
self.documents = documents
self.embeddings = embeddings
# BM25 dla keyword search
tokenized = [doc.lower().split() for doc in documents]
self.bm25 = BM25Okapi(tokenized)Konstruktor dzieli każdy dokument na słowa i buduje z nich indeks BM25Okapi, a embeddingi dostaje gotowe.
Metoda search normalizuje oba wyniki do zakresu 0-1 i miesza je z wagą alpha:
def search(
self,
query: str,
query_embedding: np.ndarray,
alpha: float = 0.5, # Waga semantic search
top_k: int = 5
) -> list[tuple[str, float]]:
"""Hybrid search z konfigurowalnymi wagami."""
# Semantic search scores
semantic_scores = np.dot(self.embeddings, query_embedding)
semantic_scores /= np.linalg.norm(self.embeddings, axis=1)
semantic_scores /= np.linalg.norm(query_embedding)
# Normalize to [0, 1]
semantic_scores = (semantic_scores - semantic_scores.min()) / (semantic_scores.max() - semantic_scores.min())
# BM25 scores
bm25_scores = np.array(self.bm25.get_scores(query.lower().split()))
if bm25_scores.max() > 0:
bm25_scores = bm25_scores / bm25_scores.max()
# Hybrid score
hybrid_scores = alpha * semantic_scores + (1 - alpha) * bm25_scores
# Top K
top_indices = np.argsort(hybrid_scores)[::-1][:top_k]
return [(self.documents[i], hybrid_scores[i]) for i in top_indices]alpha=1 to czyste wyszukiwanie semantyczne, alpha=0 czyste BM25. Polecam zacząć od 0.5 i stroić wagę na własnych pytaniach testowych.
Vector databases to infrastruktura każdego systemu RAG. Do prototypu bierz Chromę, na produkcję Qdrant albo Pinecone. W następnej lekcji poznasz LlamaIndex - framework, który upraszcza budowanie aplikacji RAG i podłącza się do tych baz jedną linijką.
Zapamiętaj: baza wektorowa to obozowe archiwum tropów, które po odcisku znajduje najbardziej podobne ślady.
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Która z poniższych to popularna vector database?
2. Co to jest Chroma w kontekście vector databases?
Zadania praktyczne w grze
- Układanie w poziomie
Ułóż elementy:
- Edytor kodu
Zaimplementuj dodawanie dokumentów do Chroma
- Układanie w poziomie
Ułóż elementy:
- Układanie w pionie
Ułóż kroki pracy z Qdrant w prawidłowej kolejności:
- Klikanie w kolejności
Ułóż dodawanie do bazy wektorowej:
- Układanie w pionie
Ułóż kroki tworzenia indeksu FAISS: