API Extensions

Le estensioni sono strumenti che consentono ai modelli linguistici di grandi dimensioni (LLM) 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 Extension che può registrare, gestire ed eseguire le estensioni. Vertex AI fornisce anche un insieme di estensioni predefinite dell'API Extension, tra cui l'estensione dell'interprete di codice e l'estensione di ricerca dell'agente.

Limitazioni

L'API Extension è disponibile solo nella regione us-central1.

Sintassi di esempio

Sintassi per creare una risorsa di estensione.

curl

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 dei parametri

Corpo della richiesta

Parametri

displayName

Facoltativo: string

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

description

Facoltativo: string

La descrizione dell'estensione visualizzata dagli utenti dall'API e dall'UI. Deve essere una stringa UTF-8 fino a 1 MB.

manifest

JsonDict|ExtensionManifest

Il manifest dell'estensione.

runtimeConfig

Facoltativo: JsonDict|RuntimeConfig

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

Per l'estensione dell'interprete di codice, il formato è il seguente:

  "runtimeConfig": {
    "codeInterpreterRuntimeConfig": {
        "fileInputGcsBucket": string,
        "fileOutputGcsBucket": string
    }
  }

Per l'estensione Agent Search, il formato è il seguente:

  "runtimeConfig": {
    "vertexAiSearchRuntimeConfig": {
      "servingConfigName": string,
    }
  }

manifest

Il manifest dell'estensione.

Parametri

name

string

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

description

string

La descrizione in linguaggio naturale dell'utilizzo dell'estensione. La descrizione viene mostrata all'LLM per aiutarlo a eseguire il ragionamento.Deve essere una stringa UTF-8 fino a 1 MB.

apiSpec

ApiSpec

La specifica dell'API mostrata all'LLM per il ragionamento. Devi fornire una descrizione significativa e informativa. apiSpec contiene il riferimento all'URI Cloud Storage che archivia 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 dell'API mostrata all'LLM per il ragionamento.

Parametri

openApiGcsUri

string

URI Cloud Storage del file YAML OpenAPI che descrive l'API di 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 dell'interprete di codice e l'estensione di Vertex AI Search supportano solo l'autenticazione del service account Google, in cui Vertex AI utilizza l'agente di servizio dell'estensione Vertex AI per accedere alle API.

Parametri

serviceAccount

Facoltativo: string

Il account di servizio con cui viene eseguita l'estensione. Se viene specificato il account di servizio, l'autorizzazione iam.serviceAccounts.getAccessToken deve essere concessa all'agente di servizio delle estensioni di Vertex AI sul account di servizio specificato. Se non specificato, viene utilizzato l'agente di servizio Vertex AI Extension per eseguire l'estensione.

runtimeConfig

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

Estensione Code Interpreter

Parametri

fileInputGcsBucket

Facoltativo: string

Il bucket Cloud Storage per l'input del file nell'estensione. Al service agent Vertex Extension Custom Code deve essere concessa l'autorizzazione roles/storage.objectViewer per questo bucket. Se non specificata, l'estensione accetta solo i contenuti dei file dal corpo della richiesta e rifiuta gli input dei file Cloud Storage.

fileOutputGcsBucket

Facoltativo: string

Il bucket Cloud Storage per l'output dei file dell'estensione. Al service agent Vertex Extension Custom Code deve essere concessa l'autorizzazione roles/storage.objectUser per questo bucket. Se non specificato, i contenuti del file vengono restituiti nel corpo della risposta.

Estensione Agent Search

Parametri

servingConfigName

string

Nome della configurazione di gestione della ricerca dell'agente per specificare quale risorsa di ricerca dell'agente utilizza l'estensione. Formato:

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

Esegui l'estensione

Parametri

operation_id

string

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

operation_params

Facoltativo: JsonDict|Struct

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

Esempi

Importare un'estensione di Code Interpreter

Crea o registra una risorsa di estensione.

Questo esempio mostra come importare un'estensione dell'interprete di codice.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto
  • LOCATION: la regione in cui elaborare la richiesta.
  • DISPLAY_NAME: il nome visualizzato dell'estensione mostrato agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 con un massimo di 128 caratteri.
  • DESCRIPTION: la descrizione dell'estensione visualizzata dagli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 fino a 1 MB.
  • MANIFEST_NAME: Il nome dell'estensione utilizzata dal 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 per il ragionamento del modello LLM. Deve essere una stringa UTF-8 fino a 1 MB.
  • GCS_URI: l'URI Cloud Storage del file YAML OpenAPI che descrive l'API di 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 di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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, quindi esegui il comando seguente:

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

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-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",
        },
    },
)
print(extension.resource_name)
# Example response:
# projects/123456789012/locations/us-central1/extensions/12345678901234567

Importare con una configurazione di runtime

Crea o registra una risorsa di estensione.

Questo esempio mostra come importare un'estensione di ricerca dell'agente specificando RuntimeConfig.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: .
  • LOCATION: la regione in cui elaborare la richiesta.
  • DISPLAY_NAME: il nome visualizzato dell'estensione mostrato agli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 con un massimo di 128 caratteri.
  • DESCRIPTION: la descrizione dell'estensione visualizzata dagli utenti dall'API e dall'interfaccia utente. Deve essere una stringa UTF-8 fino a 1 MB.
  • MANIFEST_NAME: Il nome dell'estensione utilizzata dal 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 per il ragionamento del modello LLM. Deve essere una stringa UTF-8 fino a 1 MB.
  • GCS_URI: l'URI Cloud Storage del file YAML OpenAPI che descrive l'API di estensione.
  • AUTH_TYPE: Metodo di autenticazione. Valori supportati: GOOGLE_SERVICE_ACCOUNT_AUTH.
  • SERVING_CONFIG_NAME: nome della configurazione di pubblicazione di Vertex AI Search per specificare quale risorsa Vertex AI Search utilizza l'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 di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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, quindi esegui il comando seguente:

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

Esegui un'estensione

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

Questo esempio esegue l'estensione dell'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, apporta le sostituzioni seguenti:

  • PROJECT_ID: .
  • 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 di richiesta per eseguire l'operazione in formato coppia 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 di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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, quindi esegui il comando seguente:

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

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "your-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)
# Example response:
# {
#     "generated_code": "```python\n# Find the maximum value in the list\ndata = [1, 2,..", ..
#     "execution_result": "The maximum value in the list is: 4\n",
#     "execution_error": "",
#     "output_files": [],
# }

Elenco estensioni

Elenca le estensioni in un progetto.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: .
  • 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 di queste opzioni:

curl

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

import vertexai
from vertexai.preview import extensions

# TODO (developer):Update project_id
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extensions_list = extensions.Extension.list()
print(extensions_list)
# Example response:
# [<vertexai.extensions._extensions.Extension object at 0x76e8ced37af0>
# resource name: projects/[PROJECT_ID]/locations/us-central1/extensions/1234567890123456]

Ottenere un'estensione

Visualizza i dettagli di un'estensione.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: .
  • 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 di queste opzioni:

curl

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

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "your-extension-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)
print(extension.resource_name)
# Example response:
# projects/[PROJECT_ID]/locations/us-central1/extensions/12345678901234567

Aggiornare un'estensione

Aggiorna un'estensione.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: .
  • 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 di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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, quindi esegui il comando seguente:

$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

Elimina un'estensione.

Questo esempio elimina l'estensione associata all'ID estensione.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: .
  • 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 di queste opzioni:

curl

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

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "extension_id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)
extension.delete()
# Example response:
# ...
# Extension resource projects/[PROJECT_ID]/locations/us-central1/extensions/[extension_id] deleted.

Passaggi successivi