API Extensions

Le estensioni sono strumenti per i modelli linguistici di grandi dimensioni (LLM) che consentono di accedere a dati esterni, eseguire calcoli ed eseguire altre operazioni. Possono elaborare dati in tempo reale ed eseguire azioni nel mondo reale.

Vertex AI fornisce l'API Extensions per registrare, gestire ed eseguire estensioni. Vertex AI fornisce inoltre un set di estensioni predefinite dall'API Extension, tra cui l'estensione Interprete di 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 dell'estensione.

arricciatura

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 parametri

Corpo della richiesta

Parametri

displayName

Facoltativo: string

Il nome visualizzato dell'estensione che viene mostrata agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 di massimo 128 caratteri.

description

Facoltativo: string

La descrizione dell'estensione mostrata agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 di massimo 1 MB.

manifest

JsonDict|ExtensionManifest

Il file manifest dell'estensione.

runtimeConfig

Facoltativo: JsonDict|RuntimeConfig

La configurazione di runtime che controlla il comportamento di runtime dell'estensione.

Per l'estensione 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 file manifest dell'estensione.

Parametri

name

string

Il nome dell'estensione utilizzata dall'LLM per il ragionamento. Deve essere una stringa UTF-8 di massimo 128 caratteri.

description

string

La descrizione in linguaggio naturale dell'utilizzo dell'estensione. La descrizione viene mostrata all'LLM per aiutarlo a ragionare.Deve essere una stringa UTF-8 di massimo 1 MB.

apiSpec

ApiSpec

La specifica API mostrata all'LLM per ragionamento. Devi fornire una descrizione significativa e informativa. apiSpec contiene il riferimento all'URI Cloud Storage in cui è archiviato il file YAML OpenAPI. 

  "apiSpec": {
    "openApiGcsUri": string
  }

authConfig

JsonDict|AuthConfig

Il tipo di autenticazione supportato da questa estensione.

Una richiesta di importazione di estensioni deve contenere una configurazione di autenticazione.

"authConfig": {
  "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
  "googleServiceAccountConfig": {
    "serviceAccount": string
  },
}

apiSpec

La specifica API mostrata all'LLM per ragionamento.

Parametri

openApiGcsUri

string

URI Cloud Storage del file YAML OpenAPI che descrive l'API dell'estensione, ad esempio gs://vertex-extension-public/code_interpreter.yaml

authConfig

Il tipo di autenticazione supportato da questa estensione.

Parametri

authType

string

Metodo di autenticazione. Valori supportati: GOOGLE_SERVICE_ACCOUNT_AUTH.

googleServiceAccountConfig

L'estensione Interprete di codice e l'estensione Vertex AI Search supportano solo l'autenticazione dell'account di servizio Google, in cui Vertex AI utilizza l'agente di servizio dell'estensione Vertex AI per accedere alle API.

Parametri

serviceAccount

Facoltativo: string

L'account di servizio utilizzato per l'esecuzione dell'estensione. Se l'account di servizio è specificato, l'autorizzazione iam.serviceAccounts.getAccessToken deve essere concessa all'agente di servizio dell'estensione Vertex AI nell'account di servizio specificato. Se non specificato, per eseguire l'estensione viene utilizzato l'agente di servizio di estensione Vertex AI.

runtimeConfig

L'oggetto runtimeConfig contiene configurazioni aggiuntive utilizzate durante l'esecuzione dell'estensione.

Estensione Interprete di codice

Parametri

fileInputGcsBucket

Facoltativo: string

Il bucket Cloud Storage per l'input del file nell'estensione. All'agente di servizio del codice personalizzato Vertex Extension deve essere concessa l'autorizzazione roles/storage.objectViewer per questo bucket. Se non specificata, l'estensione accetta solo i contenuti del file dal corpo della richiesta e rifiuta gli input del file Cloud Storage.

fileOutputGcsBucket

Facoltativo: string

Il bucket Cloud Storage per l'output del file dall'estensione. All'agente di servizio del codice personalizzato Vertex Extension deve essere concessa l'autorizzazione roles/storage.objectUser per questo bucket. Se non specificato, i contenuti del file vengono visualizzati nel corpo della risposta.

Estensione Vertex AI Search

Parametri

servingConfigName

string

Nome della configurazione di gestione 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}

Esegui estensione

Parametri

operation_id

string

L'ID selezionato dell'operazione da eseguire in questa estensione.

operation_params

Facoltativo: JsonDict|Struct

Parametri della richiesta utilizzati per l'esecuzione di questa operazione. Il JSON deve essere sotto forma di mappa con nome del parametro come chiave e valore effettivo del parametro come valore. Ad esempio, per impostare un parametro chiamato query sulla stringa "Che cos'è Vertex AI?", puoi usare {"query": "What is Vertex AI?"}.

Esempi

Importa un'estensione per interprete di codice

Crea o registra una risorsa di estensione.

Questo esempio mostra come importare un'estensione 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 che viene mostrata agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 di massimo 128 caratteri.
  • DESCRIPTION: la descrizione dell'estensione mostrata agli utenti dall'API e dall'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. Deve descrivere l'utilizzo dell'estensione ed è essenziale affinché l'LLM esegua il ragionamento. Deve essere una stringa UTF-8 di massimo 1 MB.
  • GCS_URI: URI Cloud Storage del file YAML OpenAPI che descrive l'API dell'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:

arricciatura

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. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"

vertexai.init(project=project_id, location="us-central1")

extension = extensions.Extension.create(
    display_name="Code Interpreter",
    description="This extension generates and executes code in the specified language",
    manifest={
        "name": "code_interpreter_tool",
        "description": "Google Code Interpreter Extension",
        "api_spec": {
            "open_api_gcs_uri": "gs://vertex-extension-public/code_interpreter.yaml"
        },
        "auth_config": {
            "google_service_account_config": {},
            "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        },
    },
)

Importa con una configurazione di runtime

Crea o registra una risorsa di estensione.

Questo esempio mostra come importare un'estensione Vertex AI Search specificando RuntimeConfig.

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 che viene mostrata agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 di massimo 128 caratteri.
  • DESCRIPTION: la descrizione dell'estensione mostrata agli utenti dall'API e dall'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. Deve descrivere l'utilizzo dell'estensione ed è essenziale affinché l'LLM esegua il ragionamento. Deve essere una stringa UTF-8 di massimo 1 MB.
  • GCS_URI: URI Cloud Storage del file YAML OpenAPI che descrive l'API dell'estensione.
  • AUTH_TYPE: metodo di autenticazione. Valori supportati: GOOGLE_SERVICE_ACCOUNT_AUTH.
  • SERVING_CONFIG_NAME: nome della configurazione di gestione 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:

arricciatura

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

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,
        }
    }
)

Eseguire un'estensione

Per eseguire un'estensione, chiamala direttamente e fornisci i parametri di esecuzione nella richiesta.

In questo esempio viene eseguita l'estensione per interprete di codice generate_and_execute per ottenere la risposta alla 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 della 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:

arricciatura

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/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 saperne di più, consulta la documentazione di riferimento dell'API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# extension_id = "EXTENSION_ID"

vertexai.init(project=project_id, location="us-central1")

extension = extensions.Extension(extension_id)
response = extension.execute(
    operation_id="generate_and_execute",
    operation_params={"query": "find the max value in the list: [1,2,3,4,-5]"},
)
print(response)

Elenco estensioni

Elencare le estensioni in un progetto.

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: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions

Per inviare la richiesta, scegli una delle seguenti opzioni:

arricciatura

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, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"

vertexai.init(project=project_id, location="us-central1")

extensions = extensions.Extension.list()
print(extensions)

Ottieni un'estensione

Visualizzare i dettagli di 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.

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:

arricciatura

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, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# extension_id = "EXTENSION_ID"

vertexai.init(project=project_id, location="us-central1")

extension = extensions.Extension(extension_id)
print(extension)

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 o toolUseExamples.

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:

arricciatura

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

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

Eliminare 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:

arricciatura

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, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# extension_id = "EXTENSION_ID"

vertexai.init(project=project_id, location="us-central1")

extension = extensions.Extension(extension_id)
extension.delete()

Passaggi successivi