Extensión Intérprete de código

Vista previa

Vertex AI Extensions es una oferta de vista previa sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de los Google Cloud Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general pueden tener una asistencia limitada y los cambios que se produzcan en ellos podrían no ser compatibles con otras versiones previas a la disponibilidad general. Para obtener más información, consulta las descripciones de las fases de lanzamiento. Además, al usar las extensiones de Vertex AI, aceptas los términos y condiciones de la vista previa de IA generativa (los "Términos de la Vista Previa").

En este documento se explica cómo registrar y usar la extensión Code Interpreter proporcionada por Google desde la consola y la API de Vertex AI. Google Cloud Esta extensión te permite generar y ejecutar código Python para hacer lo siguiente:

• Analizar, limpiar, transformar y cambiar la forma de los conjuntos de datos
• Visualizar datos en gráficos
• Realizar cálculos

La extensión Intérprete de código usa code_interpreter_tool para generar y ejecutar código Python a partir de una descripción en lenguaje natural. La code_interpreter_tool se define en un archivo de especificación de OpenAPI code_interpreter.yaml.

Mostrarme Ocultarme

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 a 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

    

Antes de empezar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Registrar, consultar y ejecutar la extensión Intérprete de código

En las siguientes secciones se muestra cómo registrar la extensión de intérprete de código mediante la Google Cloud consola y la API Vertex AI. Después de registrar la extensión, puedes consultarla mediante la consola Google Cloud o ejecutarla con la API Vertex AI.

Consola

Registrar la extensión

Sigue estos pasos para registrar la extensión Code Interpreter mediante la consola Google Cloud .

1. En la consola de Google Cloud , ve a la página Extensiones de Vertex AI.

   Ir a Extensiones de Vertex AI

2. Haz clic en Crear extensión.

3. En el cuadro de diálogo Crear una extensión, haz lo siguiente:

   • Nombre de la extensión: escribe un nombre para la extensión, como "code_interpreter_extension".
   • Descripción: (opcional) escribe una descripción de la extensión, como "Una extensión de intérprete de código".
   • Tipo de extensión: selecciona Code interpreter.

4. En la sección Archivo de especificación de OpenAPI que aparece ahora, compruebe que los siguientes campos estén configurados correctamente:

   • Nombre de la API: code_interpreter_tool.
   • Descripción de la API: Tool to generate and run valid Python code from a natural language description, or to run custom Python code...
   • Fuente: Cloud Storage.
   • Especificación de OpenAPI: vertex-extension-public/code_interpreter.yaml.
   • Autenticación: Google service account.

5. (Opcional) En la sección Configuraciones de tiempo de ejecución, proporcione el contenedor de entrada y el contenedor de salida.

   • El segmento de entrada es el segmento de Cloud Storage que la extensión usará para leer los archivos de entrada, incluido el prefijo gs://, por ejemplo, gs://sample-bucket-name. Si se especifica, debes asignar el rol roles/storage.objectViewer a este segmento en la cuenta de servicio Agente de servicio de código personalizado de extensión de Vertex.
   • El segmento de salida es el segmento de Cloud Storage que la extensión usará para escribir archivos de salida, incluido el prefijo gs://, por ejemplo, gs://sample-bucket-name. Si se especifica, debes asignar el rol roles/storage.objectUser a este segmento en la cuenta de servicio Agente de servicio de código personalizado de extensión de Vertex.

6. Haz clic en Crear extensión.

(Opcional) Consultar la extensión

Puedes usar la Google Cloud consola para experimentar con tu extensión Code Interpreter. Sigue estos pasos para invocar la extensión con peticiones en lenguaje natural.

1. En la consola de Google Cloud , ve a la página Extensiones de Vertex AI.

   Ir a Extensiones de Vertex AI

2. Haz clic en el nombre de la extensión Code Interpreter para abrir la página Detalles de la extensión.

   

3. En el cuadro Escribe un mensaje, introduce una consulta y, a continuación, consulta la respuesta. Amplía las secciones de respuesta de la extensión para ver el código que ha generado y ejecutado la extensión para producir el resultado.

   En el siguiente ejemplo se muestran los resultados de una consulta que ha calculado el valor medio de una lista de números introducida por el usuario.

   

REST

Registrar la extensión

Envía una solicitud de la API Vertex AI extensions.import para registrar la extensión Code Interpreter.

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

• PROJECT_ID: el ID de tu proyecto de Google Cloud .
• REGION: una región de Compute Engine.
• DISPLAY_NAME: el nombre de la extensión que se muestra a los usuarios, como "my_code_interpreter_extension".
• DESCRIPTION: (Opcional) La descripción de la extensión que se muestra a los usuarios, como "Una extensión de intérprete de código".
• SERVICE_ACCOUNT: (Opcional) La extensión de intérprete de código usa GOOGLE_SERVICE_ACCOUNT_AUTH como se muestra en el cuerpo de la solicitud de ejemplo. Si no especificas ninguna cuenta de servicio, la extensión usará la cuenta de servicio predeterminada Vertex AI Extension Service Agent. Si especifica otra cuenta de servicio, conceda el permiso iam.serviceAccounts.getAccessToken a la cuenta de servicio del agente de servicio de extensión de Vertex AI en la cuenta de servicio especificada.
• INPUT_BUCKET: (Opcional) El contenedor de Cloud Storage que usará la extensión para leer los archivos de entrada, incluido el prefijo gs://. Por ejemplo, gs://sample-bucket-name. Si se especifica, debes asignar el rol roles/storage.objectViewer en este segmento a la cuenta de servicio Agente de servicio de código personalizado de extensión de Vertex.
• OUTPUT_BUCKET: (Opcional) El segmento de Cloud Storage que usará la extensión para escribir archivos de salida, incluido el prefijo gs://, por ejemplo, gs://sample-bucket-name. Si se especifica, debe asignar el rol roles/storage.objectUser en este segmento a la cuenta de servicio Agente de servicio de código personalizado de 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

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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

Ejecutar 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 en lenguaje natural.

Ejemplos de consultas:

• Consulta sencilla: busca el valor máximo de una lista de números.
• Consultar datos insertados: los datos que se van a consultar se proporcionan en el cuerpo de la solicitud.
• Consulta con datos de archivo: imprime los datos del archivo.
• Consultar datos de Cloud Storage: leer datos de Cloud Storage.

Consulta simple

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

• PROJECT_ID: el ID de tu proyecto de Google Cloud .
• REGION: una región de Compute Engine.
• EXTENSION_ID: el ID de tu extensión de intérprete de código, que se indica en la sección Detalles de la extensión de la consola 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

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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 insertados

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

• PROJECT_ID: el ID de tu proyecto de Google Cloud .
• REGION: una región de Compute Engine.
• EXTENSION_ID: el ID de tu extensión de intérprete de código, que se indica en la sección Detalles de la extensión de la consola 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

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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 los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: el ID de tu proyecto de Google Cloud .
• REGION: una región de Compute Engine.
• EXTENSION_ID: el ID de tu extensión de intérprete de código, que se indica en la sección Detalles de la extensión de la consola Google Cloud .
• FILE_NAME: Los datos del archivo CSV del cuerpo de la solicitud se escriben en este archivo del directorio de trabajo.
• BASE64_ENCODED_FILE_BYTES: Los bytes del 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

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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 los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: el ID de tu proyecto de Google Cloud .
• REGION: una región de Compute Engine.
• EXTENSION_ID: el ID de tu extensión de intérprete de código, que se indica en la sección Detalles de la extensión de la consola Google Cloud .
• BUCKET_NAME: el contenedor de Cloud Storage que contiene el archivo CSV que se va a imprimir. Debes haber especificado este contenedor de entrada al registrar la extensión del intérprete de código.
• FILE_NAME: los datos del archivo CSV que se van a imprimir.BUCKET_NAME

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

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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