Vertex AI fornisce l'API Extension che può registrare, gestire ed eseguire le estensioni. Vertex AI offre inoltre insieme di estensioni predefinite dall'API Extension, incluso l'interprete del codice e l'estensione Vertex AI Search.
Limitazioni
L'API Extension è disponibile solo nella regione us-central1
.
Sintassi di esempio
Sintassi per creare una risorsa di estensione.
curl
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/extensions:import \ -d '{ "displayName": "...", "description": "...", "manifest": { ... "apiSpec": { ... }, "authConfig": { ... } ... } }'
Python
from vertexai.preview import extensions extensions.Extension.create( manifest: Union[JsonDict, ExtensionManifest], display_name: Optional[str] = None, description: Optional[str] = None, runtime_config: Optional[Union[JsonDict, RuntimeConfig]] = None )
Elenco dei parametri
Corpo della richiesta
Parametri | |
---|---|
|
Facoltativo: Il nome visualizzato dell'estensione mostrato agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 di massimo 128 caratteri. |
|
(Facoltativo) La descrizione dell'estensione visualizzata agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 di massimo 1 MB. |
Il manifest dell'estensione. |
|
Facoltativo: La configurazione di runtime che controlla il comportamento di runtime dell'estensione. Per l'estensione di interprete di codice, il formato è il seguente: "runtimeConfig": { "codeInterpreterRuntimeConfig": { "fileInputGcsBucket": string, "fileOutputGcsBucket": string } } Per l'estensione Vertex AI Search, il formato è il seguente: "runtimeConfig": { "vertexAiSearchRuntimeConfig": { "servingConfigName": string, } } |
manifest
Il manifest dell'estensione.
Parametri | |
---|---|
|
Il nome dell'estensione utilizzato dall'LLM per il ragionamento. Deve essere una stringa UTF-8 con un massimo di 128 caratteri. |
|
La descrizione in linguaggio naturale dell'utilizzo dell'estensione. La descrizione viene mostrata all'LLM per facilitare il ragionamento.Deve essere una stringa UTF-8 con una dimensione massima di 1 MB. |
La specifica dell'API mostrata all'LLM per il ragionamento. Devi fornire una descrizione significativa e informativa. "apiSpec": { "openApiGcsUri": string } |
|
Il tipo di autorizzazione supportato da questa estensione. Una richiesta di importazione dell'estensione deve contenere una configurazione di autenticazione. "authConfig": { "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH", "googleServiceAccountConfig": { "serviceAccount": string }, } |
apiSpec
La specifica dell'API mostrata all'LLM per il ragionamento.
Parametri | |
---|---|
|
URI Cloud Storage del file YAML OpenAPI che descrive l'API di estensione, ad esempio |
authConfig
Il tipo di autenticazione supportato da questa estensione.
Parametri | |
---|---|
|
Metodo di autenticazione. Valori supportati: |
googleServiceAccountConfig
L'estensione di interpretazione del codice e l'estensione Vertex AI Search supportano solo l'autenticazione dell'account di servizio Google, in cui Vertex AI utilizza Vertex AI Extension Service Agent per accedere alle API.
Parametri | |
---|---|
|
(Facoltativo) L'account di servizio con cui viene eseguita l'esecuzione dell'estensione. Se l'account di servizio è specificato, l'autorizzazione |
runtimeConfig
L'oggetto runtimeConfig
contiene configurazioni aggiuntive utilizzate durante l'esecuzione dell'estensione.
Estensione Interprete codice
Parametri | |
---|---|
|
(Facoltativo) Il bucket Cloud Storage per l'input del file nell'estensione. All'agente di servizio del codice personalizzato estensione Vertex deve essere concessa l'autorizzazione |
|
Facoltativo: Il bucket Cloud Storage per il file di output dell'estensione. All'agente di servizio del codice personalizzato estensione Vertex deve essere concessa l'autorizzazione |
Estensione Vertex AI Search
Parametri | |
---|---|
|
Nome della configurazione di servizio di Vertex AI Search per specificare la risorsa Vertex AI Search utilizzata dall'estensione. Formato:
|
Esegui estensione
Parametri | |
---|---|
|
L'ID selezionato dell'operazione da eseguire in questa estensione. |
|
(Facoltativo) Parametri di richiesta utilizzati per eseguire questa operazione. Il codice JSON deve essere sotto forma di
mappa con il nome del parametro come chiave e il valore effettivo del parametro come
valore. Ad esempio, per impostare un parametro chiamato |
Esempi
Importa un'estensione di interprete di codice
Crea o registra una risorsa di estensione.
Questo esempio mostra come importare un'estensione di interprete di codice.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui elaborare la richiesta.
- DISPLAY_NAME: il nome visualizzato dell'estensione mostrato agli utenti nell'API e nell'interfaccia utente. Deve essere una stringa UTF-8 di massimo 128 caratteri.
- DESCRIPTION: la descrizione dell'estensione mostrata agli utenti nell'API e nell'interfaccia utente. Deve essere una stringa UTF-8 di massimo 1 MB.
- MANIFEST_NAME: il nome dell'estensione utilizzata dall'LLM per il ragionamento. Deve essere una stringa UTF-8 di massimo 128 caratteri
- MANIFEST_DESCRIPTION: la descrizione in linguaggio naturale mostrata all'LLM. Dovrebbe descrivere l'utilizzo dell'estensione ed è essenziale per l'esecuzione del ragionamento da parte dell'LLM. Deve essere una stringa UTF-8 di massimo 1 MB.
- GCS_URI: URI Cloud Storage del file YAML OpenAPI che descrive l'API di estensione.
- AUTH_TYPE: metodo di autenticazione. Valori supportati:
GOOGLE_SERVICE_ACCOUNT_AUTH
.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import
Corpo JSON della richiesta:
{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "manifest": { "name": "NAME", "description": "MANIFEST_DESCRIPTION", "apiSpec": { "openApiGcsUri": "GCS_URI", }, "authConfig": { "authType": "AUTH_TYPE", "googleServiceAccountConfig": {} } } }
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import"
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Importazione con una configurazione di runtime
Crea o registra una risorsa di estensione.
Questo esempio mostra come importare un'estensione di Vertex AI Search specificando
RuntimeConfig
.
REST
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui elaborare la richiesta.
- DISPLAY_NAME: il nome visualizzato dell'estensione mostrato agli utenti nell'API e nell'interfaccia utente. Deve essere una stringa UTF-8 di massimo 128 caratteri.
- DESCRIPTION: la descrizione dell'estensione mostrata agli utenti nell'API e nell'interfaccia utente. Deve essere una stringa UTF-8 di massimo 1 MB.
- MANIFEST_NAME: il nome dell'estensione utilizzata dall'LLM per il ragionamento. Deve essere una stringa UTF-8 di massimo 128 caratteri
- MANIFEST_DESCRIPTION: la descrizione in linguaggio naturale mostrata all'LLM. Dovrebbe descrivere l'utilizzo dell'estensione ed è essenziale per l'esecuzione del ragionamento da parte dell'LLM. Deve essere una stringa UTF-8 di massimo 1 MB.
- GCS_URI: URI Cloud Storage del file YAML OpenAPI che descrive l'API di estensione.
- AUTH_TYPE: metodo di autenticazione. Valori supportati:
GOOGLE_SERVICE_ACCOUNT_AUTH
. - SERVING_CONFIG_NAME: nome della configurazione di pubblicazione di Vertex AI Search per specificare la risorsa Vertex AI Search utilizzata dall'estensione. Formato:
projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import
Corpo JSON della richiesta:
{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "manifest": { "name": "NAME", "description": "MANIFEST_DESCRIPTION", "apiSpec": { "openApiGcsUri": "GCS_URI", }, "authConfig": { "authType": "AUTH_TYPE", "googleServiceAccountConfig": {} }, runtime_config={ "vertex_ai_search_runtime_config": { "serving_config_name": SERVING_CONFIG_NAME, } } } }
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
,
quindi esegui il comando seguente:
$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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content
Python
import vertexai from vertexai.preview import extensions vertexai.init(project=PROJECT_ID, location=LOCATION) extension_vertex_ai_search = extensions.Extension.create( display_name = "vertex_ai_search", description = "This extension search from provided datastore", manifest = { "name": "vertex_ai_search", "description": "Google Vertex AI Search Extension", "api_spec": { "open_api_gcs_uri": "gs://vertex-extension-public/vertex_ai_search.yaml" }, "auth_config": { "google_service_account_config": {}, "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH", }, }, runtime_config={ "vertex_ai_search_runtime_config": { "serving_config_name": SERVING_CONFIG_NAME, } } )
Esegui un'estensione
Per eseguire un'estensione, chiama direttamente l'estensione e fornisci il metodo parametri di esecuzione nella richiesta.
In questo esempio viene eseguita l'estensione dell'interprete di codice generate_and_execute
in
trova la risposta per la query find the max value in the list: [1,2,3,4,-5]
.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui elaborare la richiesta.
- EXTENSION_ID: l'ID dell'estensione.
- OPERATION_ID: l'ID selezionato dell'operazione da eseguire in questa estensione.
- QUERY: i parametri di richiesta per eseguire l'operazione in un formato chiave-valore,
{"query": "What is Vertex AI?"}.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute
Corpo JSON della richiesta:
{ "operation_id": "OPERATION_ID", "operation_params": { "query": "QUERY", } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
,
quindi esegui il comando seguente:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute"
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta documentazione di riferimento dell'API Python.
Elenco estensioni
Elenca le estensioni in un progetto.
REST
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui elaborare la richiesta.
- EXTENSION_ID: l'ID dell'estensione.
Metodo HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Esegui questo comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions"
PowerShell
Esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions" | Select-Object -Expand Content
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Scaricare un'estensione
Visualizzare i dettagli di un'estensione.
REST
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui elaborare la richiesta.
- EXTENSION_ID: l'ID dell'estensione.
Metodo HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Esegui questo comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"
PowerShell
Esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content
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.
Aggiornare un'estensione
Aggiorna un'estensione.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui elaborare la richiesta.
- EXTENSION_ID: l'ID dell'estensione.
- UPDATE_MASK: il parametro da aggiornare. Valori accettati:
displayName
,description
otoolUseExamples
.
Metodo HTTP e URL:
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"
Corpo JSON della richiesta:
{ "description": "UPDATE_MASK", }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
,
quindi esegui il comando seguente:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK""
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 PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"" | Select-Object -Expand Content
Elimina estensione
Elimina un'estensione.
Questo esempio elimina l'estensione associata all'ID estensione.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui elaborare la richiesta.
- EXTENSION_ID: l'ID dell'estensione.
Metodo HTTP e URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Esegui questo comando:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"
PowerShell
Esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.