En este documento, se muestra cómo registrar y usar la extensión del intérprete de código proporcionado por Google desde la consola de Google Cloud y la API de Vertex AI. Esta extensión te permite generar y ejecutar el código de Python para lo siguiente:
- analizar, limpiar, transformar y cambiar la forma de tus conjuntos de datos
- visualizar los datos en gráficos y grafos
- Ejecuta cálculos
La extensión del intérprete de código usa code_interpreter_tool
para generar y ejecutar el código de Python a partir de una descripción de lenguaje natural. La
code_interpreter_tool
se define en un archivo
code_interpreter.yaml
de la
Especificación de OpenAPI.
openapi: "3.0.0" info: version: 1.0.0 title: code_interpreter_tool description: > This tool supports the following operations based on user input: 1. **Generates and Executes Code:** Accepts an user query in natural language, generates corresponding code, and executes it to produce results for the user query. Supported AuthTypes: - `GOOGLE_SERVICE_ACCOUNT_AUTH`: (Vertex AI Extension Service Agent is supported). paths: /generate_and_execute: post: operationId: generate_and_execute description: > Get the results of a natural language query by generating and executing a code snippet. Example queries: "Find the max in [1, 2, 5]" or "Plot average sales by year (from data.csv)". requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: > Required. The Natural language query to get the results for. The query string can optionally contain data to use for the code generated. For example: "I have a list of numbers: [1, 2, 3, 4]. Find the largest number in the provided data." timeout: type: number description: > Optional. Timeout in miliseconds for the code execution. Default value: 30000. files: type: array description: > Optional. Input files to use when executing the generated code. If specified, the file contents are expected be base64-encoded. For example: [{"name": "data.csv", "contents": "aXRlbTEsaXRlbTI="}] items: $ref: "#/components/schemas/File" file_gcs_uris: type: array description: > Optional. GCS URIs of input files to use when executing the generated code. For example: ["gs://input-bucket/data.csv"] This option is only applicable when `file_input_gcs_bucket` is specified in `Extension.CodeInterpreterRuntimeConfig`. items: type: string responses: '200': description: > The results of generating and executing code based on the natual language query. The result contains the generated code, and the STDOUT, STDERR, and output files from code execution. content: application/json: schema: $ref: "#/components/schemas/GenerationAndExecutionResult" components: schemas: File: description: > File used as inputs and outputs of code execution. The `contents` string should be base64-encoded bytes. For example: [{"name": "data.csv", "contents": "aXRlbTEsaXRlbTI="}] type: object properties: name: type: string contents: type: string format: byte GenerationAndExecutionResult: description: > The results of generating and executing code based on the natual language query. properties: generated_code: type: string description: > The generated code in markdown format. For example: "```python\nprint(\"Hello World\")\n```" execution_result: type: string description: > The code execution result string from STDOUT. execution_error: type: string description: > The code execution error string from STDERR. output_files: type: array description: > The output files generated from code execution. If present, the file contents are required be base64-encoded. For example: [{"name": "data.csv", "contents": "aXRlbTEsaXRlbTI="}] items: $ref: "#/components/schemas/File" output_gcs_uris: type: array description: > The output GCS URIs of files generated from code execution. For example: ["gs://output-bucket/subfolder/output.csv"] This field is only applicable when `file_output_gcs_bucket` is specified in `Extension.CodeInterpreterRuntimeConfig`. items: type: string
Para obtener información sobre las extensiones de Google con instructivos de extremo a extremo, consulta los siguientes notebooks de Jupyter:
- Flujo de trabajo de analistas de negocios con extensiones de Vertex AI: Usa la extensión Code Interpreter y la extensión de Vertex AI Search para completar un informe de investigación de oportunidades de inversión en viviendas para las partes interesadas de la empresa.
Colab | GitHub | Vertex AI Workbench - Exploración de datos y entrenamiento de modelos con el intérprete de código de Vertex AI Extensions: Realiza tareas comunes de ciencia de datos, como el análisis de conjuntos de datos y el entrenamiento de modelos.
Colab | GitHub | Vertex AI Workbench - Flujo de trabajo del análisis de opiniones de juegos con Vertex AI Extensions: Usa la extensión del intérprete de código para analizar las opiniones de juegos de Steam. Usa la extensión de Vertex AI Search para resumir las opiniones de los juegos de los sitios web. Usa la extensión de intérprete de código para crear un informe con todos los elementos generados.
Colab | GitHub | Vertex AI Workbench - Trabaja con Pandas con la extensión del intérprete de código de extensiones de Vertex AI: Usa el código de DataFrames de pandas generado por la extensión del intérprete de código para trabajar con conjuntos de datos grandes.
Colab | GitHub | Vertex AI Workbench - Flujo de trabajo de los desarrolladores web con extensiones de Vertex AI : Usa la extensión del intérprete de código para compilar e implementar una aplicación web estática.
Colab | GitHub | Vertex AI Workbench
Antes de comenzar
- Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
Enable the Vertex AI API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
Enable the Vertex AI API.
Registra, consulta y ejecuta la extensión del intérprete de código
En las siguientes secciones, se muestra cómo registrar la extensión del intérprete de código con la consola de Google Cloud y la API de Vertex AI. Después de registrar la extensión, puedes consultarla con la consola de Google Cloud o ejecutarla con la API de Vertex AI.
Console
Registra la extensión
Realiza los siguientes pasos para registrar la extensión del intérprete de código con la consola de Google Cloud.
En la consola de Google Cloud, ve a la página Extensiones de Vertex AI.
Haz clic en Create Extension.
En el cuadro de diálogo Crear una extensión nueva, haz lo siguiente:
- Nombre de la extensión: ingresa un nombre para la extensión, como "code_interpreter_extension".
- Descripción: ingresa una descripción de la extensión, como "Una extensión del intérprete de código" (opcional).
- Tipo de extensión: selecciona
Code interpreter
.
En la sección OpenAPI Spec file que aparece ahora, confirma que los siguientes campos estén configurados de forma correcta:
- Nombre de la API:
code_interpreter_tool
. - API description:
Tool to generate and run valid Python code from a natural language description, or to run custom Python code...
- Fuente:
Cloud Storage
. - OpenAPI Spec:
vertex-extension-public/code_interpreter.yaml
. - Autenticación:
Google service account
.
- Nombre de la API:
En la sección Runtime configurations, proporciona el bucket de entrada y el de salida (opcional).
- El bucket de entrada es el
bucket de Cloud Storage
que usará la extensión para leer archivos de entrada, incluido el prefijo
gs://
, por ejemplo,gs://sample-bucket-name
. Si se especifica, debes asignar el rolroles/storage.objectViewer
en este bucket a la cuenta de servicio del agente de servicio del código personalizado de la extensión de Vertex. - El bucket de salida es el
bucket de Cloud Storage
que usará la extensión para escribir los archivos de salida, incluido el prefijo
gs://
, por ejemplo,gs://sample-bucket-name
. Si se especifica, debes asignar el rolroles/storage.objectUser
en este bucket a la cuenta de servicio del agente de servicio del código personalizado de la extensión de Vertex.
- El bucket de entrada es el
bucket de Cloud Storage
que usará la extensión para leer archivos de entrada, incluido el prefijo
Haz clic en Create Extension.
Consulta la extensión (opcional)
Puedes usar la consola de Google Cloud para experimentar con la extensión del intérprete de código. Realiza los siguientes pasos para invocar la extensión con instrucciones de lenguaje natural.
En la consola de Google Cloud, ve a la página Extensiones de Vertex AI.
Haz clic en el nombre de la extensión del intérprete de código para abrir la página Extensions details.
En el cuadro Enter a message, ingresa una consulta y, luego, observa la respuesta. Expande las secciones Extension Response para ver el código que la extensión generó y ejecutó para producir el resultado.
En el siguiente ejemplo, se muestran los resultados de una consulta que calculó el valor medio de una lista de los números que ingresó el usuario.
REST
Registra la extensión
Envía una solicitud extensions.import
a la API de Vertex AI
para registrar la extensión del intérprete de código.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- REGION: una región de Compute Engine.
- DISPLAY_NAME: la extensión de nombre que se muestra a los usuarios, como "my_code_interpreter_extension".
- DESCRIPTION: la descripción de la extensión que se muestra a los usuarios, como “Una extensión del intérprete de código” (opcional).
- SERVICE_ACCOUNT: la extensión del intérprete de código
usa GOOGLE_SERVICE_ACCOUNT_AUTH
como se muestra en el cuerpo de la solicitud de muestra (opcional). Si no especificas una cuenta de servicio, la extensión usa la cuenta de servicio del
agente de servicio de Vertex AI Extension
predeterminada.
Si especificas una cuenta de servicio diferente, otorga el
permiso
iam.serviceAccounts.getAccessToken
a la cuenta de servicio del agente de servicio de Vertex AI Extension en la cuenta de servicio especificada. - INPUT_BUCKET: el
bucket de Cloud Storage
que usará la extensión para leer archivos de entrada, incluido el prefijo
gs://
, por ejemplo,gs://sample-bucket-name
(opcional). Si se especifica, debes asignar el rolroles/storage.objectViewer
en este bucket a la cuenta de servicio del agente de servicio del código personalizado de la extensión de Vertex. - OUTPUT_BUCKET: el bucket de Cloud Storage
que usará la extensión para escribir archivos de salida, incluido el prefijo
gs://
, por ejemplo,gs://sample-bucket-name
(opcional). Si se especifica, debes asignar el rolroles/storage.objectUser
en este bucket a la cuenta de servicio del agente de servicio del código personalizado de la extensión de Vertex.
Método HTTP y URL:
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import
Cuerpo JSON de la solicitud:
{ "displayName":"DISPLAY_NAME", "description":"DESCRIPTION", "manifest":{ "name":"code_interpreter_tool", "description":"A Google Code Interpreter tool", "apiSpec":{ "openApiGcsUri":"gs://vertex-extension-public/code_interpreter.yaml" }, "authConfig":{ "authType":"GOOGLE_SERVICE_ACCOUNT_AUTH", "googleServiceAccountConfig":{ "serviceAccount":"SERVICE_ACCOUNT" } } } "runtimeConfig": { "codeInterpreterRuntimeConfig": { "fileInputGcsBucket": "INPUT_BUCKET", "fileOutputGcsBucket": "OUTPUT_BUCKET" } } }
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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import" | Select-Object -Expand Content
Ejecuta la extensión
Puedes enviar una operación execute
a la API de Vertex AI para generar y ejecutar código de Python basado en una consulta de lenguaje natural.
Ejemplos de consultas:
- Consulta simple: encuentra el valor máximo de una lista de números.
- Datos intercalados de la consulta: los datos que se consultarán se proporcionan en el cuerpo de la solicitud.
- Consulta con datos de archivos: imprime datos de archivos.
- Consulta con datos de Cloud Storage: lee datos de Cloud Storage.
Consulta simple
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- REGION: una región de Compute Engine.
- EXTENSION_ID: el ID de la extensión del intérprete de código que aparece en los detalles de la extensión en la consola de Google Cloud.
Método HTTP y URL:
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Cuerpo JSON de la solicitud:
{ "operation_id":"generate_and_execute", "operation_params":{ "query":"find the max value in the list: [1,2,3,4,-5]" } }
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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content
Datos intercalados
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- REGION: una región de Compute Engine.
- EXTENSION_ID: el ID de la extensión del intérprete de código que aparece en los detalles de la extensión en la consola de Google Cloud.
Método HTTP y URL:
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Cuerpo JSON de la solicitud:
{ "operation_id":"generate_and_execute", "operation_params":{ "query":"Calculate the total values of each column(mobile_subscribers, percent_internet_users, total_internet_users, fixed_broadband_subscribers) from the below dataset.\n\n\ncountry_name country_code year mobile_subscribers percent_internet_users total_internet_users fixed_broadband_subscribers\nUnited States US 2023 333.4 90.5 303.1 200.3\nChina CN 2023 1.613 70.2 1131.4 512.2\nIndia IN 2023 1.165 50.7 688.5 557.2\nJapan JP 2023 124.3 88.2 109.5 114.8\nGermany DE 2023 102.1 90.5 92.1 100\nUnited Kingdom UK 2023 67.1 92.7 62.2 65\nFrance FR 2023 66.7 89 63 69.7\nBrazil BR 2023 213.5 68 144.1 69.4\nRussia RU 2023 203.8 74.9 152.7 51.1" } }
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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content
Impresión de archivos
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- REGION: una región de Compute Engine.
- EXTENSION_ID: el ID de la extensión del intérprete de código que aparece en los detalles de la extensión en la consola de Google Cloud.
- FILE_NAME: los datos del archivo CSV en el cuerpo de la solicitud se escriben en este archivo en el directorio de trabajo.
- BASE64_ENCODED_FILE_BYTES: los bytes de archivo en el cuerpo de la solicitud deben estar codificados en base64.
Método HTTP y URL:
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Cuerpo JSON de la solicitud:
{ "operation_id":"generate_and_execute", "operation_params":{ "query":"print the csv file", "files":[ { "name":"FILE_NAME", "contents":"BASE64_ENCODED_FILE_BYTES" } ] } }
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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content
Lectura de Cloud Storage
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- REGION: una región de Compute Engine.
- EXTENSION_ID: el ID de la extensión del intérprete de código que aparece en los detalles de la extensión en la consola de Google Cloud.
- BUCKET_NAME: el bucket de Cloud Storage que contiene el archivo CSV que se imprimirá. Debes haber especificado este bucket de entrada cuando registraste la extensión del intérprete de código.
- FILE_NAME: los datos del archivo CSV en BUCKET_NAME que se imprimirán.
Método HTTP y URL:
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Cuerpo JSON de la solicitud:
{ "operation_id":"generate_and_execute", "operation_params":{ "query":"print the csv file", "file_gcs_uris": ["gs://BUCKET_NAME/FILE_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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content