--- title: Embedding url: https://platform.claude.com/docs/it/build-with-claude/embeddings description: Gli embedding di testo sono rappresentazioni numeriche del testo che consentono di misurare la similarità semantica. Questa guida introduce gli embedding, le loro applicazioni e come utilizzare i modelli di embedding per attività come ricerca, raccomandazioni e rilevamento di anomalie. --- ## Prima di implementare gli embedding Quando selezioni un fornitore di embedding, ci sono diversi fattori che puoi considerare in base alle tue esigenze e preferenze: * Dimensione del dataset e specificità di dominio: dimensione del dataset di addestramento del modello e sua rilevanza rispetto al dominio di cui vuoi creare gli embedding. Dati più ampi o più specifici per il dominio producono generalmente embedding migliori all'interno del dominio * Prestazioni di inferenza: velocità di ricerca degli embedding e "latency" (latenza) end-to-end. Questa è una considerazione particolarmente importante per deployment di produzione su larga scala * Personalizzazione: opzioni per l'addestramento continuato su dati privati o la specializzazione dei modelli per domini molto specifici. Questo può migliorare le prestazioni su vocabolari unici ## Come ottenere embedding con Anthropic Anthropic non offre un proprio modello di embedding. Un fornitore di embedding con un'ampia varietà di modelli e funzionalità è Voyage AI di MongoDB. Voyage AI realizza modelli di embedding e "rerankers" (modelli di riordinamento). I suoi modelli di embedding includono modelli generici, multimodali, contestualizzati e specifici per dominio. Il resto di questa guida riguarda Voyage AI, ma dovresti valutare diversi fornitori di embedding per trovare quello più adatto al tuo caso d'uso specifico. ## Modelli disponibili Voyage AI offre i seguenti modelli di embedding di testo: **Ultima generazione** | Modello | Lunghezza del contesto | Dimensione dell'embedding | Descrizione | | ---------------- | ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voyage-4-large` | 32.000 | 1024 (predefinita), 256, 512, 2048 | La migliore qualità di retrieval generico e multilingue. Consulta il [post del blog su Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) per i dettagli. | | `voyage-4` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Ottimizzato per la qualità di retrieval generico e multilingue. Bilancia qualità ed efficienza. Consulta il [post del blog su Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) per i dettagli. | | `voyage-4-lite` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Ottimizzato per latenza e costo. Consulta il [post del blog su Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) per i dettagli. | | `voyage-code-4` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Ottimizzato per il recupero di **codice** e per applicazioni di coding agentico. Consulta il [post del blog su voyage-code-4](https://blog.voyageai.com/2026/08/13/voyage-code-4/) per i dettagli. | | `voyage-4-nano` | 32.000 | 2048 (predefinita), 256, 512, 1024 | Modello open-weight (licenza Apache 2.0) che scarichi da [Hugging Face](https://huggingface.co/voyageai/voyage-4-nano) ed esegui autonomamente. Non disponibile tramite l'Atlas Embedding and Reranking API. Consulta il [post del blog su Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) per i dettagli. | **Generazione precedente** Per lo stato del ciclo di vita di ciascun modello e il sostituto consigliato, consulta [Model deprecations, lifecycle states, and support](https://www.mongodb.com/docs/voyageai/models/lifecycle/) nella documentazione di MongoDB. | Modello | Lunghezza del contesto | Dimensione dell'embedding | Descrizione | | ------------------ | ---------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voyage-3-large` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Generazione precedente di `voyage-4-large`. Consulta il [post del blog su voyage-3-large](https://blog.voyageai.com/2025/01/07/voyage-3-large/) per i dettagli. | | `voyage-3.5` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Generazione precedente di `voyage-4`. Consulta il [post del blog su voyage-3.5](https://blog.voyageai.com/2025/05/20/voyage-3-5/) per i dettagli. | | `voyage-3.5-lite` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Generazione precedente di `voyage-4-lite`. Consulta il [post del blog su voyage-3.5](https://blog.voyageai.com/2025/05/20/voyage-3-5/) per i dettagli. | | `voyage-code-3` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Generazione precedente di `voyage-code-4`. Consulta il [post del blog su voyage-code-3](https://blog.voyageai.com/2024/12/04/voyage-code-3/) per i dettagli. | | `voyage-finance-2` | 32.000 | 1024 | Ottimizzato per il recupero e la RAG in ambito **finanziario**. Consulta il [post del blog su voyage-finance-2](https://blog.voyageai.com/2024/06/03/domain-specific-embeddings-finance-edition-voyage-finance-2/) per i dettagli. | | `voyage-law-2` | 16.000 | 1024 | Ottimizzato per il recupero e la RAG in ambito **legale**. Consulta il [post del blog su voyage-law-2](https://blog.voyageai.com/2024/04/15/domain-specific-embeddings-and-retrieval-legal-edition-voyage-law-2/) per i dettagli. | Inoltre, Voyage AI offre i seguenti modelli di embedding multimodali. Chiama questi modelli con `multimodal_embed()` invece di `embed()`: | Modello | Lunghezza del contesto | Dimensione dell'embedding | Descrizione | | ----------------------- | ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voyage-multimodal-3.5` | 32.000 | 1024 (predefinita), 256, 512, 2048 | Modello di embedding multimodale avanzato in grado di vettorizzare testo, immagini e video intercalati. Include il supporto video come primo modello di embedding video di livello produttivo. Consulta il [post del blog su voyage-multimodal-3.5](https://blog.voyageai.com/2026/01/15/voyage-multimodal-3-5/) per i dettagli. | | `voyage-multimodal-3` | 32.000 | 1024 | Generazione precedente di `voyage-multimodal-3.5`. Vettorizza testo intercalato e immagini ricche di contenuto, come screenshot di PDF, slide, tabelle, figure e altro. Consulta il [post del blog su voyage-multimodal-3](https://blog.voyageai.com/2024/11/12/voyage-multimodal-3/) per i dettagli. | I seguenti modelli di embedding di chunk contestualizzati producono vettori a livello di chunk che catturano il contesto completo del documento senza arricchimento manuale dei metadati. Chiama questi modelli con `contextualized_embed()` invece di `embed()`: | Modello | Lunghezza del contesto | Dimensione dell'embedding | Descrizione | | ------------------ | ---------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voyage-context-4` | 120.000 | 1024 (predefinita), 256, 512, 2048 | Embedding contestualizzati per chunk ottimizzati per la qualità di recupero generico e multilingue. Consulta il [post del blog su voyage-context-4](https://blog.voyageai.com/2026/06/29/voyage-context-4/) per i dettagli. | | `voyage-context-3` | 120.000 | 1024 (predefinita), 256, 512, 2048 | Generazione precedente di `voyage-context-4`. Consulta il [post del blog su voyage-context-3](https://blog.voyageai.com/2025/07/23/voyage-context-3/) per i dettagli. | Il limite di 120.000 token si applica quando imposti `enable_auto_chunking` su `true`. Altrimenti, il numero totale di token su tutti gli input non può superare 32.000. Voyage AI offre anche reranker, che prendono una query e un elenco di documenti e li restituiscono ordinati per rilevanza rispetto alla query. Chiama questi modelli con `rerank()`: | Modello | Lunghezza del contesto | Descrizione | | ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rerank-3` | 32.000 | Massima accuratezza. Consigliato per la maggior parte delle applicazioni. Consulta il [post del blog su rerank-3](https://blog.voyageai.com/2026/09/30/rerank-3/) per i dettagli. | | `rerank-3-lite` | 32.000 | Ottimizzato per latenza e costi. Consulta il [post del blog su rerank-3](https://blog.voyageai.com/2026/09/30/rerank-3/) per i dettagli. | | `rerank-2.5` | 32.000 | Generazione precedente di `rerank-3`. Consulta il [post del blog su rerank-2.5](https://blog.voyageai.com/2025/08/11/rerank-2-5/) per i dettagli. | | `rerank-2.5-lite` | 32.000 | Generazione precedente di `rerank-3-lite`. Consulta il [post del blog su rerank-2.5](https://blog.voyageai.com/2025/08/11/rerank-2-5/) per i dettagli. | Hai bisogno di aiuto per decidere quale modello utilizzare? Consulta [Voyage AI embedding and reranking models overview](https://www.mongodb.com/docs/voyageai/models/) nella documentazione di MongoDB. ## Iniziare con Voyage AI Per accedere ai modelli Voyage AI, crea una chiave API del modello in MongoDB Atlas: 1. Registrati per un account MongoDB Atlas oppure accedi. 2. Nel tuo progetto Atlas, seleziona **AI Model APIs** nella barra di navigazione, fai clic su **Create model API key**, assegna un nome alla chiave e fai clic su **Create**. 3. Per comodità, imposta la chiave API come variabile d'ambiente: ```bash export VOYAGE_API_KEY="" ``` Per maggiori dettagli, consulta [Voyage AI quick start](https://www.mongodb.com/docs/voyageai/quickstart/) nella documentazione di MongoDB. Puoi ottenere gli embedding utilizzando il [pacchetto Python `voyageai`](https://github.com/voyage-ai/voyageai-python) ufficiale oppure tramite richieste HTTP, come descritto nelle sezioni seguenti. Voyage AI dispone anche di un client TypeScript ufficiale. Per usarlo con una chiave API del modello di Atlas, imposta la sua opzione `environment` su `https://ai.mongodb.com/v1`, come descritto in [TypeScript client](https://www.mongodb.com/docs/voyageai/api-and-clients/#typescript-client) nella documentazione di MongoDB. ### Libreria Python di Voyage AI Installa il pacchetto `voyageai` utilizzando il seguente comando. Per usare una chiave API del modello di Atlas, è necessaria la versione 0.3.7 o successiva. ```bash pip install -U voyageai ``` Quindi, puoi creare un oggetto client e iniziare a usarlo per creare gli embedding dei tuoi testi: ```python import voyageai vo = voyageai.Client() # Questo userà automaticamente la variabile d'ambiente VOYAGE_API_KEY. # In alternativa, puoi usare vo = voyageai.Client(api_key="") texts = ["Sample text 1", "Sample text 2"] result = vo.embed(texts, model="voyage-4", input_type="document") print(result.embeddings[0]) print(result.embeddings[1]) ``` `result.embeddings` è una lista di due vettori di embedding, ciascuno contenente 1024 numeri in virgola mobile. Dopo aver eseguito il codice precedente, i due embedding vengono stampati a schermo: ```text [-0.013131560757756233, 0.019828535616397858, ...] # embedding for "Sample text 1" [-0.0069352793507277966, 0.020878976210951805, ...] # embedding for "Sample text 2" ``` Quando crei gli embedding, puoi specificare alcuni altri argomenti per la funzione `embed()`. Per ulteriori informazioni sul pacchetto Python, consulta [Accessing Voyage AI models](https://www.mongodb.com/docs/voyageai/api-and-clients/) nella documentazione di MongoDB. ### API HTTP di Voyage AI Puoi anche ottenere gli embedding inviando richieste HTTP all'Atlas Embedding and Reranking API. Ad esempio, puoi inviare una richiesta HTTP tramite il comando `curl` in un terminale: ```bash cURL curl https://ai.mongodb.com/v1/embeddings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $VOYAGE_API_KEY" \ -d '{ "input": ["Sample text 1", "Sample text 2"], "model": "voyage-4", "input_type": "document" }' ``` La risposta che otterresti è un oggetto JSON contenente gli embedding e l'utilizzo dei token: ```json { "object": "list", "data": [ { "object": "embedding", "embedding": [-0.013131560757756233, 0.019828535616397858 /* ... */], "index": 0 }, { "object": "embedding", "embedding": [-0.0069352793507277966, 0.020878976210951805 /* ... */], "index": 1 } ], "model": "voyage-4", "usage": { "total_tokens": 10 } } ``` Le chiavi API del modello di Atlas funzionano con `ai.mongodb.com`, ad eccezione delle chiavi limitate a un'area geografica, che utilizzano l'endpoint di quell'area geografica. Se invece hai una chiave API della piattaforma Voyage AI, consulta [Migrate your applications to use the Atlas Embedding and Reranking API](https://www.mongodb.com/docs/voyageai/tutorials/migrate-to-atlas/) nella documentazione di MongoDB. Per il riferimento completo di richiesta e risposta, consulta [Create text embeddings](https://www.mongodb.com/docs/api/doc/atlas-embedding-and-reranking-api/operation/operation-createembedding) nella documentazione dell'Atlas Embedding and Reranking API. ### AWS Marketplace I modelli Voyage AI sono disponibili anche su AWS Marketplace tramite il [profilo venditore di MongoDB](https://aws.amazon.com/marketplace/seller-profile?id=c9032c7b-70dd-459f-834f-c1e23cf3d092). Per le istruzioni, consulta [Deploy Voyage AI models using AWS Marketplace](https://www.mongodb.com/docs/voyageai/management/aws-marketplace/) nella documentazione di MongoDB. ## Esempio di avvio rapido Il seguente breve esempio mostra come utilizzare gli embedding. Supponi di avere un piccolo corpus di sei documenti da cui effettuare il retrieval ```python documents = [ "The Mediterranean diet emphasizes fish, olive oil, and vegetables, believed to reduce chronic diseases.", "Photosynthesis in plants converts light energy into glucose and produces essential oxygen.", "20th-century innovations, from radios to smartphones, centered on electronic advancements.", "Rivers provide water, irrigation, and habitat for aquatic species, vital for ecosystems.", "Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.", "Shakespeare's works, like 'Hamlet' and 'A Midsummer Night's Dream,' endure in literature.", ] ``` Per prima cosa, usa Voyage AI per convertire ciascun documento in un vettore di embedding. ```python import voyageai vo = voyageai.Client() # Incorpora i documenti doc_embds = vo.embed(documents, model="voyage-4", input_type="document").embeddings ``` Gli embedding ti consentono di effettuare ricerca semantica / retrieval nello spazio vettoriale. Data una query di esempio, ```python query = "When is Apple's conference call scheduled?" ``` Successivamente, convertila in un embedding ed esegui una ricerca del vicino più prossimo (nearest neighbor) per trovare il documento più rilevante in base alla distanza nello spazio degli embedding. ```python import numpy as np # Calcola l'embedding della query query_embd = vo.embed([query], model="voyage-4", input_type="query").embeddings[0] # Calcola la similarità # Gli embedding di Voyage AI sono normalizzati a lunghezza 1, quindi prodotto scalare # e similarità del coseno coincidono. similarities = np.dot(doc_embds, query_embd) retrieved_id = np.argmax(similarities) print(documents[retrieved_id]) ``` Nota che `input_type="document"` e `input_type="query"` vengono utilizzati rispettivamente per generare l'embedding del documento e della query. Per ulteriori informazioni su `input_type`, consulta [Quando e come dovrei usare il parametro input\_type?](https://platform.claude.com/docs/it/build-with-claude/embeddings#faq) nelle FAQ. L'output è il quinto documento, che è effettivamente il più rilevante per la query: ```text wrap Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET. ``` Se stai cercando un insieme dettagliato di ricette su come fare RAG con gli embedding, inclusi i database vettoriali, consulta la [ricetta RAG](https://platform.claude.com/cookbook/third-party-pinecone-rag-using-pinecone). ## FAQ I modelli di embedding si basano su potenti reti neurali per catturare e comprimere il contesto semantico, in modo simile ai modelli generativi. Il team di ricercatori di IA esperti di Voyage AI ottimizza ogni componente del processo di embedding, tra cui: * Architettura del modello * Raccolta dei dati * Funzioni di perdita * Selezione dell'ottimizzatore Scopri di più sull'approccio tecnico di Voyage AI sul [blog di Voyage AI](https://blog.voyageai.com/). Per embedding generici, i modelli consigliati sono: * `voyage-4-large`: migliore qualità * `voyage-4-lite`: latenza e costo più bassi * `voyage-4`: prestazioni bilanciate Per il retrieval, usa il parametro `input_type` per specificare se il testo è di tipo query o documento. Modelli specifici per dominio: * Attività legali: `voyage-law-2` * Recupero di codice e coding agentico: `voyage-code-4` * Attività in ambito finanziario: `voyage-finance-2` Per il recupero a livello di chunk e a livello di documento: `voyage-context-4` Per testo, immagini e video: `voyage-multimodal-3.5` Puoi usare gli embedding di Voyage AI con la similarità del prodotto scalare, la similarità del coseno o la distanza euclidea. Per una spiegazione della similarità tra embedding, consulta questa [guida alla similarità vettoriale](https://www.pinecone.io/learn/vector-similarity/). Gli embedding di Voyage AI sono normalizzati a lunghezza 1, il che significa che: * La similarità del coseno è equivalente alla similarità del prodotto scalare, mentre quest'ultima può essere calcolata più rapidamente. * La similarità del coseno e la distanza euclidea producono classifiche identiche. Consulta [Tokenization](https://www.mongodb.com/docs/voyageai/tutorials/tokenization/) nella documentazione di MongoDB. Per tutte le attività e i casi d'uso di retrieval (ad esempio, RAG), usa il parametro `input_type` per specificare se il testo di input è una query o un documento. Non omettere `input_type` né impostare `input_type=None`. Specificare se il testo di input è una query o un documento può creare migliori rappresentazioni vettoriali dense per il retrieval, il che può portare a una migliore qualità di retrieval. Quando si utilizza il parametro `input_type`, prompt speciali vengono anteposti al testo di input prima della creazione dell'embedding. In particolare: > 📘 **Prompt associati a `input_type`** > > * Per una query, il prompt è `"Represent the query for retrieving supporting documents: "`. > > * Per un documento, il prompt è `"Represent the document for retrieval: "`. > > * Esempio > > * Quando `input_type="query"`, una query come "When is Apple's conference call scheduled?" diventerà "**Represent the query for retrieving supporting documents:** When is Apple's conference call scheduled?" > * Quando `input_type="document"`, un documento come "Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET." diventerà "**Represent the document for retrieval:** Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET." La "quantization" (quantizzazione) negli embedding converte valori ad alta precisione, come i numeri in virgola mobile a precisione singola a 32 bit, in formati a precisione inferiore come interi a 8 bit o valori binari a 1 bit, riducendo archiviazione, memoria e costi rispettivamente di 4 e 32 volte. I modelli Voyage AI supportati abilitano la quantizzazione specificando il tipo di dati di output con il parametro `output_dtype`: * `float`: Ogni embedding restituito è un elenco di numeri in virgola mobile a precisione singola a 32 bit (4 byte). Questo è il valore predefinito e fornisce la massima precisione / accuratezza di recupero. * `int8` e `uint8`: Ogni embedding restituito è un elenco di interi a 8 bit (1 byte) compresi rispettivamente tra -128 e 127 e tra 0 e 255. * `binary` e `ubinary`: Ogni embedding restituito è un elenco di interi a 8 bit che rappresentano valori di embedding quantizzati a singolo bit e impacchettati in bit: `int8` per `binary` e `uint8` per `ubinary`. La lunghezza dell'elenco di interi restituito è 1/8 della dimensione effettiva dell'embedding. Il tipo binary utilizza il metodo offset binary, come mostra l'esempio seguente. > **Esempio di quantizzazione binaria** > > Considera i seguenti otto valori di embedding: -0.03955078, 0.006214142, -0.07446289, -0.039001465, 0.0046463013, 0.00030612946, -0.08496094 e 0.03994751. Con la quantizzazione binaria, i valori minori o uguali a zero verranno quantizzati a uno zero binario e i valori positivi a un uno binario, ottenendo la seguente sequenza binaria: 0, 1, 0, 0, 1, 1, 0, 1. Questi otto bit vengono quindi impacchettati in un singolo intero a 8 bit, 01001101 (con il bit più a sinistra come bit più significativo). > > * `ubinary`: La sequenza binaria viene convertita direttamente e rappresentata come l'intero senza segno (`uint8`) 77. > * `binary`: La sequenza binaria viene rappresentata come l'intero con segno (`int8`) -51, calcolato utilizzando il metodo offset binary (77 - 128 = -51). Per i modelli che supportano ciascun tipo di dati, consulta [Create text embeddings](https://www.mongodb.com/docs/api/doc/atlas-embedding-and-reranking-api/operation/operation-createembedding) nella documentazione dell'Atlas Embedding and Reranking API. L'apprendimento Matryoshka crea embedding con rappresentazioni da grossolane a fini all'interno di un singolo vettore. I modelli Voyage AI che supportano più dimensioni di output, come `voyage-code-4`, generano tali embedding Matryoshka. Per ottenere vettori più corti dall'API, passa `output_dimension` (ad esempio, `output_dimension=256`). Per accorciare vettori che hai già archiviato, troncali mantenendo il sottoinsieme iniziale di dimensioni, quindi normalizzali di nuovo. Ad esempio, il seguente codice Python mostra come troncare vettori a 1024 dimensioni a 256 dimensioni: ```python import voyageai import numpy as np def embd_normalize(v: np.ndarray) -> np.ndarray: """ Normalize the rows of a 2D numpy array to unit vectors by dividing each row by its Euclidean norm. Raises a ValueError if any row has a norm of zero to prevent division by zero. """ row_norms = np.linalg.norm(v, axis=1, keepdims=True) if np.any(row_norms == 0): raise ValueError("Cannot normalize rows with a norm of zero.") return v / row_norms vo = voyageai.Client() # Genera vettori voyage-code-4, che per impostazione predefinita sono numeri in virgola mobile a 1024 dimensioni embd = vo.embed(["Sample text 1", "Sample text 2"], model="voyage-code-4").embeddings # Imposta una dimensione più corta short_dim = 256 # Ridimensiona e normalizza i vettori alla dimensione più corta resized_embd = embd_normalize(np.array(embd)[:, :short_dim]).tolist() ``` ## Prezzi Per i dettagli sui prezzi più aggiornati, consulta [Model pricing](https://www.mongodb.com/docs/voyageai/management/billing/#model-pricing) nella documentazione di MongoDB.