Kurs Python · Moduł 11: RAG i systemy wieloagentowe
Embeddings i Vector Search
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ść.
Semantic Search
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 resultsnp.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_embeddingsKolejność 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. Czym jest embedding w kontekście NLP?
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: