Importa, gestisci ed esegui estensioni

Le estensioni sono connessioni ad API esterne. Possono elaborare i dati in tempo reale e connettersi ad API esterne. Vertex AI offre un servizio di estensione con cui importare, gestire ed eseguire estensioni.

Questo servizio di estensione può essere collegato a un'applicazione che elabora le query degli utenti e comunica con un LLM. Il servizio di estensione può fornire all'applicazione un insieme di estensioni e le operazioni che possono eseguire. Ogni volta che l'applicazione riceve una query dell'utente, fornisce queste informazioni all'LLM. Se il modello stabilisce che deve delegare l'elaborazione delle query a un'estensione, fornisce una chiamata dell'estensione richiesta e i valori dei parametri associati. L'applicazione inoltra questa richiesta al servizio dell'estensione, che la esegue. Infine, il servizio di estensione invia il risultato di questa operazione all'applicazione, che lo invia di nuovo al modello.

Questo documento mostra le funzionalità principali del servizio di estensione 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 quanto segue:

• Utilizza l'estensione interprete di codice per generare ed eseguire il codice.
• Utilizza l'estensione Vertex AI Search per accedere ai corpus e ai dati non strutturati del sito web e cercarli in modo da fornire risposte pertinenti alle domande in merito al 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 definirne l'interfaccia con un'API esterna in un file delle specifiche API. Devi caricare questo file di specifica in un bucket Cloud Storage o convertirlo in stringa. Devi quindi definire un manifest dell'estensione, includere il file di specifica e inviare una richiesta di registrazione al servizio dell'estensione.

Creare un file delle specifiche 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 oppure on-premise.

Un file delle specifiche dell'API descrive l'interfaccia di un servizio API. Devi fornire un file delle specifiche API in formato YAML che sia 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 paths. Questo oggetto deve descrivere le varie operazioni fornite dal servizio API e i parametri di input 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 componenti per definire oggetti riutilizzabili. Ad esempio, puoi utilizzare l'oggetto componenti per fornire una definizione degli schemi di oggetti definiti nell'oggetto percorsi. Puoi usare l'oggetto componenti anche 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 specifica dell'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 delle specifiche

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

Se carichi il file di specifica in un bucket Cloud Storage, concedi all'account di servizio Vertex AI Extension Service Agent ([email protected]) il ruolo Visualizzatore oggetti Storage. Per scoprire come elencare i bucket nel progetto, consulta Elenco dei bucket. Per informazioni su come copiare un oggetto in un bucket Cloud Storage, consulta Copiare, rinominare e spostare oggetti.

Definisci una richiesta di importazione delle estensioni

Dopo aver creato un file di specifica API, puoi definire una richiesta di importazione delle estensioni in un file JSON. Una richiesta di importazione delle estensioni deve contenere un riferimento al file delle specifiche dell'API (apiSpec) e alla configurazione dell'autenticazione (authConfig). Per connettere l'estensione a un modello linguistico di grandi dimensioni (LLM), 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 che viene mostrata agli utenti.
• DESCRIPTION_HUMAN: la descrizione dell'estensione mostrata agli utenti.
• EXTENSION_NAME_LLM: il nome dell'estensione utilizzato dall'LLM per il ragionamento.
• DESCRIPTION_LLM: la descrizione dell'estensione utilizzata dall'LLM per il ragionamento. Devi fornire una descrizione significativa e informativa.

Riferimento al file delle specifiche dell'API

La richiesta di importazione delle estensioni deve contenere un riferimento al file delle specifiche API. Puoi fornire il file di specifica 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 in cui è archiviato il file delle specifiche.
  • SPECIFICATION_FILE_NAME: il nome del file delle specifiche API.

• Usa openApiYaml per trasmettere 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 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, vedi Specificare una configurazione di autenticazione.

Esempi che dimostrano il funzionamento dell'estensione

Per ottenere risultati ottimali, una richiesta di importazione delle estensioni deve contenere esempi che ne dimostrano il funzionamento. Utilizza il parametro toolUseExamples per fornire questi esempi.

Il seguente codice mostra il formato 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 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ò utilizzare questa estensione. Utilizza EXAMPLE_QUERY per fornire il testo della query.
• extensionOperation: un'operazione di estensione adatta a rispondere a query. Utilizza API_SERVICE_OPERATION_ID per fornire l'ID di un'operazione di estensione definita nel file delle specifiche API.
• displayName: un nome visualizzato per l'esempio. Utilizza EXAMPLE_DISPLAY_NAME per fornire una breve descrizione.
• requestParams: i parametri della richiesta necessari per i valori extensionOperation e di esempio in formato chiave-valore. Utilizza API_SERVICE_INPUT_VAR per fornire un parametro di input definito nel file delle specifiche API e che corrisponde a API_SERVICE_OPERATION_ID. Usa EXAMPLE_INPUT per fornire un esempio di valore di input che corrisponde a EXAMPLE_QUERY.
• responseParams: i parametri di risposta dei valori extensionOperation e di esempio nel formato chiave-valore. Utilizza API_SERVICE_OUTPUT_VAR per fornire un parametro di output definito nel file delle specifiche API e che corrisponda al servizio API. Usa EXAMPLE_OUTPUT per fornire un esempio di valore di output che corrisponda a EXAMPLE_INPUT.
• responseSummary: un esempio di riepilogo che l'applicazione potrebbe fornire in risposta al query. Usa EXAMPLE_SUMMARY per fornire il testo di riepilogo.

Di seguito è riportato un esempio di toolUseExamples per un servizio API che indica "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 delle estensioni.

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

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

Se l'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 le chiavi API, Vertex AI si integra con SecretManager per l'archiviazione e l'accesso dei secret. La piattaforma Vertex AI Extensions non archivia direttamente i dati secret. Hai la responsabilità di gestire il ciclo di vita della tua 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 http://example.com/act?api_key=<API KEY>, API_KEY_CONFIG_NAME corrisponde a api_key.
• API_KEY_SECRET: SecretManager risorsa della versione del secret in cui è archiviata 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 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 dei secret. La piattaforma Vertex AI Extensions non archivia direttamente i dati secret. Devi gestire autonomamente il ciclo di vita della tua risorsa SecretManager.

Specifica authConfig come segue:

"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.

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

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

Autenticazione OIDC

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

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

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

Importa l'estensione con Vertex AI

Dopo aver definito una richiesta di importazione delle estensioni, puoi importarla con Vertex AI.

1. Imposta le seguenti variabili shell:

   ENDPOINT="LOCATION-aiplatform.googleapis.com"
   URL="http://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
   

   • PROJECT_ID: il tuo progetto.
   • LOCATION: una regione a tua scelta. Se non sei sicuro, scegli us-central1.

2. 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 delle estensioni.

   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]"
       }
     }
   }
   

3. Imposta le variabili shell in base all'output della richiesta di importazione:

   EXTENSION_ID=EXTENSION_ID
   IMPORT_OPERATION_ID=IMPORT_OPERATION_ID
   

4. 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 questo 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 degli esempi a e b, aggiorna l'estensione con l'esempio c, l'estensione aggiornata contiene solo l'esempio c.Per aggiornare la descrizione di un'estensione, esegui il comando curl seguente:

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 questo 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

Se l'estensione utilizza l'autenticazione OAuth e un token di accesso, consulta Eseguire un'estensione con l'autenticazione OAuth e un token di accesso.

Se l'estensione utilizza l'autenticazione OIDC e un token ID, consulta Eseguire un'estensione con autenticazione OIDC e un token ID.

In caso contrario, puoi eseguirla seguendo questa procedura:

1. 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 dei servizi API sono definite nel file delle specifiche API.
   • API_SERVICE_INPUT_VAR: una variabile di input che corrisponde a API_SERVICE_OPERATION_ID ed è definita nel file delle specifiche API.
   • API_SERVICE_INPUT_VALUE: un valore di input per l'estensione.

2. 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 delle specifiche API e corrispondente al servizio API.
   • API_SERVICE_OUTPUT_VALUE: un valore stringa che è una serializzazione dell'oggetto risposta. Se il file delle specifiche API definisce uno schema di risposta JSON, devi analizzare manualmente la stringa di output in JSON.

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

Se l'estensione utilizza l'autenticazione OAuth e un token di accesso, puoi eseguirla seguendo questa procedura:

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

   {
     "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 dei servizi API sono definite nel file delle specifiche API.

2. 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"
   

Eseguire un'estensione con l'autenticazione OIDC e un token ID

Se l'estensione utilizza l'autenticazione OIDC e un token ID, puoi eseguirla seguendo questi passaggi:

1. 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 del servizio API che vuoi eseguire. Le operazioni dei servizi API sono definite nel file delle specifiche API.

2. 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 framework di orchestrazione LLM.