Kurs Python · Moduł 11: RAG i systemy wieloagentowe

Embeddings i Vector Search

7 min czytania ·
W tej lekcji5

Użytkownik pyta: "gdzie odpoczywają koty?", a w notatniku masz zdanie "Kotek leży na dywanie". Wyszukiwanie po słowach kluczowych nie znajdzie tu żadnego wspólnego wyrazu, choć sens jest prawie ten sam. Potrzebujemy sposobu, żeby porównywać znaczenie, a nie litery. Tym sposobem są embeddings.

Embeddings to wektorowe reprezentacje tekstu, które pozwalają maszynom "rozumieć" znaczenie słów i zdań. Myśl o nich jak o odcisku tropu: każde zwierzę zostawia inny ślad, a tropiciel po kształcie odcisku pozna, kto przeszedł szlakiem. Embedding to taki odcisk tekstu - sekwencja liczb, która opisuje jego semantykę.

Czym są embeddings?

Embedding to wektor liczb rzeczywistych reprezentujący tekst w przestrzeni semantycznej. Teksty o podobnym znaczeniu dostają wektory leżące blisko siebie. Najprościej wygenerować go przez API OpenAI, metodą client.embeddings.create:

from openai import OpenAI

client = OpenAI()

def get_embedding(text: str, model: str = "text-embedding-3-small") -> list[float]:
    """Generuje embedding dla podanego tekstu."""
    response = client.embeddings.create(
        model=model,
        input=text
    )
    return response.data[0].embedding

# Przykład
text = "Python to świetny język programowania"
embedding = get_embedding(text)

print(f"Wymiar wektora: {len(embedding)}")  # 1536 dla text-embedding-3-small
print(f"Pierwsze 5 wartości: {embedding[:5]}")

Funkcja zwraca zwykłą listę floatów. Model text-embedding-3-small domyślnie daje wektory o 1536 wymiarach, a text-embedding-3-large 3072. Sam tekst nigdzie się nie zapisuje, dostajemy tylko jego liczbowy odcisk. Cały proces zawsze ma ten sam rytm: przygotuj tekst, wyślij go do modelu embeddingów, odbierz wektor i zapisz go w bazie wektorowej.

Modele embeddingów

Nie każdy obóz ma budżet na płatne API. Biblioteka sentence-transformers uruchamia modele open-source lokalnie, na Twoim komputerze. Poniższa klasa zbiera w jednym miejscu model lokalny i model OpenAI:

from sentence_transformers import SentenceTransformer

# Modele open-source
class EmbeddingModels:
    """Różne modele embeddingów."""

    def __init__(self):
        # Szybki i lekki
        self.minilm = SentenceTransformer('all-MiniLM-L6-v2')

        # Większy, lepszy dla polskiego
        self.multilingual = SentenceTransformer('paraphrase-multilingual-mpnet-base-v2')

    def embed_with_openai(self, texts: list[str]) -> list[list[float]]:
        """OpenAI embeddings - najwyższa jakość."""
        from openai import OpenAI
        client = OpenAI()

        response = client.embeddings.create(
            model="text-embedding-3-large",  # 3072 wymiarów
            input=texts
        )
        return [item.embedding for item in response.data]

    def embed_with_sentence_transformers(self, texts: list[str]) -> list[list[float]]:
        """Lokalne embeddings - bez kosztów API."""
        return self.minilm.encode(texts).tolist()

all-MiniLM-L6-v2 jest szybki i lekki (384 wymiary), paraphrase-multilingual-mpnet-base-v2 jest większy i radzi sobie z wieloma językami, także z polskim. Metoda encode zwraca tablicę NumPy, dlatego wołamy .tolist().

Teraz porównajmy teksty w dwóch językach i jedno zdanie zupełnie z innej bajki:

# Porównanie modeli
models = EmbeddingModels()

texts = [
    "Uczenie maszynowe to dziedzina AI",
    "Machine learning is a field of AI",
    "Lubię jeść pizzę"
]

# Open-source embeddings
embeddings = models.embed_with_sentence_transformers(texts)
print(f"Lokalne embeddings: {len(embeddings[0])} wymiarów")

Wynik pokaże 384 wymiary. Zwróć uwagę, że wymiar zależy od modelu, a nie od długości tekstu: krótkie zdanie i długi akapit dostają wektory tej samej długości.

Metryki podobieństwa

Mamy wektory, więc trzeba je porównać. Oto trzy najpopularniejsze miary, każda w jednej linijce NumPy:

import numpy as np
from typing import Callable

def cosine_similarity(vec1: np.ndarray, vec2: np.ndarray) -> float:
    """Podobieństwo kosinusowe - najczęściej używane."""
    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

def euclidean_distance(vec1: np.ndarray, vec2: np.ndarray) -> float:
    """Odległość euklidesowa."""
    return np.linalg.norm(vec1 - vec2)

def dot_product(vec1: np.ndarray, vec2: np.ndarray) -> float:
    """Iloczyn skalarny."""
    return np.dot(vec1, vec2)

Podobieństwo kosinusowe patrzy tylko na kąt między wektorami i to ono jest najczęściej używane do porównywania embeddingów. Odległość euklidesowa mierzy dystans, więc tu mniejsza liczba oznacza większe podobieństwo. Iloczyn skalarny zależy i od kąta, i od długości wektorów.

Sprawdźmy to na trzech zdaniach, z których dwa mówią o kotach:

# Demonstracja
def demonstrate_similarity():
    """Pokazuje jak działają metryki podobieństwa."""
    from sentence_transformers import SentenceTransformer

    model = SentenceTransformer('all-MiniLM-L6-v2')

    sentences = [
        "Kot siedzi na macie",           # 0
        "Kotek leży na dywanie",         # 1 - podobne znaczenie
        "Programowanie w Pythonie",       # 2 - inne znaczenie
    ]

    embeddings = model.encode(sentences)

    print("Podobieństwo kosinusowe:")
    print(f"  Zdanie 0 vs 1: {cosine_similarity(embeddings[0], embeddings[1]):.3f}")
    print(f"  Zdanie 0 vs 2: {cosine_similarity(embeddings[0], embeddings[2]):.3f}")
    print(f"  Zdanie 1 vs 2: {cosine_similarity(embeddings[1], embeddings[2]):.3f}")

demonstrate_similarity()

Para zdań 0 i 1 powinna dostać wyraźnie wyższy wynik niż pary ze zdaniem o Pythonie, mimo że "Kot" i "Kotek" to różne słowa. Dokładnych liczb nie wpisuję, bo zależą od wersji modelu.

Jeszcze jedna przydatna opcja. Jeśli poprosisz model o znormalizowane wektory (długość równa 1), iloczyn skalarny staje się dokładnie podobieństwem kosinusowym:

from sentence_transformers import SentenceTransformer

model = SentenceTransformer('all-MiniLM-L6-v2')
document_text = "Lwy polują najczęściej o zmierzchu"

# Wektor o długości 1 - iloczyn skalarny od razu daje podobieństwo kosinusowe
embedding = model.encode(document_text, normalize_embeddings=True)
print(embedding.shape)  # (384,)

Parametr nazywa się normalize_embeddings, a pojedynczy string daje jednowymiarową tablicę. Treść wektora wskazuje ten sam kierunek co bez normalizacji, zmienia się tylko jego długość.

Złóżmy te klocki w wyszukiwarkę semantyczną. Najpierw mały kontener na wynik, zrobiony dekoratorem @dataclass, i klasa, która raz indeksuje dokumenty:

from dataclasses import dataclass
import numpy as np

@dataclass
class SearchResult:
    """Wynik wyszukiwania semantycznego."""
    text: str
    score: float
    index: int

class SemanticSearch:
    """Prosta implementacja wyszukiwania semantycznego."""

    def __init__(self, model_name: str = 'all-MiniLM-L6-v2'):
        from sentence_transformers import SentenceTransformer
        self.model = SentenceTransformer(model_name)
        self.documents: list[str] = []
        self.embeddings: np.ndarray | None = None

    def index_documents(self, documents: list[str]) -> None:
        """Indeksuje dokumenty."""
        self.documents = documents
        self.embeddings = self.model.encode(documents)
        print(f"Zaindeksowano {len(documents)} dokumentów")

index_documents liczy embeddingi wszystkich dokumentów jednym wywołaniem encode i trzyma je w macierzy. To odpowiedź na słabość z poprzedniej lekcji: dokumenty embedujemy raz, a nie przy każdym pytaniu.

Metoda search liczy podobieństwo pytania do całej macierzy naraz, bez pętli:

    def search(self, query: str, top_k: int = 5) -> list[SearchResult]:
        """Wyszukuje najbardziej podobne dokumenty."""
        if self.embeddings is None:
            raise ValueError("Brak zaindeksowanych dokumentów!")

        query_embedding = self.model.encode([query])[0]

        # Oblicz podobieństwa
        similarities = np.dot(self.embeddings, query_embedding)
        similarities /= np.linalg.norm(self.embeddings, axis=1)
        similarities /= np.linalg.norm(query_embedding)

        # Top-K wyników
        top_indices = np.argsort(similarities)[::-1][:top_k]

        results = []
        for idx in top_indices:
            results.append(SearchResult(
                text=self.documents[idx],
                score=float(similarities[idx]),
                index=int(idx)
            ))

        return results

np.argsort sortuje rosnąco, więc [::-1] odwraca kolejność, a [:top_k] bierze najlepsze wyniki. Dwa dzielenia przez normy zamieniają iloczyn skalarny w podobieństwo kosinusowe.

Pora na test na pięciu dokumentach:

# Przykład użycia
search = SemanticSearch()

documents = [
    "Python jest językiem programowania ogólnego przeznaczenia",
    "Machine Learning wykorzystuje algorytmy do uczenia się z danych",
    "RAG łączy wyszukiwanie z generowaniem tekstu",
    "FastAPI to nowoczesny framework do budowania API",
    "Docker konteneryzuje aplikacje",
]

search.index_documents(documents)

results = search.search("Jak budować aplikacje webowe?")
for r in results:
    print(f"Score: {r.score:.3f} | {r.text}")

Na pytanie o aplikacje webowe najwyżej powinien wypaść dokument o FastAPI, choć nie dzieli z pytaniem ani jednego słowa kluczowego.

Batch Processing

Tysiąc dokumentów wysyłanych pojedynczo to tysiąc zapytań HTTP. API OpenAI przyjmuje listę tekstów w parametrze input, więc wysyłamy je partiami:

def batch_embed(texts: list[str], batch_size: int = 100) -> list[list[float]]:
    """Embedowanie dużej ilości tekstów w partiach."""
    from openai import OpenAI
    client = OpenAI()

    all_embeddings = []

    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]

        response = client.embeddings.create(
            model="text-embedding-3-small",
            input=batch
        )

        batch_embeddings = [item.embedding for item in response.data]
        all_embeddings.extend(batch_embeddings)

        print(f"Przetworzono {min(i + batch_size, len(texts))}/{len(texts)}")

    return all_embeddings

Kolejność wyników w response.data odpowiada kolejności tekstów w partii, dlatego możemy po prostu doklejać je przez extend.

Drugi sposób na oszczędność to cache. Ten sam tekst i ten sam model zawsze dają ten sam embedding, więc zapisujemy wynik na dysku pod kluczem z hasha:

# Cache'owanie embeddingów
import hashlib
import json
from pathlib import Path

class EmbeddingCache:
    """Cache dla embeddingów."""

    def __init__(self, cache_dir: str = ".embedding_cache"):
        self.cache_dir = Path(cache_dir)
        self.cache_dir.mkdir(exist_ok=True)

    def _get_cache_key(self, text: str, model: str) -> str:
        """Generuje klucz cache."""
        content = f"{model}:{text}"
        return hashlib.md5(content.encode()).hexdigest()

    def get(self, text: str, model: str) -> list[float] | None:
        """Pobiera embedding z cache."""
        key = self._get_cache_key(text, model)
        cache_file = self.cache_dir / f"{key}.json"

        if cache_file.exists():
            return json.loads(cache_file.read_text())
        return None

    def set(self, text: str, model: str, embedding: list[float]) -> None:
        """Zapisuje embedding do cache."""
        key = self._get_cache_key(text, model)
        cache_file = self.cache_dir / f"{key}.json"
        cache_file.write_text(json.dumps(embedding))

MD5 służy tu wyłącznie jako szybki identyfikator pliku, nie jako zabezpieczenie, więc jego słabości kryptograficzne nie mają znaczenia. Model jest częścią klucza celowo: po zmianie modelu stare wektory nie pasują do nowych. Polecam cache'ować embeddingi od pierwszego dnia, bo przy ponownym indeksowaniu oszczędza to i czas, i pieniądze.

Embeddings to fundament każdego systemu RAG. W następnej lekcji poznasz vector databases - specjalizowane bazy danych do przechowywania i wyszukiwania wektorów - które robią to, co nasza macierz NumPy, ale dla milionów dokumentów.

Zapamiętaj: embedding to odcisk tropu tekstu, a podobne znaczenia zostawiają 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. Czym jest embedding w kontekście NLP?

  2. 2. Która metryka jest najczęściej używana do porównywania embeddingów?

Zadania praktyczne w grze

  • Edytor kodu

    Napisz funkcję cosine_similarity

  • Układanie w pionie

    Uporządkuj kroki:

  • Układanie w poziomie

    Ułóż wywołanie metody tworzenia embeddingu:

  • Klikanie w kolejności

    Ułóż wywołanie embeddingu:

  1. PytanieEmbeddings
  2. PytaniePodobieństwo wektorów
  3. Zadanie z kodemCosine Similarity
  4. Ułóż w kolejnościPipeline embeddingów
  5. Ułóż w kolejnościWywołanie OpenAI Embeddings
  6. Kliknij w kolejnościEmbedding Call

Przydatne artykuły