Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Genera embedding per i tuoi dati

Lezione 3 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Prepara i tuoi dati
  3. Genera embedding in batch
  4. Archivia gli embedding
  5. Pipeline completa: dai file di testo agli embedding
  6. Stima i costi
  7. Punti chiave

Obiettivi

  • Preparare i dati testuali per la generazione degli embedding
  • Generare embedding in modo efficiente su larga scala
  • Archiviare i vettori per un utilizzo successivo

Prepara i tuoi dati

La qualità dei tuoi embedding dipende direttamente dalla qualità dei tuoi dati. Un testo pieno di spazi superflui, caratteri di controllo derivanti da un’esportazione mal configurata o interruzioni di riga erratiche produce un vettore leggermente impreciso. Questo scarto si accumula a ogni ricerca. La pulizia non è cosmetica: è la prima e più economica ottimizzazione della rilevanza.

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"

Arricchisci il contesto

Un estratto di documentazione isolato perde parte del suo significato senza il titolo. Prendi un paragrafo che inizia con «Scarica il pacchetto dal sito ufficiale»: fuori contesto, nulla indica che si riferisca a PostgreSQL e il vettore risultante non corrisponderà mai a una query su PostgreSQL. Prefissando il contenuto con il suo titolo e la sua sezione, reinietti queste informazioni nel testo che il modello vede.

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..."
)

Genera embedding in batch

Su un corpus reale di centinaia o migliaia di documenti, l’elaborazione deve essere suddivisa in blocchi e resiliente ai problemi di rete. La funzione seguente itera sui testi a fette, ordina sistematicamente la risposta per index per garantire che il vettore #7 corrisponda al documento #7 e riprova una volta dopo una pausa in caso di errore.

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

Ordinare per index è una precauzione che non devi mai saltare. Uno spostamento silenzioso di una riga è sufficiente ad associare ogni documento al vettore del suo vicino. Il sintomo che osserverai è «la ricerca restituisce spazzatura», senza alcun errore tecnico che ti indichi la direzione giusta.

Archivia gli embedding

Per un piccolo corpus di qualche migliaio di documenti, un semplice file JSON contenente testi, metadati e vettori funziona perfettamente. Ha il vantaggio di essere leggibile dall’uomo quando devi debuggare un risultato strano.

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)

Oltre quella scala, il JSON diventa un collo di bottiglia: ogni numero viene scritto per esteso, gonfiando il file e imponendo un parsing costoso a ogni caricamento. NumPy archivia gli stessi valori in binario su 4 byte e si ricarica istantaneamente.

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")

Pipeline completa: dai file di testo agli embedding

Mettiamo insieme questi elementi in una funzione che legge una cartella, pulisce ogni file, genera i vettori e divide l’archiviazione in due: metadati in JSON (leggibili e modificabili) e matrice in NumPy (compatta e veloce).

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/")

Nota l’uso di sorted() sul glob: senza di esso, l’ordine dei file dipende dal filesystem e i tuoi due file di output rischiano di andare fuori sincrono dopo un semplice cambio macchina.

Stima i costi

Prima di lanciare un lavoro massiccio, conta i token localmente con tiktoken. L’operazione richiede pochi secondi e ti evita di scoprire troppo tardi che un corpus filtrato male conteneva dieci volte il volume previsto.

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

I prezzi nel dizionario sono indicativi e invecchiano rapidamente: controlla sempre le tariffe attuali prima di presentare un preventivo a un cliente.

Punti chiave

  • Pulisci e arricchisci i tuoi testi prima di generare gli embedding
  • Usa l’elaborazione in batch per grandi corpus
  • Archivia i metadati in JSON e i vettori in NumPy
  • Stima i costi prima di lanciare un lavoro massiccio