Embedding

L'API Gemini offre modelli di incorporamento di testo per generare incorporamenti per parole, frasi, frasi e codice. Questi embedding di base sono alla base di attività di NLP avanzate come la ricerca semantica, la classificazione e il clustering, fornendo risultati più accurati e sensibili al contesto rispetto agli approcci basati su parole chiave.

La creazione di sistemi di Retrieval Augmented Generation (RAG) è un caso d'uso comune per gli incorporamenti. Gli incorporamenti svolgono un ruolo chiave nel migliorare significativamente gli output del modello con maggiore accuratezza fattuale, coerenza e ricchezza contestuale. Recuperano in modo efficiente le informazioni pertinenti dalle knowledge base, rappresentate da incorporamenti, che vengono poi passati come contesto aggiuntivo nel prompt di input ai modelli linguistici, guidandoli a generare risposte più informate e accurate.

Per applicazioni di livello aziendale e carichi di lavoro di grandi volumi, ti consigliamo di utilizzare modelli di incorporamento su Vertex AI.

Generazione degli incorporamenti

Utilizza il metodo embedContent per generare incorporamenti di testo:

Python

from google import genai

client = genai.Client()

result = client.models.embed_content(
        model="gemini-embedding-001",
        contents="What is the meaning of life?")

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {

    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: 'What is the meaning of life?',
    });

    console.log(response.embeddings);
}

main();

Vai

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }
    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(embeddings))
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": {"parts":[{"text": "What is the meaning of life?"}]}
    }'

Puoi anche generare incorporamenti per più blocchi contemporaneamente passandoli come elenco di stringhe.

Python

from google import genai

client = genai.Client()

result = client.models.embed_content(
        model="gemini-embedding-001",
        contents= [
            "What is the meaning of life?",
            "What is the purpose of existence?",
            "How do I bake a cake?"
        ])

for embedding in result.embeddings:
    print(embedding)

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {

    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: [
            'What is the meaning of life?',
            'What is the purpose of existence?',
            'How do I bake a cake?'
        ],
    });

    console.log(response.embeddings);
}

main();

Vai

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?"),
        genai.NewContentFromText("How does photosynthesis work?"),
        genai.NewContentFromText("Tell me about the history of the internet."),
    }
    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(embeddings))
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": [
        {"parts": [{"text": "What is the meaning of life?"}]},
        {"parts": [{"text": "What is the purpose of existence?"}]},
        {"parts": [{"text": "How do I bake a cake?"}]}
        ]
    }'

Specifica il tipo di attività per migliorare il rendimento

Puoi utilizzare gli incorporamenti per un'ampia gamma di attività, dalla classificazione alla ricerca di documenti. Specificare il tipo di attività corretto consente di ottimizzare gli incorporamenti per le relazioni previste, massimizzando l'accuratezza e l'efficienza. Per un elenco completo dei tipi di attività supportati, consulta la tabella Tipi di attività supportati.

Il seguente esempio mostra come utilizzare SEMANTIC_SIMILARITY per verificare la somiglianza di significato tra stringhe di testo.

Python

from google import genai
from google.genai import types
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

client = genai.Client()

texts = [
    "What is the meaning of life?",
    "What is the purpose of existence?",
    "How do I bake a cake?"]

result = [
    np.array(e.values) for e in client.models.embed_content(
        model="gemini-embedding-001",
        contents=texts, 
        config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY")).embeddings
]

# Calculate cosine similarity. Higher scores = greater semantic similarity.

embeddings_matrix = np.array(result)
similarity_matrix = cosine_similarity(embeddings_matrix)

for i, text1 in enumerate(texts):
    for j in range(i + 1, len(texts)):
        text2 = texts[j]
        similarity = similarity_matrix[i, j]
        print(f"Similarity between '{text1}' and '{text2}': {similarity:.4f}")

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as cosineSimilarity from "compute-cosine-similarity";

async function main() {
    const ai = new GoogleGenAI({});

    const texts = [
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    ];

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: texts,
        taskType: 'SEMANTIC_SIMILARITY'
    });

    const embeddings = response.embeddings.map(e => e.values);

    for (let i = 0; i < texts.length; i++) {
        for (let j = i + 1; j < texts.length; j++) {
            const text1 = texts[i];
            const text2 = texts[j];
            const similarity = cosineSimilarity(embeddings[i], embeddings[j]);
            console.log(`Similarity between '${text1}' and '${text2}': ${similarity.toFixed(4)}`);
        }
    }
}

main();

Vai

package main

import (
    "context"
    "fmt"
    "log"
    "math"

    "google.golang.org/genai"
)

// cosineSimilarity calculates the similarity between two vectors.
func cosineSimilarity(a, b []float32) (float64, error) {
    if len(a) != len(b) {
        return 0, fmt.Errorf("vectors must have the same length")
    }

    var dotProduct, aMagnitude, bMagnitude float64
    for i := 0; i < len(a); i++ {
        dotProduct += float64(a[i] * b[i])
        aMagnitude += float64(a[i] * a[i])
        bMagnitude += float64(b[i] * b[i])
    }

    if aMagnitude == 0 || bMagnitude == 0 {
        return 0, nil
    }

    return dotProduct / (math.Sqrt(aMagnitude) * math.Sqrt(bMagnitude)), nil
}

func main() {
    ctx := context.Background()
    client, _ := genai.NewClient(ctx, nil)
    defer client.Close()

    texts := []string{
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    }

    var contents []*genai.Content
    for _, text := range texts {
        contents = append(contents, genai.NewContentFromText(text, genai.RoleUser))
    }

    result, _ := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        &genai.EmbedContentRequest{TaskType: genai.TaskTypeSemanticSimilarity},
    )

    embeddings := result.Embeddings

    for i := 0; i < len(texts); i++ {
        for j := i + 1; j < len(texts); j++ {
            similarity, _ := cosineSimilarity(embeddings[i].Values, embeddings[j].Values)
            fmt.Printf("Similarity between '%s' and '%s': %.4f\n", texts[i], texts[j], similarity)
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [
        {"parts": [{"text": "What is the meaning of life?"}]},
        {"parts": [{"text": "What is the purpose of existence?"}]},
        {"parts": [{"text": "How do I bake a cake?"}]}
    ],
    "embedding_config": {
        "task_type": "SEMANTIC_SIMILARITY"
    }
}'

Di seguito è riportato un esempio di output di questo snippet di codice:

Similarity between 'What is the meaning of life?' and 'What is the purpose of existence?': 0.9481

Similarity between 'What is the meaning of life?' and 'How do I bake a cake?': 0.7471

Similarity between 'What is the purpose of existence?' and 'How do I bake a cake?': 0.7371

Tipi di attività supportati

Tipo di attività Descrizione Esempi
SEMANTIC_SIMILARITY Incorporamenti ottimizzati per valutare la somiglianza del testo. Sistemi di suggerimenti, rilevamento dei duplicati
CLASSIFICAZIONE Incorporamenti ottimizzati per classificare i testi in base a etichette preimpostate. Analisi del sentiment, rilevamento dello spam
CLUSTERING Incorporamenti ottimizzati per raggruppare i testi in base alle loro somiglianze. Organizzazione dei documenti, ricerca di mercato, rilevamento di anomalie
RETRIEVAL_DOCUMENT Incorporamenti ottimizzati per la ricerca di documenti. Indicizzazione di articoli, libri o pagine web per la ricerca.
RETRIEVAL_QUERY Incorporamenti ottimizzati per le query di ricerca generali. Utilizza RETRIEVAL_QUERY per le query e RETRIEVAL_DOCUMENT per i documenti da recuperare. Ricerca personalizzata
CODE_RETRIEVAL_QUERY Incorporamenti ottimizzati per il recupero di blocchi di codice in base a query in linguaggio naturale. Utilizza CODE_RETRIEVAL_QUERY per le query e RETRIEVAL_DOCUMENT per i blocchi di codice da recuperare. Suggerimenti di codice e ricerca
QUESTION_ANSWERING Incorporamenti per le domande in un sistema di risposta alle domande, ottimizzati per trovare i documenti che rispondono alla domanda. Utilizza QUESTION_ANSWERING per le domande e RETRIEVAL_DOCUMENT per i documenti da recuperare. Chatbox
FACT_VERIFICATION Incorporamenti per le affermazioni che devono essere verificate, ottimizzati per il recupero di documenti che contengono prove a sostegno o confutazione dell'affermazione. Utilizza FACT_VERIFICATION per il testo di destinazione; RETRIEVAL_DOCUMENT per i documenti da recuperare Sistemi di verifica dei fatti automatizzati

Controllare le dimensioni dell'incorporamento

Il modello di incorporamento Gemini, gemini-embedding-001, viene addestrato utilizzando la tecnica di apprendimento della rappresentazione Matrioska (MRL), che insegna a un modello a apprendere incorporamenti ad alta dimensionalità con segmenti iniziali (o prefissi) che sono anche versioni più semplici e utili degli stessi dati. Puoi scegliere di utilizzare l'incorporamento completo a 3072 dimensioni oppure puoi troncarlo a una dimensione più piccola senza perdere qualità per risparmiare spazio di archiviazione. Per una qualità ottimale, ti consigliamo di utilizzare i valori 768 e 1536.

Utilizzando il parametro output_dimensionality, gli utenti possono controllare le dimensioni del vettore di incorporamento di output. La selezione di una dimensionalità di output più piccola può consentire di risparmiare spazio di archiviazione e aumentare l'efficienza di calcolo per le applicazioni downstream, sacrificando poco in termini di qualità.

Python

from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents="What is the meaning of life?",
    config=types.EmbedContentConfig(output_dimensionality=768)
)

[embedding_obj] = result.embeddings
embedding_length = len(embedding_obj.values)

print(f"Length of embedding: {embedding_length}")

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {
    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        content: 'What is the meaning of life?',
        outputDimensionality: 768,
    });

    const embeddingLength = response.embedding.values.length;
    console.log(`Length of embedding: ${embeddingLength}`);
}

main();

Vai

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    // The client uses Application Default Credentials.
    // Authenticate with 'gcloud auth application-default login'.
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }

    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        &genai.EmbedContentRequest{OutputDimensionality: 768},
    )
    if err != nil {
        log.Fatal(err)
    }

    embedding := result.Embeddings[0]
    embeddingLength := len(embedding.Values)
    fmt.Printf("Length of embedding: %d\n", embeddingLength)
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: YOUR_GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [
        {"parts": [{"text": "What is the meaning of life?"}]}
    ],
    "embedding_config": {
        "output_dimensionality": 768
    }
}'

Output di esempio:

Length of embedding: 768

L'incorporamento della dimensione 3072 è normalizzato. Gli embedding normalizzati producono una somiglianza semantica più accurata confrontando la direzione del vettore, non la sua magnitudo. Per altre dimensioni, tra cui 768 e 1536, devi normalizzare gli incorporamenti nel seguente modo:

Python

import numpy as np
from numpy.linalg import norm

embedding_values_np = np.array(embedding_obj.values)
normed_embedding = embedding_values_np / np.linalg.norm(embedding_values_np)

print(f"Normed embedding length: {len(normed_embedding)}")
print(f"Norm of normed embedding: {np.linalg.norm(normed_embedding):.6f}") # Should be very close to 1

Output di esempio:

Normed embedding length: 768
Norm of normed embedding: 1.000000

Casi d'uso

Gli incorporamenti di testo sono fondamentali per una serie di casi d'uso comuni dell'AI, ad esempio:

Memorizzazione degli incorporamenti

Quando porti gli incorporamenti in produzione, è comune utilizzare database vettoriali per archiviare, indicizzare e recuperare in modo efficiente incorporamenti ad alta dimensionalità. Google Cloud offre servizi di dati gestiti che possono essere utilizzati a questo scopo, tra cui BigQuery, AlloyDB e Cloud SQL.

I seguenti tutorial mostrano come utilizzare altri database vettoriali di terze parti con Gemini Embedding.

Modelli di embedding

Modello generalmente disponibile

Modelli legacy

  • embedding-001 (ritiro il 14 agosto 2025)
  • text-embedding-004 (ritiro previsto per il 14 gennaio 2026)

Utilizzo degli incorporamenti

A differenza dei modelli di AI generativa che creano nuovi contenuti, il modello Gemini Embedding ha lo scopo di trasformare il formato dei dati di input in una rappresentazione numerica. Sebbene Google sia responsabile della fornitura di un modello di incorporamento che trasforma il formato dei dati di input nel formato numerico richiesto, gli utenti mantengono la piena responsabilità dei dati inseriti e degli incorporamenti risultanti. Utilizzando il modello Gemini Embedding, confermi di detenere i diritti necessari relativi a qualsiasi contenuto caricato. Non generare contenuti che violano la proprietà intellettuale o i diritti di privacy altrui. L'utilizzo di questo servizio è soggetto alle nostre Norme relative all'uso vietato e ai Termini di servizio di Google.

Inizia a creare con gli incorporamenti

Dai un'occhiata al notebook della guida rapida sugli incorporamenti per esplorare le funzionalità del modello e scoprire come personalizzare e visualizzare gli incorporamenti.