Extensão Intérprete de código

Neste documento, mostramos como registrar e usar a extensão Code Interpreter fornecida pelo Google no console do Google Cloud e na API Vertex AI. Essa extensão permite gerar e executar código Python para:

Analisar, limpar, transformar e remodelar conjuntos de dados
Visualizar dados em gráficos
Realizar cálculos

A extensão Code Interpreter usa o code_interpreter_tool para gerar e executar o código Python a partir de uma descrição de linguagem natural. O code_interpreter_tool é definido em um arquivo code_interpreter.yaml da especificação 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 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

Para saber mais sobre as extensões do Google com tutoriais completos, consulte os seguintes notebooks do Jupyter:

Fluxo de trabalho de analistas de negócios com extensões da Vertex AI: use a extensão Code Interpreter e a extensão Vertex AI para Pesquisa para concluir um relatório de pesquisa de oportunidades de investimento em habitação para as partes interessadas de negócios.
Colab | GitHub | Vertex AI Workbench
Análise detalhada de dados e treinamento de modelo com o interpretador de códigos das Extensões da Vertex AI: realize tarefas comuns de ciência de dados, como análise de conjuntos de dados e treinamento de modelo.
Colab | GitHub | Vertex AI Workbench
Fluxo de trabalho de análise de avaliações de jogos com as Extensões da Vertex AI: use a extensão Code Interpreter para analisar as avaliações de jogos do Steam. Use a extensão Vertex AI para Pesquisa para resumir avaliações de jogos em sites. Use a extensão Intérprete de código para criar um relatório com todos os recursos gerados.
Colab | GitHub | Vertex AI Workbench
Como trabalhar com o Pandas usando a extensão Code Interpreter das Extensões da Vertex AI: use o código DataFrames do pandas gerado pela extensão Code Interpreter para trabalhar com conjuntos de dados muito grandes.
Colab | GitHub | Vertex AI Workbench
Fluxo de trabalho de desenvolvedores Web com as Extensões da Vertex AI: use a extensão Code Interpreter para criar e implantar um aplicativo da Web estático.
Colab | GitHub | Vertex AI Workbench

Antes de começar

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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

Registrar, consultar e executar a extensão Code Interpreter

As seções a seguir mostram como registrar a extensão do Intérprete de código usando o console do Google Cloud e a API Vertex AI. Depois de registrar a extensão, ela pode ser consultada usando o console do Google Cloud ou executada usando a API Vertex AI.

Console

Registrar a extensão

Siga as etapas a seguir para registrar a extensão Intérprete de código usando o console do Google Cloud.

No console do Google Cloud, acesse a página Extensões da Vertex AI.

Acesse as extensões da Vertex AI
Clique em Criar extensão.
Na caixa de diálogo Criar uma nova extensão, faça isto:
- Nome da extensão: insira um nome para a extensão, como "code_interpreter_extension".
- Descrição: (opcional) insira uma descrição da extensão, como "Uma extensão de intérprete de código".
- Tipo de extensão: selecione Code interpreter.
Na seção Arquivo de especificação da OpenAPI exibida, verifique se os campos a seguir estão definidos corretamente:
- Nome da API: code_interpreter_tool.
- Descrição de APIs: Tool to generate and run valid Python code from a natural language description, or to run custom Python code...
- Fonte: Cloud Storage.
- Especificação da OpenAPI: vertex-extension-public/code_interpreter.yaml.
- Autenticação: Google service account.
(Opcional) Na seção Configurações do ambiente de execução, forneça os buckets de entrada e de saída.
- O bucket de entrada é o bucket do Cloud Storage que a extensão usará para ler os arquivos de entrada, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, você precisa atribuir o papel roles/storage.objectViewer nesse bucket à conta de serviço do Agente de serviço de código personalizado da extensão da Vertex.
- O bucket de saída é o bucket do Cloud Storage que a extensão usará para gravar arquivos de saída, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, você precisa atribuir o papel roles/storage.objectUser nesse bucket à conta de serviço do Agente de serviço de código personalizado da extensão da Vertex.
Clique em Criar extensão.

(Opcional) Consultar a extensão

Use o console do Google Cloud para testar a extensão Intérprete de código. Siga as etapas a seguir para invocar a extensão com os comandos de linguagem natural.

No console do Google Cloud, acesse a página Extensões da Vertex AI.

Acesse as extensões da Vertex AI
Clique no nome da extensão Intérprete de código para abrir a página Detalhes das extensões.
Na caixa Insira uma mensagem, digite uma consulta e veja a resposta. Expanda as seções "Resposta da extensão" para visualizar o código que a extensão gerou e executou para produzir o resultado.

Veja no exemplo a seguir os resultados de uma consulta que calculou o valor médio de uma lista de números inseridos pelo usuário.

REST

Registrar a extensão

Envie uma solicitação extensions.import da API Vertex AI para registrar a extensão Intérprete de código.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud.
REGION: uma região do Compute Engine.
DISPLAY_NAME: a extensão nome mostrada aos usuários, como "my_code_interpreter_extension".
DESCRIPTION: (opcional) a descrição da extensão que é exibida aos usuários, como "Uma extensão Intérprete de código".
SERVICE_ACCOUNT: (opcional) a extensão Intérprete de código usa GOOGLE_SERVICE_ACCOUNT_AUTH, conforme mostrado no corpo da solicitação de amostra. Se você não especificar uma conta de serviço, a extensão vai usar a conta de serviço padrão do Agente de serviço de extensão da Vertex AI. Se você especificar uma conta de serviço diferente, conceda a permissão iam.serviceAccounts.getAccessToken à conta de serviço do Agente de serviço de extensão da Vertex AI na conta de serviço especificada.
INPUT_BUCKET: (opcional) o bucket do Cloud Storage que a extensão usará para ler arquivos de entrada, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, você precisa atribuir o papel roles/storage.objectViewer nesse bucket à conta de serviço do Agente de serviço de código personalizado da extensão da Vertex.
OUTPUT_BUCKET: (opcional) o bucket do Cloud Storage que a extensão usará para gravar arquivos de saída, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, você precisa atribuir o papel roles/storage.objectUser nesse bucket à conta de serviço do Agente de serviço de código personalizado da extensão da Vertex.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import

Corpo JSON da solicitação:

{
  "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 a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Executar a extensão

Envie uma operação execute à API Vertex AI para gerar e executar um código Python com base em uma consulta de linguagem natural.

Exemplos de consultas:

Consulta simples: encontra o valor máximo em uma lista de números.
Consulta de dados inline: os dados a serem consultados são fornecidos no corpo da solicitação.
Consulta de dados de arquivos: imprime os dados do arquivo.
Consulta de dados do Cloud Storage: lê os dados do Cloud Storage.

Consulta simples

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud.
REGION: uma região do Compute Engine.
EXTENSION_ID: o ID da extensão Intérprete de código listado nos Detalhes da extensão no console do Google Cloud.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute

Corpo JSON da solicitação:

{
  "operation_id":"generate_and_execute",
  "operation_params":{
    "query":"find the max value in the list: [1,2,3,4,-5]"
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Dados inline

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud.
REGION: uma região do Compute Engine.
EXTENSION_ID: o ID da extensão Intérprete de código listado nos Detalhes da extensão no console do Google Cloud.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute

Corpo JSON da solicitação:

{
  "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 a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Impressão de arquivo

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud.
REGION: uma região do Compute Engine.
EXTENSION_ID: o ID da extensão Intérprete de código listado nos Detalhes da extensão no console do Google Cloud.
FILE_NAME: os dados do arquivo CSV no corpo da solicitação são gravados nesse arquivo no diretório de trabalho.
BASE64_ENCODED_FILE_BYTES: os bytes do arquivo no corpo da solicitação precisam ser codificados em base64.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute

Corpo JSON da solicitação:

{
  "operation_id":"generate_and_execute",
  "operation_params":{
    "query":"print the csv file",
    "files":[
      {
        "name":"FILE_NAME",
        "contents":"BASE64_ENCODED_FILE_BYTES"
      }
    ]
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Leitura do Cloud Storage

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud.
REGION: uma região do Compute Engine.
EXTENSION_ID: o ID da extensão Intérprete de código listado nos Detalhes da extensão no console do Google Cloud.
BUCKET_NAME: o bucket do Cloud Storage que contém o arquivo CSV a ser impresso. Você precisa especificar esse bucket de entrada ao registrar a extensão Intérprete de código.
FILE_NAME: os dados do arquivo CSV no BUCKET_NAME a ser impresso.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute

Corpo JSON da solicitação:

{
  "operation_id":"generate_and_execute",
  "operation_params":{
    "query":"print the csv file",
    "file_gcs_uris": ["gs://BUCKET_NAME/FILE_NAME"]
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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