L'API Text Embedding converte i dati testuali in vettori numerici. Queste rappresentazioni vettoriali sono progettate per catturare il significato semantico e il contesto delle parole che rappresentano.
Modelli supportati:
Modelli inglesi | Modelli multilingue |
---|---|
textembedding-gecko@001 |
textembedding-gecko-multilingual@001 |
textembedding-gecko@003 |
text-multilingual-embedding-002 |
text-embedding-004 |
Sintassi
curl
PROJECT_ID = PROJECT_ID REGION = us-central1 MODEL_ID = MODEL_ID curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:predict -d \ '{ "instances": [ ... ], "parameters": { ... } }'
Python
PROJECT_ID = PROJECT_ID REGION = us-central1 MODEL_ID = MODEL_ID import vertexai from vertexai.language_models import TextEmbeddingModel vertexai.init(project=PROJECT_ID, location=REGION) model = TextEmbeddingModel.from_pretrained(MODEL_ID) embeddings = model.get_embeddings(...)
Elenco dei parametri
Parametri | |
---|---|
|
Ogni istanza rappresenta una singola porzione di testo da incorporare. |
|
Il testo per cui vuoi generare gli incorporamenti. |
|
Facoltativo: Se il criterio viene impostato su true, il testo di input verrà troncato. Se il criterio viene impostato su false, viene restituito un errore se il testo di input supera la lunghezza massima supportata dal modello. Il valore predefinito è true. |
|
Facoltativo: Utilizzato per specificare la dimensione di incorporamento dell'output. Se impostato, gli incorporamenti di output verranno troncati alla dimensione specificata. |
Corpo della richiesta
{
"instances": [
{
"task_type": "RETRIEVAL_DOCUMENT",
"title": "document title",
"content": "I would like embeddings for this text!"
},
]
}
Parametri | |
---|---|
|
Il testo per cui vuoi generare gli incorporamenti. |
|
Facoltativo: Utilizzato per trasmettere l'applicazione downstream prevista per aiutare il modello a produrre incorporamenti migliori. Deve essere uno dei seguenti valori:
Il parametro |
|
Facoltativo: Utilizzato per aiutare il modello a produrre incorporamenti migliori.
Valido solo con |
taskType
La seguente tabella descrive i valori parametro task_type
e i relativi casi d'uso:
task_type |
Descrizione |
---|---|
RETRIEVAL_QUERY |
Specifica che il testo specificato è una query in un'impostazione di ricerca o recupero. |
RETRIEVAL_DOCUMENT |
Specifica che il testo specificato è un documento in un'impostazione di ricerca o recupero. |
SEMANTIC_SIMILARITY |
Specifica che il testo specificato viene utilizzato per la somiglianza testuale semantica (STS). |
CLASSIFICATION |
Specifica che l'incorporamento viene utilizzato per la classificazione. |
CLUSTERING |
Specifica che l'incorporamento viene utilizzato per il clustering. |
QUESTION_ANSWERING |
Specifica che l'incorporamento delle query viene utilizzato per rispondere alle domande. Utilizza RETRIEVAL_DOCUMENT per il lato del documento. |
FACT_VERIFICATION |
Specifica che l'incorporamento delle query viene utilizzato per la verifica dei fatti. |
Attività di recupero:
Query: utilizza task_type=RETRIEVAL_QUERY
per indicare che il testo di input è una query di ricerca.
Corpus: utilizza task_type=RETRIEVAL_DOCUMENT
per indicare che il testo di input fa parte
della raccolta di documenti in cui viene eseguita la ricerca.
Attività di somiglianza:
Somiglianza semantica: utilizza task_type= SEMANTIC_SIMILARITY
per entrambi i testi di input per valutare la
somiglianza complessiva del loro significato.
Corpo della risposta
{
"predictions": [
{
"embeddings": {
"statistics": {
"truncated": boolean,
"token_count": integer
},
"values": [ number ]
}
}
]
}
Elemento risposta | Descrizione |
---|---|
embeddings |
Il risultato generato dal testo di input. |
statistics |
Le statistiche calcolate dal testo di input. |
truncated |
Indica se il testo di input è stato troncato e più lungo del numero massimo di token consentiti. |
tokenCount |
Numero di token del testo di input. |
values |
Il campo values contiene i vettori di incorporamento corrispondenti alle parole nel testo di input. |
Esempio di risposta
{
"predictions": [
{
"embeddings": {
"values": [
0.0058424929156899452,
0.011848051100969315,
0.032247550785541534,
-0.031829461455345154,
-0.055369812995195389,
...
],
"statistics": {
"token_count": 4,
"truncated": false
}
}
}
]
}
Esempi
Incorpora una stringa di testo
Caso d'uso di base
L'esempio seguente mostra come ottenere l'incorporamento di una stringa di testo.
REST
Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. Il seguente esempio invia una richiesta all'endpoint del modello di publisher.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- TEXT: il testo per cui vuoi generare gli incorporamenti. Limite: cinque testi fino a un massimo di 2048 token per testo per tutti i modelli eccetto
textembedding-gecko@001
. La lunghezza massima del token di input pertextembedding-gecko@001
è 3072. - AUTO_TRUNCATE: se impostato su
false
, un testo che supera il limite di token determina la mancata riuscita della richiesta. Il valore predefinito ètrue
.
Metodo HTTP e URL:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004:predict
Corpo JSON della richiesta:
{ "instances": [ { "content": "TEXT"} ], "parameters": { "autoTruncate": AUTO_TRUNCATE } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004:predict"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004:predict" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente. Tieni presente che values
è stato troncato per risparmiare spazio.
- Utilizza il metodo
generateContent
per richiedere che la risposta venga restituita dopo la completa generazione. Per ridurre la percezione della latenza per un pubblico umano, trasmetti il flusso della risposta mentre viene generata utilizzando il metodostreamGenerateContent
. - L'ID modello multimodale si trova alla fine dell'URL, prima del metodo (ad esempio,
gemini-1.5-flash
ogemini-1.0-pro-vision
). Questo esempio potrebbe supportare anche altri modelli.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Caso d'uso avanzato
L'esempio seguente illustra alcune funzionalità avanzate
- Utilizza
task_type
etitle
per migliorare la qualità dell'incorporamento. - Utilizza i parametri per controllare il comportamento dell'API.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- TEXT: il testo per cui vuoi generare gli incorporamenti. Limite: cinque testi fino a un massimo di 3072 token per testo.
- TASK_TYPE: utilizzato per trasmettere l'applicazione downstream prevista per aiutare il modello a produrre incorporamenti migliori.
- TITLE: utilizzato per aiutare il modello a produrre incorporamenti migliori.
- AUTO_TRUNCATE: se impostato su
false
, un testo che supera il limite di token determina la mancata riuscita della richiesta. Il valore predefinito ètrue
. - OUTPUT_DIMENSIONALITY: utilizzata per specificare la dimensione di incorporamento dell'output. Se impostato, gli incorporamenti di output verranno troncati alla dimensione specificata.
Metodo HTTP e URL:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict
Corpo JSON della richiesta:
{ "instances": [ { "content": "TEXT", "task_type": "TASK_TYPE", "title": "TITLE" }, ], "parameters": { "autoTruncate": AUTO_TRUNCATE, "outputDimensionality": OUTPUT_DIMENSIONALITY } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente. Tieni presente che values
è stato troncato per risparmiare spazio.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Lingue di testo supportate
Tutti i modelli di incorporamento del testo supportano e sono stati valutati sul testo
in lingua inglese. I modelli textembedding-gecko-multilingual@001
e
text-multilingual-embedding-002
supportano inoltre e sono stati
valutati nelle seguenti lingue:
- Lingue valutate:
Arabic (ar)
,Bengali (bn)
,English (en)
,Spanish (es)
,German (de)
,Persian (fa)
,Finnish (fi)
,French (fr)
,Hindi (hi)
,Indonesian (id)
,Japanese (ja)
,Korean (ko)
,Russian (ru)
,Swahili (sw)
,Telugu (te)
,Thai (th)
,Yoruba (yo)
,Chinese (zh)
- /8/9,
Afrikaans
/9,Afrikaans
/9,Afrikaans
/9,Afrikaans
/1,Afrikaans
/1,Afrikaans
/1,Afrikaans
/Armenian
,Afrikaans
/1,Afrikaans
/Armenian
,Afrikaans
/Armenian
,Albanian
Amharic
Arabic
Azerbaijani
Basque
Belarusiasn
Bengali
Bulgarian
Burmese
Catalan
Cebuano
Chichewa
Chinese
Corsican
Czech
Danish
Dutch
English
Esperanto
Estonian
Filipino
Finnish
French
Galician
Georgian
German
Greek
Gujarati
Haitian Creole
Hausa
Hawaiian
Hebrew
Hindi
Hmong
Hungarian
Icelandic
Igbo
Indonesian
Irish
Italian
Japanese
Javanese
Kannada
Kazakh
Khmer
Korean
Kurdish
Kyrgyz
Lao
Latin
Latvian
Lithuanian
Luxembourgish
Macedonian
Malagasy
Malay
Malayalam
Maltese
Maori
Marathi
Mongolian
Nepali
Norwegian
Pashto
Persian
Polish
Portuguese
Punjabi
Romanian
Russian
Samoan
Scottish Gaelic
Serbian
Shona
Sindhi
Sinhala
Slovak
Slovenian
Somali
Sotho
Spanish
Sundanese
Swahili
Swedish
Tajik
Tamil
Telugu
Thai
Turkish
Ukrainian
Urdu
Uzbek
Vietnamese
Welsh
West Frisian
Xhosa
Yiddish
Yoruba
Zulu
Versioni modello
Per utilizzare una versione del modello stabile,
specifica il numero di versione del modello, ad esempio text-embedding-004
.
Ogni versione stabile è disponibile per sei mesi dopo la data di rilascio della
versione stabile successiva.
La tabella seguente contiene le versioni dei modelli stabili disponibili:
Nome modello | Data di uscita | Data di interruzione |
---|---|---|
incorporamento-testo-004 | 14 maggio 2024 | 14 maggio 2025 |
text-embedding-preview-0409 | 9 aprile 2024 | 27 giugno 2024 |
text-multilingual-embedding-002 | 14 maggio 2024 | 14 maggio 2025 |
text-multilingual-embedding-preview-0409 | 9 aprile 2024 | 27 giugno 2024 |
textembedding-gecko@003 | 12 dicembre 2023 | 12 dicembre 2024 |
textembedding-gecko-multilingual@001 | 2 novembre 2023 | 12 dicembre 2024 |
textembedding-gecko@002 (pregresso, ma ancora supportato) |
2 novembre 2023 | 9 ottobre 2024 |
textembedding-gecko@001 | 7 giugno 2023 | 9 ottobre 2024 |
multimodalembedding@001 | 12 febbraio 2024 | 12 febbraio 2025 |
Per saperne di più, consulta Versioni dei modelli e ciclo di vita.
Passaggi successivi
Per una documentazione dettagliata, consulta quanto segue: