Importazione, gestione ed esecuzione di estensioni

Le estensioni sono connessioni ad API esterne. Possono elaborare i dati in tempo reale e connettersi ad API esterne per eseguire azioni reali. Vertex AI offre un servizio di estensione in grado di 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 le estensioni 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 di estensione, che quindi esegue l'estensione. Infine, il servizio di estensione invia il risultato di questa operazione all'applicazione, che quindi lo invia al modello.

Questo documento mostra la funzionalità chiave del servizio di estensione Vertex AI:

Per scoprire come importare ed eseguire un'estensione fornita da Google, consulta quanto segue:

Creare e importare estensioni

Questo documento presuppone che tu abbia già 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 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 i 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 di specifiche API descrive l'interfaccia di un servizio API. Devi fornire un file di specifiche delle 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 componenti. 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 degli oggetti definiti nell'oggetto percorsi. Puoi anche utilizzare l'oggetto componenti 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 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 bucket Cloud Storage o convertirlo in una stringa.

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

Dopo aver creato un file di specifiche API, puoi definire una richiesta di importazione delle estensioni in un file JSON. Una richiesta di importazione di un'estensione deve contenere un riferimento al file delle specifiche dell'API (apiSpec) e alla configurazione di 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 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 mostrato agli utenti.
  • DESCRIPTION_HUMAN: la descrizione dell'estensione mostrata 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. Devi fornire 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 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 in cui è archiviato il file delle specifiche.
    • SPECIFICATION_FILE_NAME: il nome del file delle specifiche dell'API.

  • Usa 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 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 dimostrano il funzionamento dell'estensione

Per ottenere risultati ottimali, una richiesta di importazione di un'estensione deve contenere esempi che dimostrano 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, i parametri di richiesta e di 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 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 di richiesta necessari per i valori extensionOperation e di esempio, nel formato chiave-valore. Utilizza API_SERVICE_INPUT_VAR per fornire un parametro di input definito nel file delle specifiche API e corrispondente a API_SERVICE_OPERATION_ID. Utilizza EXAMPLE_INPUT per fornire un esempio di un valore di input che corrisponde a EXAMPLE_QUERY.
  • responseParams: i parametri di risposta di extensionOperation e i valori di esempio nel formato chiave-valore. Utilizza API_SERVICE_OUTPUT_VAR per fornire un parametro di output definito nel file delle specifiche delle API e corrispondente al servizio API. Utilizza EXAMPLE_OUTPUT per fornire un esempio di valore di output corrispondente a EXAMPLE_INPUT.
  • responseSummary: un esempio di riepilogo che l'applicazione potrebbe fornire in risposta a query. Utilizza EXAMPLE_SUMMARY per fornire il testo di 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 dell'estensione.

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

Per supportare l'autenticazione delle 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 https://example.com/act?api_key=<API KEY>, API_KEY_CONFIG_NAME corrisponde a api_key.
  • API_KEY_SECRET: SecretManager risorsa di 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 la sezione Descrizione dei parametri.

Autenticazione HTTP di base

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 il ciclo di vita della risorsa SecretManager autonomamente.

Specifica authConfig come segue:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • CREDENTIAL_SECRET: SecretManager risorsa di versione del secret in cui archivia la credenziale con codifica 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 come segue:

"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 scoprire 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 usa questo account di servizio per generare token di accesso.

Esegui i seguenti passaggi per consentire a Vertex AI Extension Service Agent di ottenere i token di accesso da SERVICE_ACCOUNT_NAME.

  1. Vai alla pagina IAM.

    Vai a IAM

  2. Seleziona la scheda Account di servizio.

  3. Fai clic sul tuo account di servizio. Il valore di SERVICE_ACCOUNT_NAME in authConfig deve corrispondere al nome del tuo account di servizio.

  4. Fai clic sulla scheda Autorizzazioni.

  5. Fai clic su Concedi l'accesso.

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

  7. Nella sezione Assegna ruoli, individua e seleziona il ruolo Service Account Token Creator. Questo ruolo include l'autorizzazione iam.serviceAccounts.getAccessToken.

  8. 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 come segue:

"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 scoprire 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 usa questo account di servizio per generare token OpenID Connect (OIDC). Vertex AI imposta il pubblico per il token su API_SERVICE_URL, come definito nel file delle specifiche dell'API.

Esegui i seguenti passaggi per consentire a Vertex AI Extension Service Agent di ottenere i token di accesso da SERVICE_ACCOUNT_NAME.

  1. Vai alla pagina IAM.

    Vai a IAM

  2. Seleziona la scheda Account di servizio.

  3. Fai clic sul tuo account di servizio. Il valore di SERVICE_ACCOUNT_NAME in authConfig deve corrispondere al nome del tuo account di servizio.

  4. Fai clic sulla scheda Autorizzazioni.

  5. Fai clic su Concedi l'accesso.

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

  7. Nella sezione Assegna ruoli, individua e seleziona il ruolo Service Account Token Creator. Questo ruolo include l'autorizzazione iam.serviceAccounts.getOpenIdToken.

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

  1. 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. In caso di dubbi, 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"

    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 di 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 gli esempi a e b, poi aggiorna l'estensione con l'esempio c, l'estensione aggiornata contiene solo l'esempio c.Per aggiornare la descrizione di un'estensione, esegui questo 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 questo 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

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 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 di servizio API che vuoi eseguire. Le operazioni di servizio API sono definite nel file delle specifiche delle 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 rappresenta una serializzazione dell'oggetto di risposta. Se il file delle specifiche delle API definisce uno schema di risposta JSON, devi analizzare questa stringa di output in JSON autonomamente.

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

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 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": "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 delle 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