Questo documento mostra la funzionalità chiave del servizio di estensione Vertex AI:
- Come creare e importare le estensioni.
- Come gestire le estensioni.
- Come eseguire le estensioni.
Per scoprire come importare ed eseguire un'estensione fornita da Google, consulta quanto segue:
- Utilizza l'estensione dell'interprete di codice per generare ed eseguire codice.
- Utilizza l'estensione Vertex AI Search per accedere e cercare corpus di siti web e dati non strutturati per fornire risposte pertinenti a domande in linguaggio naturale.
Creare e importare estensioni
Questo documento presuppone che tu disponga già di un servizio API in esecuzione in grado di supportare un'estensione. Per creare un'estensione, devi definire la sua interfaccia con un'API esterna in un file di specifica API. Devi caricare questo file di specifiche in un bucket Cloud Storage o convertirlo in una stringa. Devi quindi definire un manifest dell'estensione, includere il file di specifica e inviare una richiesta di registrazione al servizio di estensione.
Crea un file di specifiche API
Un'estensione può essere creata da chiunque tramite file che definiscono e descrivono gli endpoint API dell'estensione. Gli endpoint API possono essere pubblici o privati e ospitati su qualsiasi cloud o on-premise.
Un file di specifica API descrive l'interfaccia di un servizio API. Devi fornire un file di specifica API in formato YAML compatibile con OpenAPI 3.0. Questo file di specifiche deve definire quanto segue:
Un oggetto server. Questo oggetto deve definire un URL del server API. Il servizio di estensione Vertex AI non supporta più server.
servers: - url: API_SERVICE_URL
Un oggetto percorsi. Questo oggetto deve descrivere le varie operazioni fornite dal servizio API e i parametri di input corrispondenti a ogni operazione. Ogni operazione deve avere un identificatore univoco e una risposta.
paths: ... get: operationId: API_SERVICE_OPERATION_ID ... parameters: - name: API_SERVICE_INPUT_VAR ... responses: ...
Un oggetto componenti. Questo oggetto è facoltativo. Puoi utilizzare l'oggetto components per definire oggetti riutilizzabili. Ad esempio, puoi utilizzare l'oggetto components per fornire una definizione degli schemi degli oggetti definiti nell'oggetto paths. Puoi anche utilizzare l'oggetto components per descrivere i parametri di output del servizio API.
components: schemas: Result: ... properties: API_SERVICE_OUTPUT_VAR: ...
Per saperne di più su OpenAPI, consulta Specifica OpenAPI.
L'esempio seguente è un file di specifica API per un servizio API che dice "hello" nella lingua richiesta:
openapi: "3.0.0"
info:
version: 1.0.0
title: Hello Extension
description: Learn to build Vertex AI extensions
servers:
- url: [API_SERVICE_URL]
paths:
/hello:
get:
operationId: say_hello
description: Say hello in prompted language.
parameters:
- name: apiServicePrompt
in: query
description: Language
required: true
schema:
type: string
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: "#/components/schemas/Result"
components:
schemas:
Result:
description: Hello in the requested language.
properties:
apiServiceOutput:
type: string
Carica il file di specifica
Puoi caricare il file di specifica in un bucket Cloud Storage o convertirlo in una stringa.
Se carichi il file di specifica in un bucket Cloud Storage, concedi il ruolo Storage Object Viewer al account di servizio Vertex AI Extension Service Agent
(service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com
). Per scoprire
come elencare i bucket nel tuo progetto, consulta
Elenco dei bucket.
Per scoprire come copiare un oggetto in un bucket Cloud Storage, consulta
Copiare, rinominare e spostare oggetti.
Definisci una richiesta di importazione di estensioni
Dopo aver creato un file di specifica API, puoi definire una richiesta di importazione dell'estensione in un file JSON. Una richiesta di importazione dell'estensione deve contenere un riferimento al file di specifica dell'API (apiSpec
) e alla configurazione dell'autenticazione (authConfig
). Per connettere l'estensione a un modello linguistico di grandi dimensioni (LLM) e vedere come funziona, includi il parametro facoltativo toolUseExamples
. Se
vuoi eseguire solo l'estensione, non includere il parametro toolUseExamples
.
Una richiesta di importazione di estensioni ha il seguente formato:
{
"displayName": "DISPLAY_NAME_HUMAN",
"description": "DESCRIPTION_HUMAN",
"manifest": {
"name": "EXTENSION_NAME_LLM",
"description": "DESCRIPTION_LLM",
"apiSpec": { ... },
"authConfig": { ... },
}
"toolUseExamples": [ ... ],
}
- DISPLAY_NAME_HUMAN: il nome dell'estensione visualizzato dagli utenti.
- DESCRIPTION_HUMAN: la descrizione dell'estensione visualizzata dagli utenti.
- EXTENSION_NAME_LLM: il nome dell'estensione utilizzata dal LLM per il ragionamento.
- DESCRIPTION_LLM: la descrizione dell'estensione utilizzata dal LLM per il ragionamento. Devi fornire una descrizione significativa e informativa.
Riferimento al file di specifica dell'API
La richiesta di importazione dell'estensione deve contenere un riferimento al file di specifica dell'API. Puoi fornire il file di specifica in due modi:
Utilizza
openApiGcsUri
per inserire l'URI Cloud Storage del file YAML."apiSpec": { "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml" },
- BUCKET_NAME: il nome del bucket Cloud Storage che archivia il file di specifica.
- SPECIFICATION_FILE_NAME: il nome del file delle specifiche API.
Utilizza
openApiYaml
per passare il file YAML come stringa.
Configurazione autenticazione
Le estensioni possono essere pubbliche, disponibili per qualsiasi utente, o private, disponibili solo per gli utenti autorizzati all'interno di una o più organizzazioni.
Una richiesta di importazione di estensioni deve contenere una configurazione di autenticazione. Puoi scegliere tra i seguenti metodi di autenticazione:
NO_AUTH
: Nessuna autenticazioneAPI_KEY_AUTH
: autenticazione con chiave APIHTTP_BASIC_AUTH
: autenticazione di base HTTPOAUTH
: autenticazione OAuthOIDC_AUTH
: autenticazione OIDC
Per scoprire di più sulle configurazioni di autenticazione, consulta Specificare una configurazione di autenticazione.
Esempi che mostrano come funziona l'estensione
Per ottenere risultati ottimali, una richiesta di importazione di estensioni deve contenere esempi che
dimostrino il funzionamento dell'estensione. Utilizza il parametro toolUseExamples
per
fornire questi esempi.
Il seguente codice mostra il formato di toolUseExamples
per un singolo esempio,
con un singolo parametro di input e un singolo parametro di output. In questo esempio,
sia i parametri della richiesta sia quelli della risposta sono di tipo string
.
"toolUseExamples": [
{
"extensionOperation": {
"operationId": "API_SERVICE_OPERATION_ID",
},
"displayName": "EXAMPLE_DISPLAY_NAME",
"query": "EXAMPLE_QUERY",
"requestParams": {
"fields": [
{
"key": "API_SERVICE_INPUT_VAR",
"value": {
"string_value": "EXAMPLE_INPUT",
}
}
]
},
"responseParams": {
"fields": [
{
"key": "API_SERVICE_OUTPUT_VAR",
"value": {
"string_value": "EXAMPLE_OUTPUT",
},
}
],
},
"responseSummary": "EXAMPLE_SUMMARY"
}
],
query
: Un esempio di query che può sfruttare questa estensione. Utilizza EXAMPLE_QUERY per fornire il testo della query.extensionOperation
: un'operazione di estensione adatta a rispondere aquery
. Utilizza API_SERVICE_OPERATION_ID per fornire l'ID di un'operazione di estensione definita nel file di specifica dell'API.displayName
: Un nome visualizzato per l'esempio. Utilizza EXAMPLE_DISPLAY_NAME per fornire una breve descrizione.requestParams
: i parametri della richiesta necessari perextensionOperation
e i valori di esempio, nel formato chiave-valore. Utilizza API_SERVICE_INPUT_VAR per fornire un parametro di input definito nel file di specifica API e corrispondente a API_SERVICE_OPERATION_ID. Utilizza EXAMPLE_INPUT per fornire un esempio di valore di input corrispondente a EXAMPLE_QUERY.responseParams
: i parametri di risposta diextensionOperation
e valori di esempio nel formato chiave-valore. Utilizza API_SERVICE_OUTPUT_VAR per fornire un parametro di output definito nel file di specifica API e corrispondente al servizio API. Utilizza EXAMPLE_OUTPUT per fornire un esempio di valore di output che corrisponde a EXAMPLE_INPUT.responseSummary
: un esempio di riepilogo che l'applicazione potrebbe fornire in risposta aquery
. Utilizza EXAMPLE_SUMMARY per fornire il testo del riepilogo.
Di seguito è riportato un esempio di toolUseExamples
per un servizio API che
dice "hello" nella lingua richiesta:
"toolUseExamples": [
{
"extensionOperation": {
"operationId": "say_hello",
},
"displayName": "Say hello in the requested language",
"query": "Say hello in French",
"requestParams": {
"fields": [
{
"key": "apiServicePrompt",
"value": {
"string_value": "French",
}
}
]
},
"responseParams": {
"fields": [
{
"key": "apiServiceOutput",
"value": {
"string_value": "bonjour",
},
}
],
},
"responseSummary": "Bonjour"
}
],
Specifica una configurazione di autenticazione
Devi specificare una configurazione di autenticazione quando definisci una richiesta di importazione dell'estensione.
Se la tua estensione non richiede l'autenticazione, imposta la variabile authType
su NO_AUTH
:
"authConfig": {
"authType": "NO_AUTH"
}
Se la tua estensione richiede l'autenticazione, devi impostare il tipo di autenticazione
nella variabile authType
e fornire una configurazione di autenticazione. Puoi
scegliere tra i seguenti metodi di autenticazione:
- Autenticazione con chiave API HTTP
- Autenticazione di base HTTP
- Autenticazione OAuth
- Autenticazione OIDC
Autenticazione con chiave API
Per supportare l'autenticazione con chiave API, Vertex AI si integra con
SecretManager per l'archiviazione e l'accesso
ai secret. La piattaforma Vertex AI Extensions non archivia direttamente i dati sensibili.
È tua responsabilità gestire il ciclo di vita della risorsa SecretManager
.
Specifica authConfig
nel seguente modo:
"authConfig": {
"authType": "API_KEY_AUTH",
"apiKeyConfig": {
"name": "API_KEY_CONFIG_NAME",
"apiKeySecret": "API_KEY_SECRET",
"httpElementLocation": "HTTP_ELEMENT_LOCATION",
},
}
- API_KEY_CONFIG_NAME: il nome della chiave API. Ad esempio,
nella richiesta API
https://example.com/act?api_key=<API KEY>
, API_KEY_CONFIG_NAME corrisponde aapi_key
. - API_KEY_SECRET: risorsa della versione segreta
SecretManager
che archivia la chiave. Questo parametro ha il seguente formato:projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION
. HTTP_ELEMENT_LOCATION: la posizione della chiave API nella richiesta HTTP. I valori possibili sono:
HTTP_IN_QUERY
HTTP_IN_HEADER
HTTP_IN_PATH
HTTP_IN_BODY
HTTP_IN_COOKIE
Per scoprire di più, consulta la sezione Descrizione dei parametri.
Autenticazione di base HTTP
Per supportare l'autenticazione di base HTTP, Vertex AI si integra con
SecretManager per l'archiviazione e l'accesso ai secret. La piattaforma Vertex AI Extensions non archivia direttamente i dati sensibili.
Devi gestire autonomamente il ciclo di vita della risorsa SecretManager
.
Specifica authConfig
nel seguente modo:
"authConfig": {
"authType": "HTTP_BASIC_AUTH",
"httpBasicAuthConfig": {
"credentialSecret": "CREDENTIAL_SECRET"
},
}
- CREDENTIAL_SECRET: risorsa della versione del secret
SecretManager
che memorizza la credenziale codificata in base64. Questo parametro ha il seguente formato:projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION
.
Autenticazione OAuth
Vertex AI supporta due metodi di autenticazione OAuth: token di accesso e account di servizio.
Token di accesso
Specifica authConfig
nel seguente modo:
"authConfig": {
"authType": "OAUTH",
"oauthConfig": {}
}
Lascia vuoto il campo oauthConfig
quando importi l'estensione. Se
scegli di eseguire un'estensione registrata, devi fornire un token di accesso nel
campo oauthConfig
della richiesta di esecuzione. Per saperne di più, consulta
Eseguire l'estensione.
Service account
Specifica authConfig
nel seguente modo:
"authConfig": {
"authType": "OAUTH",
"oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
- SERVICE_ACCOUNT_NAME: Vertex AI utilizza questo account di servizio per generare token di accesso.
Segui questi passaggi per consentire a Vertex AI Extension Service Agent
di
ottenere token di accesso da SERVICE_ACCOUNT_NAME.
Vai alla pagina IAM.
Seleziona la scheda Service Account.
Fai clic sul tuo account di servizio. Il valore di
SERVICE_ACCOUNT_NAME
inauthConfig
deve corrispondere al nome del tuo account di servizio.Fai clic sulla scheda Entità con accesso.
Fai clic su Concedi l'accesso.
Nella sezione Aggiungi entità, nel campo Nuove entità, inserisci
service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com
. Questa entità corrisponde al account di servizioVertex AI Extension Service Agent
.Nella sezione Assegna i ruoli, individua e seleziona il ruolo
Service Account Token Creator
. Questo ruolo include l'autorizzazioneiam.serviceAccounts.getAccessToken
.Fai clic sul pulsante Salva.
Autenticazione OIDC
Vertex AI supporta due metodi di autenticazione OIDC: token ID e account di servizio.
Token ID
Specifica authConfig
nel seguente modo:
"authConfig": {
"authType": "OIDC_AUTH",
"oidcConfig": {}
}
Lascia vuoto il campo oidcConfig
quando importi l'estensione. Se
scegli di eseguire un'estensione registrata, devi fornire un token ID nel
campo oidcConfig
della richiesta di esecuzione. Per saperne di più, consulta
Eseguire l'estensione.
Service account
Specifica authConfig
nel seguente modo:
"authConfig": {
"authType": "OIDC_AUTH",
"oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
- SERVICE_ACCOUNT_NAME: Vertex AI utilizza questo account di servizio per generare token OpenID Connect (OIDC). Vertex AI imposta il pubblico del token su API_SERVICE_URL, come definito nel file di specifica dell'API.
Segui questi passaggi per consentire a Vertex AI Extension Service Agent
di
ottenere token di accesso da SERVICE_ACCOUNT_NAME.
Vai alla pagina IAM.
Seleziona la scheda Service Account.
Fai clic sul tuo account di servizio. Il valore di
SERVICE_ACCOUNT_NAME
inauthConfig
deve corrispondere al nome del tuo account di servizio.Fai clic sulla scheda Autorizzazioni.
Fai clic su Concedi l'accesso.
Nella sezione Aggiungi entità, nel campo Nuove entità, inserisci
service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com
. Questa entità corrisponde al account di servizioVertex AI Extension Service Agent
.Nella sezione Assegna i ruoli, individua e seleziona il ruolo
Service Account Token Creator
. Questo ruolo include l'autorizzazioneiam.serviceAccounts.getOpenIdToken
.Fai clic sul pulsante Salva.
Importa l'estensione con Vertex AI
Dopo aver definito una richiesta di importazione dell'estensione, puoi importare l'estensione con Vertex AI.
Imposta le seguenti variabili della shell:
ENDPOINT="LOCATION-aiplatform.googleapis.com" URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
- PROJECT_ID: il tuo progetto.
- LOCATION: una regione a tua scelta. In caso di dubbi,
scegli
us-central1
.
Esegui questo comando
curl
per inviare la richiesta di importazione:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d @IMPORT_REQUEST.json "${URL}/extensions:import"
- IMPORT_REQUEST: il nome del file JSON che contiene la richiesta di importazione dell'estensione.
La risposta ha il seguente formato:
{ "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata", "genericMetadata": { "createTime": "[CREATE_TIME]", "updateTime": "[UPDATE_TIME]" } } }
Imposta le variabili della shell in base all'output della richiesta di importazione:
EXTENSION_ID=EXTENSION_ID IMPORT_OPERATION_ID=IMPORT_OPERATION_ID
Per controllare lo stato dell'importazione, esegui questo comando
curl
:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ "${URL}/operations/${IMPORT_OPERATION_ID}"
Gestisci le estensioni
Per elencare tutte le estensioni registrate, esegui questo comando curl
:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"
Per ottenere un'estensione, esegui il seguente comando curl
:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"
Puoi aggiornare displayName
, description
o
toolUseExamples
dell'estensione. Se specifichi toolUseExamples
quando aggiorni un'estensione, l'aggiornamento sostituisce gli esempi. Ad esempio, se hai gli esempi a
e b
, aggiorna l'estensione con l'esempio c
. L'estensione aggiornata contiene solo l'esempio c
. Per aggiornare una descrizione dell'estensione, esegui il seguente comando curl
:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
"description": "A nice tool.",
}'
Per eliminare un'estensione, esegui il seguente comando curl
:
curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}
Eseguire un'estensione
Esistono due modi per eseguire un'estensione:
execute
: questa modalità si concentra esclusivamente sull'esecuzione dell'API. L'estensione attiva l'operazione API specificata e restituisce i risultati non elaborati senza ulteriori elaborazioni.query
: questa modalità è progettata per interazioni intelligenti. che prevede più passaggi:- Richiesta del modello: la query e lo schema dell'estensione vengono forniti a
Gemini come prompt e
FunctionDeclaration
rispettivamente. - Esecuzione dell'API: se il modello determina che è necessario utilizzare uno strumento, l'estensione chiama automaticamente l'operazione API per conto del modello e recupera i risultati.
- Integrazione del modello: i risultati dell'API vengono inseriti nel modello, che li elabora per generare la risposta finale, pertinente al contesto. In
sostanza,
query
funge da agente con un solo strumento, utilizzando l'API per raggiungere i suoi obiettivi.
- Richiesta del modello: la query e lo schema dell'estensione vengono forniti a
Gemini come prompt e
Questa sezione descrive come execute
un'estensione.
Se la tua estensione utilizza l'autenticazione OAuth e un token di accesso, consulta Eseguire un'estensione con l'autenticazione OAuth e un token di accesso.
Se la tua estensione utilizza l'autenticazione OIDC e un token ID, consulta Eseguire un'estensione con l'autenticazione OIDC e un token ID.
In caso contrario, puoi eseguirlo seguendo questi passaggi:
Crea un file denominato
execute-extension.json
con i seguenti contenuti:{ "operation_id": "API_SERVICE_OPERATION_ID", "operation_params": { "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE" } }
- API_SERVICE_OPERATION_ID: l'ID dell'operazione del servizio API che vuoi eseguire. Le operazioni del servizio API sono definite nel file di specifiche API.
- API_SERVICE_INPUT_VAR: una variabile di input che corrisponde a API_SERVICE_OPERATION_ID ed è definita nel file di specifica API.
- API_SERVICE_INPUT_VALUE: un valore di input per l'estensione.
Esegui questo comando
curl
:curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \ "${URL}/extensions/${EXTENSION_ID}:execute"
La risposta ha il seguente formato:
{ "output": { "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}" } }
- API_SERVICE_OUTPUT_VAR: un parametro di output definito nel file di specifiche API e corrispondente al servizio API.
- API_SERVICE_OUTPUT_VALUE: un valore stringa che è una serializzazione dell'oggetto risposta. Se il file di specifica API definisce uno schema di risposta JSON, devi analizzare questa stringa di output in JSON autonomamente.
Esegui un'estensione con l'autenticazione OAuth e un token di accesso
Se la tua estensione utilizza l'autenticazione OAuth e un token di accesso, puoi eseguirla seguendo questi passaggi:
Crea un file denominato
execute-extension.json
con i seguenti contenuti:{ "operation_id": "API_SERVICE_OPERATION_ID", "operation_params": {...}, "runtime_auth_config": { "authType": "OAUTH", "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"} } }
- API_SERVICE_OPERATION_ID: l'ID dell'operazione del servizio API che vuoi eseguire. Le operazioni del servizio API sono definite nel file di specifiche API.
Esegui questo comando
curl
:curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \ "${URL}/extensions/${EXTENSION_ID}:execute"
Esegui un'estensione con l'autenticazione OIDC e un token ID
Se la tua estensione utilizza l'autenticazione OIDC e un token ID, puoi eseguirla seguendo questi passaggi:
Crea un file denominato
execute-extension.json
con i seguenti contenuti:{ "operation_id": "API_SERVICE_OPERATION_ID", "operation_params": {...}, "runtime_auth_config": { "authType": "OIDC_AUTH", "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"} } }
- API_SERVICE_OPERATION_ID: l'ID dell'operazione del servizio API che vuoi eseguire. Le operazioni del servizio API sono definite nel file di specifiche API.
Esegui questo comando
curl
:curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \ "${URL}/extensions/${EXTENSION_ID}:execute"