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 Vertex AI Search.

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 Vertex AI 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 al modello 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, per eseguire l'estensione viene utilizzato l'agente di servizio Vertex AI Extension.

runtimeConfig

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

Estensione Interprete codice

Parametri

fileInputGcsBucket

(Facoltativo) string

Il bucket Cloud Storage per l'input del file nell'estensione. All'agente di servizio del codice personalizzato dell'estensione Vertex 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 del file dall'estensione. All'agente di servizio del codice personalizzato dell'estensione Vertex 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 Vertex AI Search

Parametri

servingConfigName

string

Nome della configurazione di pubblicazione di Vertex AI Search per specificare quale risorsa di Vertex AI Search 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 utilizzati per eseguire questa operazione. Il JSON deve essere sotto forma di mappa con il nome del parametro come chiave e il valore effettivo del parametro 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 seguenti sostituzioni:

  • 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 nell'API e nell'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, 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 Python, consulta Installare l'SDK Vertex AI 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 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 Vertex AI Search specificando RuntimeConfig.

REST

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

  • 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 nell'API e nell'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, 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,
        }
    }
)

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 seguenti sostituzioni:

  • 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, 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 Python, consulta Installare l'SDK Vertex AI 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 = "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 seguenti sostituzioni:

  • 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 documentazione di riferimento dell'API Python.

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 seguenti sostituzioni:

  • 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 documentazione di riferimento dell'API Python.

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 seguenti sostituzioni:

  • 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, 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

Elimina un'estensione.

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

REST

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

  • 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 documentazione di riferimento dell'API Python.

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