Przejdź do głównej treści
Polski— Wybierz język
Menu

Generuj osadzenia dla swoich danych

Lekcja 3 z 22 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Cele
  2. Przygotuj swoje dane
  3. Generuj osadzenia partiami
  4. Przechowuj osadzenia
  5. Kompletny potok: od plików tekstowych do osadzeń
  6. Oszacuj koszty
  7. Kluczowe wnioski

Cele

  • Przygotuj swoje dane tekstowe do generowania osadzeń
  • Efektywnie generuj osadzenia na dużą skalę
  • Przechowuj wektory do późniejszego wykorzystania

Przygotuj swoje dane

Jakość twoich osadzeń zależy bezpośrednio od jakości danych. Tekst pełen zbędnych spacji, znaków kontrolnych pochodzących z błędnie skonfigurowanego eksportu lub nieregularnych znaków końca linii generuje nieco przesunięty wektor. To przesunięcie kumuluje się przy każdym wyszukiwaniu. Czyszczenie danych to nie kosmetyka: to pierwsza i najtańsza optymalizacja trafności wyników.

import re

def nettoyer_texte(texte: str) -> str:
    """Prepares text for embedding."""
    # Remove multiple spaces
    texte = re.sub(r"\s+", " ", texte)
    # Remove control characters
    texte = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", texte)
    # Trim
    texte = texte.strip()
    return texte

# Example
brut = "  Texte   avec   des   espaces\n\n\nen trop  "
propre = nettoyer_texte(brut)
print(propre)  # "Texte avec des espaces en trop"

Wzbogać kontekst

Izolowany fragment dokumentacji traci część swojego znaczenia bez tytułu. Weź akapit zaczynający się od „Pobierz pakiet ze strony oficjalnej“: bez kontekstu nic nie wskazuje, że chodzi o PostgreSQL, a powstały wektor nigdy nie dopasuje się do zapytania dotyczącego PostgreSQL. Poprzez dodanie prefiksu z tytułem i sekcją wstrzykujesz te informacje z powrotem do tekstu, który widzi model.

def enrichir_document(titre: str, section: str, contenu: str) -> str:
    """Creates enriched text for better embedding."""
    return f"Titre : {titre}\nSection : {section}\n\n{contenu}"

texte_enrichi = enrichir_document(
    titre="Installation de PostgreSQL",
    section="Getting Started Guide",
    contenu="Download the package from the official site..."
)

Generuj osadzenia partiami

W przypadku rzeczywistego korpusu liczącego setki lub tysiące dokumentów przetwarzanie musi być podzielone na części i odporne na chwilowe problemy z siecią. Poniższa funkcja iteruje przez teksty w fragmentach, systematycznie sortuje odpowiedź według index, aby upewnić się, że wektor nr 7 odpowiada dokumentowi nr 7, i ponawia próbę raz po pauzie w przypadku wystąpienia błędu.

from openai import OpenAI
import time
import json

client = OpenAI()

def generer_embeddings(
    textes: list[str],
    model: str = "text-embedding-3-large",
    batch_size: int = 100
) -> list[list[float]]:
    """Generates embeddings in batches with error handling."""
    tous_les_embeddings = []

    for i in range(0, len(textes), batch_size):
        batch = textes[i:i + batch_size]
        print(f"Processing batch {i // batch_size + 1}/"
              f"{(len(textes) - 1) // batch_size + 1}")

        try:
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            # Sort by index to guarantee order
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )
        except Exception as e:
            print(f"Error on batch {i}: {e}")
            # Retry after a pause
            time.sleep(5)
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )

    return tous_les_embeddings

Sortowanie według index to środek ostrożności, którego nigdy nie wolno pomijać. Ciche przesunięcie o jeden wiersz wystarczy, aby powiązać każdy dokument z wektorem sąsiada. Objawem, jaki zaobserwujesz, będzie „wyszukiwanie zwracające śmieci“, bez żadnego błędu technicznego, który wskazałby właściwy kierunek rozwiązywania problemu.

Przechowuj osadzenia

Dla małego korpusu liczącego kilka tysięcy dokumentów prosty plik JSON zawierający teksty, metadane i wektory sprawdza się doskonale. Ma tę zaletę, że jest czytelny dla człowieka, gdy trzeba zdebugować dziwny wynik.

import json

documents = [
    {"id": 1, "texte": "Premier document...", "metadata": {"source": "faq"}},
    {"id": 2, "texte": "Deuxième document...", "metadata": {"source": "docs"}},
]

# Generate embeddings
textes = [d["texte"] for d in documents]
embeddings = generer_embeddings(textes)

# Add vectors to documents
for doc, emb in zip(documents, embeddings):
    doc["embedding"] = emb

# Save
with open("corpus_embeddings.json", "w") as f:
    json.dump(documents, f)

Powyżej tej skali JSON staje się wąskim gardłem: każda liczba jest zapisywana w pełnej postaci, co rozdyma plik i narzuca kosztowne parsowanie przy każdym ładowaniu. NumPy przechowuje te same wartości w formacie binarnym na 4 bajtach i ładuje je natychmiastowo.

import numpy as np

# Convert to NumPy matrix
matrice = np.array(embeddings, dtype=np.float32)
print(f"Shape : {matrice.shape}")  # (n_docs, 3072)

# Save in binary format
np.save("embeddings.npy", matrice)

# Load
matrice_chargee = np.load("embeddings.npy")

Kompletny potok: od plików tekstowych do osadzeń

Połączmy te elementy w funkcji, która odczytuje folder, czyści każdy plik, generuje wektory i dzieli przechowywanie na dwie części: metadane w JSON (czytelne i edytowalne) oraz macierz w NumPy (kompaktowa i szybka).

from openai import OpenAI
from pathlib import Path
import json
import numpy as np

client = OpenAI()

def pipeline_embeddings(dossier: str, model: str = "text-embedding-3-large"):
    """Complete pipeline: files → embeddings → storage."""
    dossier_path = Path(dossier)

    # 1. Read files
    documents = []
    for fichier in sorted(dossier_path.glob("*.txt")):
        contenu = fichier.read_text(encoding="utf-8")
        contenu = nettoyer_texte(contenu)
        if contenu:
            documents.append({
                "id": fichier.stem,
                "fichier": fichier.name,
                "texte": contenu
            })

    print(f"{len(documents)} documents found")

    # 2. Generate embeddings
    textes = [d["texte"] for d in documents]
    embeddings = generer_embeddings(textes, model=model)

    # 3. Save
    # Metadata in JSON
    meta = [{"id": d["id"], "fichier": d["fichier"]} for d in documents]
    with open("metadata.json", "w") as f:
        json.dump(meta, f, ensure_ascii=False, indent=2)

    # Vectors in NumPy
    np.save("embeddings.npy", np.array(embeddings, dtype=np.float32))

    print(f"Embeddings saved: {len(embeddings)} vectors "
          f"of {len(embeddings[0])} dimensions")

    return documents, embeddings

# Usage
documents, embeddings = pipeline_embeddings("./mes_documents/")

Zwróć uwagę na sorted() przy glob: bez niego kolejność plików zależy od systemu plików, a dwa pliki wyjściowe ryzykują roz synchronizowanie się po zwykłej zmianie maszyny.

Oszacuj koszty

Przed uruchomieniem masowego zadania policz tokeny lokalnie za pomocą tiktoken. Operacja zajmuje kilka sekund i uchroni cię przed odkryciem zbyt późno, że źle przefiltrowany korpus zawierał dziesięciokrotnie większą objętość niż oczekiwano.

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

def estimer_cout(textes: list[str], model: str = "text-embedding-3-large"):
    """Estimates embedding cost for a list of texts."""
    total_tokens = sum(len(encoder.encode(t)) for t in textes)

    # Approximate prices per million tokens (check current rates)
    prix = {
        "text-embedding-3-large": 0.13,
        "text-embedding-3-small": 0.02,
    }

    cout = total_tokens / 1_000_000 * prix.get(model, 0.13)
    print(f"Estimated tokens: {total_tokens:,}")
    print(f"Estimated cost: ${cout:.4f}")
    return total_tokens, cout

Ceny w słowniku są orientacyjne i szybko się dezaktualizują: zawsze sprawdzaj aktualne stawki przed przedstawieniem wyceny klientowi.

Kluczowe wnioski

  • Czyść i wzbogacaj swoje teksty przed generowaniem osadzeń
  • Używaj przetwarzania wsadowego dla dużych korpusów
  • Przechowuj metadane w JSON, a wektory w NumPy
  • Oszacuj koszty przed uruchomieniem masowego zadania