L'API Text Embedding converte i dati testuali in vettori numerici. Questi le 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 il loro utilizzo
casi:
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: usa task_type= SEMANTIC_SIMILARITY
per entrambi i testi di input per valutare
la somiglianza generale dei significati.
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 configurare l'ambiente, puoi usare REST per testare un prompt di testo. Il seguente esempio invia una richiesta al publisher endpoint del modello.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- TEXT: il testo che deve 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
, il 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 la
generateContent
per richiedere che la risposta venga restituita dopo la sua completa generazione. Per ridurre la percezione della latenza per un pubblico umano, trasmetti la risposta in tempo reale generati utilizzandostreamGenerateContent
. - 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 altri modelli di machine learning.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta documentazione di riferimento dell'API Python.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Go Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Java Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Node.js Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 che deve generare gli incorporamenti. . Limite: cinque testi fino a un massimo di 3072 token per testo.
- TASK_TYPE: utilizzato per trasmettere il downstream desiderato per aiutare il modello a produrre incorporamenti migliori.
- TITLE: utilizzato per aiutare il modello a produrre incorporamenti migliori.
- AUTO_TRUNCATE: se impostato su
false
, il testo che supera il limite di token determina la mancata riuscita della richiesta. Il valore predefinito ètrue
. - OUTPUT_DIMENSIONALITY: utilizzato per specificare 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 ulteriori informazioni, consulta documentazione di riferimento dell'API Python.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Go Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Java Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Node.js Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Lingue di testo supportate
Tutti i modelli di incorporamento del testo supportano e sono stati valutati in lingua inglese
testo. Le textembedding-gecko-multilingual@001
e
I modelli text-multilingual-embedding-002
supportano inoltre e sono stati
valutato 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)
- Lingue supportate:
Afrikaans
,Albanian
,Amharic
,Arabic
,Armenian
,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
eZulu
.
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 dell'
alla 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 | Da determinare. |
text-multilingual-embedding-002 | 14 maggio 2024 | Da determinare. |
textembedding-gecko@003 | 12 dicembre 2023 | 14 maggio 2025 |
textembedding-gecko-multilingual@001 | 2 novembre 2023 | 14 maggio 2025 |
textembedding-gecko@002 (pregresso, ma ancora supportato) |
2 novembre 2023 | 12 dicembre 2024 |
textembedding-gecko@001 (pregresso, ma ancora supportato) |
7 giugno 2023 | 2 novembre 2024 |
multimodalembedding@001 | 12 febbraio 2024 | Da determinare. |
Per saperne di più, consulta Versioni dei modelli e ciclo di vita.
Passaggi successivi
Per una documentazione dettagliata, consulta quanto segue: