Questa pagina è stata tradotta dall'API Cloud Translation.

Creare ed eseguire estensioni

Questo documento illustra le funzionalità principali del servizio di estensioni Vertex AI:

Come creare e importare estensioni.
Come gestire le estensioni.
Come eseguire le estensioni.

Per scoprire come importare ed eseguire un'estensione fornita da Google, consulta la seguenti:

Utilizza l'estensione Interprete di codice per generare ed eseguire le API nel tuo codice.
Utilizza l'estensione Vertex AI Search per accedere ai corpora dei siti web e ai dati non strutturati e per eseguire ricerche al loro interno al fine di fornire risposte pertinenti alle domande in linguaggio naturale.

Creare e importare estensioni

In questo documento si presuppone che tu abbia già un servizio API in esecuzione che può un'estensione. Per creare un'estensione, devi definirne l'interfaccia con un'API esterna in un file di specifiche API. Devi carica questo file di specifiche in un bucket Cloud Storage oppure 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 delle specifiche dell'API

Chiunque può creare un'estensione tramite file che definiscono e descrivono gli endpoint API delle estensioni. Gli endpoint API possono essere pubblici o privati e ospitati su qualsiasi cloud o on-premise.

Un file di specifiche API descrive l'interfaccia di un servizio API. Devi fornire un file di specifica dell'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. L'estensione Vertex AI non supporta più server.
```
servers:
  - url: API_SERVICE_URL
```

Un oggetto paths. Questo oggetto deve descrivere le varie operazioni fornite dal servizio API e l'input i parametri corrispondenti a ciascuna 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 components. Questo oggetto è facoltativo. Puoi utilizzare l'oggetto components per definire oggetti riutilizzabili. Per Ad esempio, puoi utilizzare l'oggetto componenti per fornire una definizione schemi di oggetti definiti nell'oggetto percorsi. Puoi anche utilizzare l'oggetto components per descrivere i parametri di output del servizio API.
```
components:
  schemas:
    Result:
      ...
      properties:
        API_SERVICE_OUTPUT_VAR:
        ...
```

Per scoprire di più su OpenAPI, consulta la specifica OpenAPI.

L'esempio seguente è un file di specifiche dell'API per un servizio API che dice "ciao" 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 delle specifiche

Puoi caricare il file delle specifiche in un file di Cloud Storage un bucket o convertirlo in una stringa.

Se carichi il file delle specifiche in un bucket Cloud Storage, concedi il parametro Vertex AI Extension Service Agent account di servizio (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com) il Visualizzatore oggetti Storage. 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.

Definire una richiesta di importazione di estensioni

Dopo aver creato un file di specifiche API, puoi definire un'importazione delle estensioni richiesta in un file JSON. Una richiesta di importazione dell'estensione deve contenere un riferimento a il file delle specifiche dell'API (apiSpec) e la configurazione dell'autenticazione (authConfig). Collegare l'estensione a un modello linguistico di grandi dimensioni (LLM) per vedere come funziona l'estensione, includi il parametro facoltativo toolUseExamples. Se vuoi eseguire solo l'estensione, non includere toolUseExamples .

Una richiesta di importazione di un'estensione 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 agli utenti.
DESCRIPTION_HUMAN: la descrizione dell'estensione che mostrati agli utenti.
EXTENSION_NAME_LLM: il nome dell'estensione utilizzata dall'LLM per il ragionamento.
DESCRIPTION_LLM: la descrizione dell'estensione utilizzata dall'LLM per il ragionamento. Fornisci una descrizione significativa e informativa.

Riferimento al file delle specifiche dell'API

La richiesta di importazione dell'estensione deve contenere un riferimento al file delle specifiche dell'API. Puoi fornire il file delle specifiche in due modi:

Usa openApiGcsUri per passare 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 memorizza il file delle specifiche.
- SPECIFICATION_FILE_NAME: il nome del file delle specifiche dell'API.
Utilizza openApiYaml per passare il file YAML come stringa.

Configurazione autenticazione

Le estensioni possono essere esclusivamente pubbliche, disponibili per l'uso da qualsiasi utente oppure private disponibili per gli utenti autorizzati all'interno di una o più organizzazioni.

Una richiesta di importazione dell'estensione deve contenere una configurazione di autenticazione. Puoi scegliere tra i seguenti metodi di autenticazione:

NO_AUTH: nessuna autenticazione
API_KEY_AUTH: autenticazione con chiave API
HTTP_BASIC_AUTH: autenticazione di base HTTP
OAUTH: autenticazione OAuth
OIDC_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 dell'estensione deve contenere esempi che illustrino il funzionamento dell'estensione. Usa il parametro toolUseExamples per fornisci 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, i parametri di richiesta e di risposta sono entrambi 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 per rispondere al query. Utilizza API_SERVICE_OPERATION_ID per fornire l'ID di un dell'estensione definita nel file delle specifiche delle API.
displayName: un nome visualizzato per l'esempio. Utilizza le funzionalità di EXAMPLE_DISPLAY_NAME per fornire una breve descrizione.
requestParams: i parametri di richiesta necessari per extensionOperation e valori di esempio, in formato chiave-valore. Utilizza API_SERVICE_INPUT_VAR per fornire un parametro di input definito nel file di specifiche dell'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 dei valori extensionOperation e di esempio in formato chiave-valore. Utilizza API_SERVICE_OUTPUT_VAR per fornire un parametro di output definito nel file delle specifiche dell'API e corrispondente al servizio API. Utilizza EXAMPLE_OUTPUT per fornire un esempio di un valore di output corrispondente a EXAMPLE_INPUT.
responseSummary: un esempio di riepilogo che l'applicazione potrebbe fornire in risposta al query. Utilizza EXAMPLE_SUMMARY per fornire il testo del riepilogo.

Di seguito è riportato un esempio di toolUseExamples per un servizio API che dice "ciao" 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 di un'estensione.

Se l'estensione non richiede l'autenticazione, imposta la variabile authType a NO_AUTH:

"authConfig": {
  "authType": "NO_AUTH"
}

Se l'estensione richiede l'autenticazione, devi impostare l'autenticazione digita la variabile authType e indica 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 delle chiavi API, Vertex AI si integra con SecretManager per l'archiviazione e l'accesso alle chiavi. La piattaforma Vertex AI Extensions non archivia direttamente i dati secret. È tua responsabilità gestire il ciclo di vita della risorsa SecretManager.

Specifica authConfig come segue:

"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 a api_key.
API_KEY_SECRET: risorsa versione secret SecretManager che memorizza 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 finestra HTTP richiesta. 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 HTTP di base

Per supportare l'autenticazione di base HTTP, Vertex AI si integra con SecretManager per lo stoccaggio e l'accesso alle secret. La piattaforma Vertex AI Extensions non archivia direttamente i dati secret. Devi gestire autonomamente il ciclo di vita della risorsa SecretManager.

Specifica authConfig come segue:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}

CREDENTIAL_SECRET: risorsa della versione della secret SecretManager che immagazzina 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 un account di servizio.

Token di accesso

Specifica authConfig come segue:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {}
}

Lascia vuoto il campo oauthConfig quando importi l'estensione. Se scelgo di eseguire un'estensione registrata, devo fornire un token di accesso nel campo oauthConfig della richiesta di esecuzione. Per saperne di più, consulta Eseguire l'estensione.

Service account

Specifica authConfig come segue:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}

SERVICE_ACCOUNT_NAME: Vertex AI utilizza questo account di servizio per generare token di accesso.

Procedi come descritto di seguito per consentire all'app Vertex AI Extension Service Agent di ricevi token di accesso da SERVICE_ACCOUNT_NAME.

Vai alla pagina IAM.

Vai a IAM
Seleziona la scheda Account di servizio.
Fai clic sul tuo account di servizio. Il valore di SERVICE_ACCOUNT_NAME in authConfig 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 all'account di servizio Vertex AI Extension Service Agent.
Nella sezione Assegna ruoli, trova e seleziona il ruolo Service Account Token Creator. Questo ruolo include Autorizzazione iam.serviceAccounts.getAccessToken.
Fai clic sul pulsante Salva.

Autenticazione OIDC

Vertex AI supporta due metodi di autenticazione OIDC: token di identità e account di servizio.

Token ID

Specifica authConfig come segue:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {}
}

Lascia vuoto il campo oidcConfig quando importi l'estensione. Se esegui 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 come segue:

"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 segmento di pubblico per il token su API_SERVICE_URL, come definito nel file di specifiche dell'API.

Procedi come descritto di seguito per consentire all'app Vertex AI Extension Service Agent di ricevi token di accesso da SERVICE_ACCOUNT_NAME.

Vai alla pagina IAM.

Vai a IAM
Seleziona la scheda Account di servizio.
Fai clic sul tuo account di servizio. Il valore di SERVICE_ACCOUNT_NAME in authConfig 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 all'account di servizio Vertex AI Extension Service Agent.
Nella sezione Assegna ruoli, trova e seleziona il ruolo Service Account Token Creator. Questo ruolo include l'autorizzazione iam.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 di 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. Se hai dubbi, scegli us-central1.

Esegui il seguente 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 di 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 il seguente 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 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"

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 dell'estensione, l'aggiornamento sostituirà gli esempi. Ad esempio, se hai gli esempi a e b, aggiorna l'estensione con l'esempio c e l'estensione aggiornata conterrà solo l'esempio c. Per aggiornare la descrizione di un'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}

Esegui un'estensione

Esistono due modi per eseguire un'estensione:

execute: questo si concentra esclusivamente sull'esecuzione dell'API. L'estensione attiva lo stato specificato dell'API e restituisce i risultati non elaborati senza ulteriori elaborazioni.
query: questa modalità è progettato per interazioni intelligenti. che prevede più passaggi:
- Richiesta modello: la query e lo schema dell'estensione vengono forniti a Gemini come prompt FunctionDeclaration rispettivamente.
- Esecuzione dell'API: se il modello determina che è necessario l'utilizzo dello strumento, l'estensione chiama automaticamente l'operazione dell'API per conto del modello e recupera i risultati.
- Integrazione del modello: i risultati dell'API vengono inseriti nel modello, che le elabora per generare la risposta finale pertinente in base al contesto. Nella In sostanza, query si comporta come un agente con un singolo strumento, utilizzando l'API per raggiungere i propri obiettivi.

Questa sezione descrive come execute un'estensione.

Se l'estensione utilizza l'autenticazione OAuth e un token di accesso, consulta: Esegui 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 autenticazione OIDC e un token ID.

In caso contrario, puoi eseguirlo seguendo questa procedura:

Crea un file denominato execute-extension.json con il seguente contenuto:
```
{
  "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 file delle specifiche API.
- API_SERVICE_INPUT_VAR: una variabile di input che corrisponde a API_SERVICE_OPERATION_ID ed è definito nel file delle specifiche delle 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 in file delle specifiche dell'API e corrisponde all'API completamente gestito di Google Cloud.
- API_SERVICE_OUTPUT_VALUE: un valore di stringa che è una serializzazione dell'oggetto risposta. Se il file di specifiche delle API definisce Schema di risposta JSON, devi analizzare questa stringa di output in JSON su la tua.

Eseguire un'estensione con autenticazione OAuth e un token di accesso

Se l'estensione utilizza l'autenticazione OAuth e un token di accesso, puoi eseguirla seguendo i passaggi che seguono:

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 di servizio API che vuoi eseguire. Le operazioni del servizio API sono definite file delle 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 autenticazione OIDC e un token ID

Se l'estensione utilizza l'autenticazione OIDC e un token di identità, puoi eseguire la seguendo questi passaggi:

Crea un file denominato execute-extension.json con il seguente contenuto:

{
  "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 di servizio API che vuoi eseguire. Le operazioni di servizio API sono definite nel file delle specifiche dell'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"

Passaggi successivi

Crea ed esegui il deployment del tuo framework di orchestrazione LLM.