API Extensions

Las extensiones son herramientas que permiten a los modelos de lenguaje extensos (LLMs) acceder a datos externos, realizar cálculos y llevar a cabo otras operaciones. Pueden procesar datos en tiempo real y llevar a cabo acciones en el mundo real.

Vertex AI proporciona la API Extension, que puede registrar, gestionar y ejecutar extensiones. Vertex AI también proporciona un conjunto de extensiones prediseñadas de la API Extension, como la extensión de intérprete de código y la extensión de Vertex AI Search.

Limitaciones

La API Extension solo está disponible en la región us-central1.

Sintaxis de ejemplo

Sintaxis para crear un recurso de extensión.

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
)

Lista de parámetros

Cuerpo de la solicitud

Parámetros

displayName

Opcional: string

Nombre visible de la extensión que se muestra a los usuarios desde la API y la interfaz de usuario. Debe ser una cadena UTF-8 de hasta 128 caracteres.

description

Opcional: string

Descripción de la extensión que se muestra a los usuarios desde la API y la interfaz de usuario. Debe ser una cadena UTF-8 de hasta 1 MB.

manifest

JsonDict|ExtensionManifest

El manifiesto de la extensión.

runtimeConfig

Opcional: JsonDict|RuntimeConfig

La configuración del tiempo de ejecución que controla el comportamiento del tiempo de ejecución de la extensión.

En el caso de la extensión de intérprete de código, el formato es el siguiente:

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

En el caso de la extensión Vertex AI Search, el formato es el siguiente:

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

manifest

El manifiesto de la extensión.

Parámetros

name

string

El nombre de la extensión que usa el LLM para razonar. Debe ser una cadena UTF-8 de hasta 128 caracteres.

description

string

Descripción en lenguaje natural del uso de la extensión. La descripción se muestra al LLM para ayudarle a razonar.Debe ser una cadena UTF-8 de hasta 1 MB.

apiSpec

ApiSpec

La especificación de la API que se muestra al LLM para el razonamiento. Debes proporcionar una descripción significativa e informativa. apiSpec contiene la referencia al URI de Cloud Storage que almacena el archivo YAML de OpenAPI.

  "apiSpec": {
    "openApiGcsUri": string
  }

authConfig

JsonDict|AuthConfig

El tipo de autenticación admitido por esta extensión.

Una solicitud de importación de extensiones debe contener una configuración de autenticación.

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

apiSpec

La especificación de la API que se muestra al LLM para el razonamiento.

Parámetros

openApiGcsUri

string

URI de Cloud Storage del archivo YAML de OpenAPI que describe la API de extensión, como gs://vertex-extension-public/code_interpreter.yaml

authConfig

El tipo de autenticación admitido por esta extensión.

Parámetros

authType

string

Método de autenticación. Valores admitidos: GOOGLE_SERVICE_ACCOUNT_AUTH.

googleServiceAccountConfig

La extensión de intérprete de código y la extensión de búsqueda de Vertex AI solo admiten la autenticación de cuentas de servicio de Google, en la que Vertex AI usa el agente de servicio de extensiones de Vertex AI para acceder a las APIs.

Parámetros

serviceAccount

Opcional: string

La cuenta de servicio con la que se ejecuta la extensión. Si se especifica la cuenta de servicio, se debe conceder el permiso iam.serviceAccounts.getAccessToken al agente de servicio de extensión de Vertex AI en la cuenta de servicio especificada. Si no se especifica, se usa el agente del servicio de extensiones de Vertex AI para ejecutar la extensión.

runtimeConfig

El objeto runtimeConfig contiene configuraciones adicionales que se usan al ejecutar la extensión.

Extensión de intérprete de código

Parámetros

fileInputGcsBucket

Opcional: string

El segmento de Cloud Storage del archivo de entrada de la extensión. Se debe conceder el permiso roles/storage.objectViewer a este segmento al agente de servicio de código personalizado de la extensión Vertex. Si no se especifica, la extensión solo acepta el contenido de los archivos del cuerpo de la solicitud y rechaza las entradas de archivos de Cloud Storage.

fileOutputGcsBucket

Opcional: string

Segmento de Cloud Storage para el archivo de salida de la extensión. Se debe conceder el permiso roles/storage.objectUser a este segmento al agente de servicio de código personalizado de la extensión Vertex. Si no se especifica, el contenido del archivo se muestra en el cuerpo de la respuesta.

Extensión Vertex AI Search

Parámetros

servingConfigName

string

Nombre de la configuración de servicio de Vertex AI Search para especificar qué recurso de Vertex AI Search usa la extensión. Formato:

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

Ejecutar extensión

Parámetros

operation_id

string

El ID seleccionado de la operación que se va a ejecutar en esta extensión.

operation_params

Opcional: JsonDict|Struct

Parámetros de solicitud que se usan para ejecutar esta operación. El JSON debe tener la forma de un mapa con el nombre del parámetro como clave y el valor del parámetro como valor. Por ejemplo, para asignar el valor de cadena "¿Qué es Vertex AI?" a un parámetro llamado query, puedes usar {"query": "What is Vertex AI?"}.

Ejemplos

Importar una extensión de intérprete de código

Crea o registra un recurso de extensión.

En este ejemplo se muestra cómo importar una extensión de intérprete de código.

.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto.
  • LOCATION: la región en la que se procesará la solicitud.
  • DISPLAY_NAME: el nombre visible de la extensión que se muestra a los usuarios desde la API y la interfaz de usuario. Debe ser una cadena UTF-8 de hasta 128 caracteres.
  • DESCRIPTION: la descripción de la extensión que se muestra a los usuarios desde la API y la interfaz de usuario. Debe ser una cadena UTF-8 de hasta 1 MB.
  • MANIFEST_NAME: El nombre de la extensión que usa el LLM para razonar. Debe ser una cadena UTF-8 de hasta 128 caracteres.
  • MANIFEST_DESCRIPTION: la descripción en lenguaje natural que se muestra al LLM. Debe describir el uso de la extensión y es esencial para que el LLM pueda razonar. Debe ser una cadena UTF-8 de hasta 1 MB.
  • GCS_URI: URI de Cloud Storage del archivo YAML de OpenAPI que describe la API de extensión.
  • AUTH_TYPE: método de autenticación. Valores admitidos: GOOGLE_SERVICE_ACCOUNT_AUTH.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "manifest": {
    "name": "NAME",
    "description": "MANIFEST_DESCRIPTION",
    "apiSpec": {
      "openApiGcsUri": "GCS_URI",
    },
    "authConfig": {
      "authType": "AUTH_TYPE",
      "googleServiceAccountConfig": {}
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la 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

Importar con una configuración de tiempo de ejecución

Crea o registra un recurso de extensión.

En este ejemplo se muestra cómo importar una extensión de Vertex AI Search especificando RuntimeConfig.

.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • LOCATION: la región en la que se procesará la solicitud.
  • DISPLAY_NAME: el nombre visible de la extensión que se muestra a los usuarios desde la API y la interfaz de usuario. Debe ser una cadena UTF-8 de hasta 128 caracteres.
  • DESCRIPTION: la descripción de la extensión que se muestra a los usuarios desde la API y la interfaz de usuario. Debe ser una cadena UTF-8 de hasta 1 MB.
  • MANIFEST_NAME: El nombre de la extensión que usa el LLM para razonar. Debe ser una cadena UTF-8 de hasta 128 caracteres.
  • MANIFEST_DESCRIPTION: la descripción en lenguaje natural que se muestra al LLM. Debe describir el uso de la extensión y es esencial para que el LLM pueda razonar. Debe ser una cadena UTF-8 de hasta 1 MB.
  • GCS_URI: URI de Cloud Storage del archivo YAML de OpenAPI que describe la API de extensión.
  • AUTH_TYPE: método de autenticación. Valores admitidos: GOOGLE_SERVICE_ACCOUNT_AUTH.
  • SERVING_CONFIG_NAME: nombre de la configuración de servicio de Vertex AI Search para especificar qué recurso de Vertex AI Search usa la extensión. Formato: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "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,
      }
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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,
        }
    }
)

Ejecutar una extensión

Para ejecutar una extensión, llama directamente a la extensión y proporciona los parámetros de ejecución en la solicitud.

En este ejemplo se ejecuta la extensión del intérprete de código generate_and_execute para obtener la respuesta a la consulta find the max value in the list: [1,2,3,4,-5].

.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • LOCATION: la región en la que se procesará la solicitud.
  • EXTENSION_ID: el ID de la extensión.
  • OPERATION_ID: el ID seleccionado de la operación que se va a ejecutar en esta extensión.
  • QUERY: los parámetros de solicitud para ejecutar la operación en formato de clave-valor, {"query": "What is Vertex AI?"}.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute

Cuerpo JSON de la solicitud:

{
  "operation_id": "OPERATION_ID",
  "operation_params": {
    "query": "QUERY",
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la 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": [],
# }

Mostrar extensiones

Muestra las extensiones de un proyecto.

.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • LOCATION: la región en la que se procesará la solicitud.
  • EXTENSION_ID: el ID de la extensión.

Método HTTP y URL:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions"

PowerShell

Ejecuta el comando siguiente:

$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

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la 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]

Obtener una extensión

Obtener los detalles de una extensión.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • LOCATION: la región en la que se procesará la solicitud.
  • EXTENSION_ID: el ID de la extensión.

Método HTTP y URL:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

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

Ejecuta el comando siguiente:

$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

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la 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

Actualizar una extensión

Actualiza una extensión.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • LOCATION: la región en la que se procesará la solicitud.
  • EXTENSION_ID: el ID de la extensión.
  • UPDATE_MASK: el parámetro que se va a actualizar. Valores aceptados: displayName, description o toolUseExamples.

Método HTTP y URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"

Cuerpo JSON de la solicitud:

{
  "description": "UPDATE_MASK",
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Eliminar extensión

Elimina una extensión.

En este ejemplo, se elimina la extensión asociada al ID de extensión.

.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • LOCATION: la región en la que se procesará la solicitud.
  • EXTENSION_ID: el ID de la extensión.

Método HTTP y URL:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

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

Ejecuta el comando siguiente:

$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

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la 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.

Siguientes pasos