Se hai letto i miei articoli su cosa sono gli embedding e su come si creano, sai già che un embedding è una lista di numeri che rappresenta il significato di un testo. Questo articolo risponde a due domande pratiche: come si usano davvero le API di embedding di OpenAI e perché un software come OpenClaw, che gestisce il mio assistente personale, ne ha bisogno ogni giorno.
Di cosa parleremo..
Cos’è un embedding, in una frase
Un embedding è una sequenza di numeri che cattura il significato di un testo. Testi simili producono sequenze simili, testi diversi producono sequenze lontane. È questo che permette a un computer di confrontare frasi in modo intelligente, senza limitarsi a cercare parole identiche.
Come funzionano le API di OpenAI
Le API di OpenAI per gli embedding sono tra le più semplici da usare: si invia un testo e si riceve il vettore corrispondente. La chiamata è una singola richiesta HTTP all’endpoint /v1/embeddings, con il testo da convertire e il nome del modello. La risposta contiene il vettore, cioè la lista di numeri, insieme al conteggio dei token consumati, perché la fatturazione avviene per token di input.
OpenAI offre due modelli di terza generazione. text-embedding-3-small produce vettori da 1536 numeri ed è veloce ed economico. text-embedding-3-large produce vettori da 3072 numeri ed è più preciso. Entrambi accettano fino a 8192 token per richiesta.
Un dettaglio interessante: con il parametro dimensions si può chiedere un vettore più corto, per esempio da 256 numeri, risparmiando spazio e costi. Un text-embedding-3-large ridotto a 256 dimensioni supera ancora il vecchio modello ada-002 con i suoi 1536.
Quanto costa
Il prezzo è per token di input. text-embedding-3-small costa 0,00002 dollari per 1000 token, circa 62.500 pagine di testo per ogni dollaro speso. text-embedding-3-large costa 0,00013 dollari per 1000 token, circa 9.615 pagine per dollaro. Rispetto al vecchio text-embedding-ada-002, il modello small costa cinque volte meno e rende di più.
Cosa ci fai con un embedding
Gli embedding sono la base di tante applicazioni: ricerca semantica, raggruppamento di testi simili, classificazione, raccomandazioni e rilevamento di anomalie. Sono anche il cuore del RAG, la tecnica che permette a un assistente di rispondere usando documenti reali: i documenti vengono trasformati in vettori, salvati in un database vettoriale e confrontati con la domanda. Se vuoi un esempio pratico, ho scritto una guida al RAG domestico.
Perché OpenClaw usa gli embedding
OpenClaw è il software che gestisce il mio assistente personale. Un assistente che si rispetti deve ricordare: progetti, preferenze, conversazioni passate. La memoria di OpenClaw è fatta di file di testo, come MEMORY.md e gli appunti giornalieri, e per trovare il ricordo giusto usa proprio gli embedding.
Il meccanismo è identico a quello delle API descritte sopra. La memoria viene spezzettata in pezzi piccoli, ogni pezzo viene trasformato in un vettore e salvato in un indice locale. Quando arriva una domanda, anche quella viene trasformata in vettore e OpenClaw cerca i pezzi più vicini. Il risultato è che posso chiedere come va il progetto del sito e l’assistente ritrova gli appunti sulla pubblicazione degli articoli, anche se la parola esatta non compare in nessuno di quei file.
La ricerca non usa solo i vettori: OpenClaw combina la ricerca per significato con una ricerca per parole chiave, il cosiddetto BM25. I vettori catturano i sinonimi e i concetti, le parole chiave trovano con precisione nomi, codici ed errori. Le due strade si coprono a vicenda.
Ci sono poi due accorgimenti intelligenti. Il primo è il decadimento temporale: gli appunti datati perdono gradualmente peso, così i ricordi recenti contano più di quelli vecchi, mentre i file principali come MEMORY.md restano sempre rilevanti. Il secondo è la cache: gli embedding già calcolati vengono riusati, quindi non si rifà il lavoro a ogni domanda.
Il dietro le quinte: dove vivono gli embedding
Fin qui ho parlato di come si generano gli embedding, ma non di dove finiscono. La parte più affascinante, per chi vuole capire come funzionano davvero, è questa: gli embedding si salvano, non si ricalcolano.
OpenClaw non rigenera i vettori a ogni domanda. La memoria viene indicizzata una volta sola: i file vengono spezzati in pezzi piccoli, ogni pezzo viene trasformato in un vettore e tutto viene salvato in un unico file locale, un database SQLite. Quando arriva una domanda, viene convertito in vettore solo il testo della domanda, e quel vettore viene confrontato con quelli già salvati. È come l’indice di un libro: lo costruisci una volta, poi ogni ricerca è una semplice consultazione. Ricalcolare tutti gli embedding a ogni domanda sarebbe come ristampare l’intero libro per cercare una parola.
Se poi modifico un appunto, non si rifà tutto: vengono aggiornati solo i pezzi cambiati, grazie a una cache che evita di riconvertire il testo rimasto identico. Il lavoro pesante si fa una volta, le consultazioni successive costano quasi nulla.
Perché un file e non un database vettoriale dedicato
Esistono database fatti apposta per i vettori, come Qdrant, Pinecone o Milvus. Sono strumenti potenti, ma pensati per chi gestisce milioni o miliardi di vettori, con più utenti e più macchine. Per un uso personale sono come affittare un ufficio con server room quando ti serve un quaderno.
Un database SQLite, invece, è un semplice file: niente server da installare, niente processi da tenere accesi. Testo, vettori, indice per parole chiave e cache vivono tutti nello stesso file. Backup? Copi il file. E la ricerca può essere ibrida: i vettori trovano i sinonimi e i concetti, l’indice per parole chiave trova con precisione nomi e codici. Due motori di ricerca in un unico file.
FAQ
Un embedding e un modello che genera testo sono la stessa cosa?
No. Un modello come GPT genera testo, un embedding produce una lista di numeri che rappresenta il significato. Sono strumenti complementari: gli embedding trovano le informazioni giuste, il modello le trasforma in risposta. Nel RAG lavorano insieme.
Devo usare per forza le API di OpenAI?
No. Esistono molti fornitori di embedding, anche gratuiti o locali. OpenClaw, per esempio, permette di cambiarli in base alle esigenze di costo e privacy.
Quanto testo posso convertire in una volta?
Ogni richiesta accetta fino a 8192 token, circa 6000 parole. Per testi più lunghi si divide il contenuto in pezzi e si genera un vettore per ogni pezzo, come fa OpenClaw con la memoria.
Gli embedding funzionano anche in italiano?
Sì. I modelli di OpenAI gestiscono molte lingue e i benchmark multilingua come MIRACL mostrano un netto miglioramento rispetto al passato: text-embedding-3-large passa dal 31,4% del vecchio ada-002 al 54,9%.
