Extensión del intérprete de código

En este documento, se muestra cómo registrar y usar la extensión del intérprete de código que proporciona Google desde la consola de Google Cloud y la API de Vertex AI. Esta extensión te permite generar y ejecutar 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="}]

                    Only one of `file_gcs_uris` and `files` field should be provided.
                  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"]

                    Only one of `file_gcs_uris` and `files` field should be provided.
                    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 de intérprete de código y la extensión de búsqueda de Vertex AI 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 Extensiones de Vertex AI: 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 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 mediante la extensión del intérprete de código de las extensiones de Vertex AI: Usa el código de DataFrames de Pandas generado por la extensión de intérprete de código para trabajar con conjuntos de datos especialmente grandes.
    Colab | GitHub | Vertex AI Workbench
  • Flujo de trabajo de desarrolladores web con extensiones de Vertex AI: Usa la extensión de intérprete de código para compilar e implementar una aplicación web estática.
    Colab | GitHub | Vertex AI Workbench

Antes de comenzar

  1. 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.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  4. Habilita la API de Vertex AI.

    Habilita la API

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

    Go to project selector

  6. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  7. Habilita la API de Vertex AI.

    Habilita la 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.

  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 Create Extension.

  3. 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.
  4. 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.
  5. En la sección Runtime configurations, proporciona el bucket de entrada y el de salida (opcional).

  6. 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.

  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 del intérprete de código para abrir la página Extensions details.

    Nombre del intérprete de código.

  3. 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.

    Consulta de valor medio.

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:

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