Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'API Embeddings: Modelli e Dimensioni

Lezione 2 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. La Chiamata di Base
  3. I Due Modelli Disponibili
  4. Embedding in Batch
  5. Riduzione della Dimensionalità
  6. Gestione dei Token
  7. Punti chiave

Obiettivi

  • Padroneggiare la chiamata client.embeddings.create()
  • Comprendere le differenze tra i modelli di embedding
  • Utilizzare la riduzione della dimensionalità

La Chiamata di Base

Tutta l’API Embeddings di OpenAI si riduce a un singolo metodo: client.embeddings.create(). Gli passi una stringa di testo e il nome di un modello:

from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    input="Hello, how are you?",
    model="text-embedding-3-large"
)

embedding = response.data[0].embedding
print(f"Type: {type(embedding)}")        # list
print(f"Length: {len(embedding)}")      # 3072
print(f"Snippet: {embedding[:3]}")        # [0.023, -0.041, 0.012]

L’oggetto restituito non è il vettore stesso, ma un wrapper che contiene più vettori, poiché l’API è progettata per gestire batch. Al suo interno trovi data, una lista di oggetti dove ciascuno ha un campo embedding (il vettore) e un campo index (la sua posizione nel batch inviato); model, il modello effettivamente utilizzato; e usage.prompt_tokens, il numero di token fatturati. Dovresti registrare quest’ultimo campo fin dal primo giorno: è l’unica misura affidabile di quanto ti costa l’indicizzazione.

I Due Modelli Disponibili

text-embedding-3-large è il modello ad alte prestazioni. Le sue 3.072 dimensioni catturano le sfumature semantiche più fini, rendendolo ideale per la ricerca su grandi corpora, pipeline RAG esigenti e, in generale, qualsiasi caso in cui la precisione prevale sul costo. Se un utente formula domande in modo indiretto o i tuoi documenti coprono un dominio tecnico denso, noterai la differenza nel ranking dei risultati.

text-embedding-3-small è più compatto con 1.536 dimensioni e offre un eccellente rapporto prezzo-prestazioni. È la scelta giusta per la classificazione del testo, i sistemi di raccomandazione, il prototipaggio rapido e le applicazioni ad alto volume dove l’obiettivo non è distinguere tra due documenti quasi identici, ma separare temi chiaramente distinti. Un semplice ciclo verifica cosa restituisce ciascuno:

# Confronta i due modelli
for model_name in ["text-embedding-3-small", "text-embedding-3-large"]:
    resp = client.embeddings.create(
        input="Artificial intelligence",
        model=model_name
    )
    vec = resp.data[0].embedding
    print(f"{model_name}: {len(vec)} dimensions")

Embedding in Batch

Non indicizzi un corpus reale un testo alla volta: ogni chiamata HTTP costa un round-trip di rete e elaborare mille documenti individualmente significa accumulare mille latenze. L’API accetta fino a 2.048 testi in una singola chiamata e il campo index ti permette di mappare ogni vettore al documento corretto.

texts = [
    "Machine learning is advancing rapidly",
    "Deep learning is revolutionizing computer vision",
    "Vector databases store embeddings",
    "Python is the preferred language for data scientists"
]

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

for item in response.data:
    print(f"Text {item.index}: vector of {len(item.embedding)} dimensions")

print(f"Tokens consumed: {response.usage.prompt_tokens}")

In pratica, raggruppa i tuoi testi in batch da 100 a 2.048 a seconda del tuo volume: batch più piccoli rendono il recupero dopo i guasti più semplice, mentre quelli più grandi riducono il numero di chiamate. Monitora usage.prompt_tokens a ogni iterazione per stimare i costi man mano che procedi, invece di scoprirli sulla fattura, e implementa retry con backoff esponenziale: il superamento del rate limit è un errore transitorio, non un motivo per interrompere un lavoro di indicizzazione di tre ore.

Riduzione della Dimensionalità

I modelli text-embedding-3-* accettano un parametro dimensions che restituisce vettori più corti della loro dimensione nativa:

# Vettore completo: 3072 dimensioni
full = client.embeddings.create(
    input="Reduction test",
    model="text-embedding-3-large"
)

# Vettore ridotto: 256 dimensioni
reduced = client.embeddings.create(
    input="Reduction test",
    model="text-embedding-3-large",
    dimensions=256
)

print(f"Full: {len(full.data[0].embedding)} dim")    # 3072
print(f"Reduced: {len(reduced.data[0].embedding)} dim")  # 256

Il meccanismo è semplice: la riduzione tronca il vettore e poi lo rinormalizza. Poiché le prime dimensioni trasportano la maggior parte delle informazioni, il degrado rimane molto graduale. La tabella seguente fornisce benchmark standard per bilanciare qualità e storage.

DimensionsRelative QualityStorageUse Case
3,072100%~24 KBHigh-precision search
1,536~98%~12 KBGood general compromise
512~93%~4 KBHigh volume, reduced cost
256~88%~2 KBPrototyping, simple classification

Ricorda che la scelta delle dimensioni ti impegna: tutti i vettori in un dato indice devono avere la stessa dimensione e cambiare idea richiede di ricalcolare tutto.

Gestione dei Token

I modelli di embedding hanno un limite di 8.191 token per testo e l’API restituisce un errore se lo superi. È meglio misurare prima di inviare piuttosto che gestire un’eccezione nel mezzo di un batch:

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

text = "A potentially long text..."
tokens = encoder.encode(text)

if len(tokens) > 8191:
    # Tronca
    truncated_text = encoder.decode(tokens[:8191])
    print(f"Text truncated from {len(tokens)} to 8191 tokens")

Il troncamento è una rete di sicurezza, non una strategia: un documento lungo troncato perde la sua parte finale, e spesso è proprio la fine a contenere la risposta che cerchi. La gestione corretta dei documenti di grandi dimensioni prevede il chunking, che affronteremo più avanti nel corso.

Punti chiave

  • client.embeddings.create() accetta un singolo testo o una lista di testi
  • Usa text-embedding-3-large (3.072 dim) per la precisione, text-embedding-3-small (1.536 dim) per l’efficienza dei costi
  • Il parametro dimensions ti permette di ridurre la dimensione del vettore
  • L’invio di testi in batch è più efficiente delle chiamate individuali
  • Limite di 8.191 token per testo