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 | |
---|---|
|
Opcional: 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. |
|
Opcional: 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. |
El manifiesto de la extensión. |
|
Opcional: 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 | |
---|---|
|
El nombre de la extensión que usa el LLM para razonar. Debe ser una cadena UTF-8 de hasta 128 caracteres. |
|
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. |
La especificación de la API que se muestra al LLM para el razonamiento. Debes proporcionar una descripción significativa e informativa. "apiSpec": { "openApiGcsUri": string } |
|
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 | |
---|---|
|
URI de Cloud Storage del archivo YAML de OpenAPI que describe la API de extensión, como |
authConfig
El tipo de autenticación admitido por esta extensión.
Parámetros | |
---|---|
|
Método de autenticación. Valores admitidos: |
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 | |
---|---|
|
Opcional: La cuenta de servicio con la que se ejecuta la extensión. Si se especifica la cuenta de servicio, se debe conceder el permiso |
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 | |
---|---|
|
Opcional: El segmento de Cloud Storage del archivo de entrada de la extensión. Se debe conceder el permiso |
|
Opcional: Segmento de Cloud Storage para el archivo de salida de la extensión. Se debe conceder el permiso |
Extensión Vertex AI Search
Parámetros | |
---|---|
|
Nombre de la configuración de servicio de Vertex AI Search para especificar qué recurso de Vertex AI Search usa la extensión. Formato:
|
Ejecutar extensión
Parámetros | |
---|---|
|
El ID seleccionado de la operación que se va a ejecutar en esta extensión. |
|
Opcional: 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 |
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.
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.
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.
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.
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
otoolUseExamples
.
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.