Kurs Python · Moduł 11: RAG i systemy wieloagentowe

Vector Databases

8 min czytania ·
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 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.points

Uwaga 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 results

Mniejsza 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. 1. Która z poniższych to popularna vector database?

  2. 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:

  1. PytanieVector Database
  2. PytanieChroma DB
  3. Ułóż w kolejnościImport ChromaDB
  4. Zadanie z kodemChroma Collection
  5. Ułóż w kolejnościChroma query
  6. Ułóż w kolejnościQdrant workflow
  7. Kliknij w kolejnościVector Store Add
  8. Ułóż w kolejnościFAISS Index

Przydatne artykuły