L'API Embeddings: Modelli e Dimensioni
In questa pagina
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.
| Dimensions | Relative Quality | Storage | Use Case |
|---|---|---|---|
| 3,072 | 100% | ~24 KB | High-precision search |
| 1,536 | ~98% | ~12 KB | Good general compromise |
| 512 | ~93% | ~4 KB | High volume, reduced cost |
| 256 | ~88% | ~2 KB | Prototyping, 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
dimensionsti 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