API de Extensions

Las extensiones son herramientas para que los modelos de lenguaje grandes accedan a datos externos, ejecuten cálculos y realicen otras operaciones. Pueden procesar datos en tiempo real y realizar acciones reales. Vertex AI proporciona la API de Extension que puede registrar, administrar y ejecutar extensiones. Vertex AI también proporciona un conjunto de extensiones compiladas previamente de la API de Extension, incluidas la extensión de intérprete de código, la extensión de Vertex AI Search, entre otras.

Limitación

• Solo está disponible en la región "us-central1".

Importa la extensión

Crea o registra un recurso de extensión.

Sintaxis

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import

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

Parámetros
displayName	Opcional: string El nombre visible de la extensión que se muestra a los usuarios desde la API y la IU. Debe ser una cadena UTF-8 de hasta 128 caracteres.
description	Opcional: string La descripción de la extensión que se muestra a los usuarios desde la API y la IU. Debe ser una cadena UTF-8 de hasta 1 MB.
manifest	JsonDict|ExtensionManifest Manifiesto de la extensión.
runtimeConfig	Opcional: JsonDict|RuntimeConfig Configuración del entorno de ejecución que controla el comportamiento del entorno de ejecución de esta extensión.

ExtensionManifest

Parámetros
name	string El nombre de la extensión que usa el LLL para razonar. Debe ser una cadena UTF-8 de hasta 128 caracteres.
description	string La descripción en lenguaje natural que se muestra al LLM. Debería describir el uso de la extensión y es esencial que el LLM realice el razonamiento. Debe ser una cadena UTF-8 de hasta 1 MB.
apiSpec	ApiSpec La especificación de la API que se muestra al LLM para razonar. Debes proporcionar una descripción informativa y significativa.
authConfig	JsonDict|AuthConfig Tipo de autenticación que admite esta extensión.

ApiSpec

ApiSpec contiene la referencia al URI de Cloud Storage que almacena el archivo yaml de OpenAPI.

"apiSpec": {
  "openApiGcsUri": string
}

Parámetros
openApiGcsUri	string URI de Cloud Storage del archivo YAML de OpenAPI que describe la API de la extensión, p. ej., gs://vertex-extension-public/code_interpreter.yaml

AuthConfig

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

Autenticación de la cuenta de servicio de Google

La extensión de intérprete de código y la extensión de Vertex AI Search solo admiten la cuenta de servicio de Google en la que Vertex AI usa el agente de servicio de extensión de Vertex AI para acceder a las APIs. Para admitir la autenticación de la cuenta de servicio de Google, especifica authConfig:

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

Parámetros

serviceAccount

Opcional: string La cuenta de servicio con la que se realiza la ejecución de la extensión. Si se especifica la cuenta de servicio, se debe otorgar el permiso iam.serviceAccounts.getAccessToken al [agente de servicio de extensiones](/vertex-ai/docs/general/access-control#service-agents) de Vertex AI en la cuenta de servicio especificada. Si no se especifica, se usará el agente de servicio de Vertex AI Extension para ejecutar la extensión.

RuntimeConfig

La configuración del entorno de ejecución contiene una configuración adicional que se usa cuando se ejecuta la extensión.

Para la extensión del intérprete de código, runtimeConfig se puede configurar de la siguiente manera:

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

Parámetros
fileInputGcsBucket	Opcional: string El bucket de Cloud Storage para la entrada de archivos de esta extensión. Si se especifica, admite la entrada del bucket de Cloud Storage. El agente de servicio del código personalizado de la extensión de Vertex debe tener el permiso roles/storage.objectViewer para este bucket. Si no se especifica, la extensión solo aceptará el contenido del archivo del cuerpo de la solicitud y rechazará las entradas de archivos de Cloud Storage.
fileOutputGcsBucket	Opcional: string Bucket de Cloud Storage para la salida de archivos de esta extensión. Si se especifica, escribe todos los archivos de salida en el bucket de Cloud Storage. El agente de servicio del código personalizado de la extensión de Vertex debe tener el permiso roles/storage.objectUser para este bucket. Si no se especifica, el contenido del archivo se mostrará en el cuerpo de la respuesta.

Para la extensión de Vertex AI Search, el runtimeConfig debe establecerse en lo siguiente:

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

Parámetros
servingConfigName	string Nombre de la configuración de entrega de Vertex AI Search para especificar qué recurso de Vertex AI Search usará la extensión. Formato: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

Ejemplos

Importa el intérprete de código

En este ejemplo, se muestra cómo los usuarios pueden importar una extensión del intérprete de código.

• PROJECT_ID = PROJECT_ID
• REGION = us-central1

Nota: Esta es una función de versión preliminar y solo está disponible a través de la versión v1beta1 de la API.

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import \
 -d '{
    "displayName": "Code Interpreter",
    "description": "This extension generates and executes code",
    "manifest": {
      "name": "code_interpreter_tool",
      "description": "Google Code Interpreter Extension",
      "apiSpec": {
        "openApiGcsUri": "gs://vertex-extension-public/code_interpreter.yaml",
      },
      "authConfig": {
        "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        "googleServiceAccountConfig": {}
      }
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID,location=REGION)

extension_code_interpreter = 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 RuntimeConfig

En este ejemplo, se muestra cómo los usuarios pueden importar una extensión con RuntimeConfig (con la extensión de Vertex AI Search como ejemplo).

Nota: Esta es una función de versión preliminar y solo está disponible a través de la versión v1beta1 de la API.

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import \
 -d '{
    "displayName": "Vertex AI Search extension",
    "description": "A search extension",
    "manifest": {
      "name": "vertex_ai_search",
      "description": "Vertex AI Search Extension",
      "apiSpec": {
        "openApiGcsUri": "gs://vertex-extension-public/vertex_ai_search.yaml",
      },
      "authConfig": {
        "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        "googleServiceAccountConfig": {}
      }
    },
    "runtimeConfig": {
      "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "'${SERVING_CONFIG_NAME}'",
      }
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

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

Ejecuta la extensión

Ejecuta una extensión, que llame directamente a la operación de extensión con los parámetros proporcionados en la solicitud.

Sintaxis

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}/:execute

Python

from vertexai.preview import extensions

extension.execute(
  operation_id: str,
  operation_params: Optional[Union[JsonDict, Struct]] = None,
)

Lista de parámetros

Parámetros
operation_id	string El ID seleccionado de la operación que se ejecutará en esta extensión
operation_params	Opcional: JsonDict|Struct Los parámetros de solicitud que se usarán para ejecutar esta operación. El JSON debe tener una forma de mapa con el nombre del parámetro como clave y el valor del parámetro real como valor. P. ej., si esta operación requiere que se configure un parámetro "consulta" en "¿Qué es Vertex AI?". puedes configurar esto como {"consulta": “¿Qué es Vertex AI?”}.

Ejemplos

En este ejemplo, se ejecuta la extensión del intérprete de código generate_and_execute para obtener la respuesta de la consulta "busca el valor máximo en la lista: [1,2,3,4,-5]".

• PROJECT_ID = PROJECT_ID
• REGION = us-central1
• EXTENSION_ID = EXTENSION_ID

Nota: Esta es una función de versión preliminar y solo está disponible a través de la versión v1beta1 de la API.

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}:execute \
 -d '{
   "operation_id": "generate_and_execute",
   "operation_params": {
      "query": "find the max value in the list: [1,2,3,4,-5]",
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

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

Enumera la extensión

Enumera el recurso de extensiones dentro del proyecto.

Ejemplo

• PROJECT_ID = PROJECT_ID
• REGION = us-central1

Nota: Esta es una función de versión preliminar y solo está disponible a través de la versión v1beta1 de la API.

curl

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID,location=REGION)

extensions.Extension.list()

Obtén la extensión

Obtén un recurso de extensión.

Ejemplo

• PROJECT_ID = PROJECT_ID
• REGION = us-central1
• EXTENSION_ID = EXTENSION_ID

Nota: Esta es una función de versión preliminar y solo está disponible a través de la versión v1beta1 de la API.

curl

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

extension = extensions.Extension(EXTENSION_ID)

Actualiza la extensión

Actualiza un recurso de extensión. Puedes actualizar el displayName, la descripción o el toolUseExamples de la extensión.

Ejemplo

En este ejemplo, se actualiza la descripción de la extensión a “Una buena herramienta”.

• PROJECT_ID = PROJECT_ID
• REGION = us-central1
• EXTENSION_ID = EXTENSION_ID

curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

Borra la extensión

Borra un recurso de extensión.

Ejemplo

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

• PROJECT_ID = PROJECT_ID
• REGION = us-central1
• EXTENSION_ID = EXTENSION_ID

Nota: Esta es una función de versión preliminar y solo está disponible a través de la versión v1beta1 de la API.

curl

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

extension_code_interpreter = extensions.Extension(
    "${EXTENSION_ID}"
)
extension_code_interpreter.delete()

Explora más

Para obtener documentación detallada, consulta lo siguiente:

• El vínculo público será Conecta modelos a las APIs a través de extensiones
• Extensiones de Google