Esta página foi traduzida pela API Cloud Translation.

Extensão do Intérprete de código

Este documento mostra como registar e usar a extensão Code Interpreter fornecida pela Google a partir da Google Cloud consola e da API Vertex AI. Esta extensão permite-lhe gerar e executar código Python para:

Analise, limpe, transforme e reformule os seus conjuntos de dados
Visualize dados em gráficos
Executar cálculos

A extensão Code Interpreter usa o code_interpreter_tool para gerar e executar código Python a partir de uma descrição em linguagem natural. O elemento code_interpreter_tool está definido num ficheiro OpenAPI Specification code_interpreter.yaml.

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

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.

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.

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

Registe, consulte e execute a extensão do interpretador de código

As secções seguintes mostram como registar a extensão Code Interpreter através da Google Cloud consola e da API Vertex AI. Depois de registar a extensão, pode consultá-la através da Google Cloud consola ou executá-la através da API Vertex AI.

Consola

Registe a extensão

Siga os passos abaixo para registar a extensão Code Interpreter através da Google Cloud consola.

Na Google Cloud consola, aceda à página Vertex AI Extensions.

Aceda às extensões do Vertex AI
Clique em Criar extensão.
Na caixa de diálogo Criar uma nova extensão, faça o seguinte:
- Nome da extensão: introduza um nome para a extensão, como "code_interpreter_extension".
- Descrição: (opcional) introduza uma descrição da extensão, como "Uma extensão de intérprete de código".
- Tipo de extensão: selecione Code interpreter.
Na secção Ficheiro de especificação OpenAPI que é apresentada, confirme se os seguintes campos estão definidos corretamente:
- Nome da API: code_interpreter_tool.
- Descrição da API: Tool to generate and run valid Python code from a natural language description, or to run custom Python code...
- Fonte: Cloud Storage.
- Especificação OpenAPI: vertex-extension-public/code_interpreter.yaml.
- Autenticação: Google service account.
(Opcional) Na secção Configurações de tempo de execução, indique o contentor de entrada e o contentor de saída.
- O contentor de entrada é o contentor do Cloud Storage que a extensão vai usar para ler ficheiros de entrada, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, tem de atribuir a função roles/storage.objectViewer neste contentor à conta de serviço do agente do serviço de código personalizado da extensão do Vertex.
- O contentor de saída é o contentor do Cloud Storage que a extensão vai usar para escrever ficheiros de saída, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, tem de atribuir a função roles/storage.objectUser neste contentor à conta de serviço do agente do serviço de código personalizado da extensão do Vertex.
Clique em Criar extensão.

(Opcional) Consulte a extensão

Pode usar a Google Cloud consola para experimentar a extensão Code Interpreter. Siga os passos abaixo para invocar a extensão com comandos de linguagem natural.

Na Google Cloud consola, aceda à página Vertex AI Extensions.

Aceda às extensões do Vertex AI
Clique no nome da extensão do Interpretador de código para abrir a página Detalhes das extensões.
Na caixa Introduza uma mensagem, introduza uma consulta e, em seguida, veja a resposta. Expanda as secções de resposta da extensão para ver o código que a extensão gerou e executou para produzir o resultado.

O exemplo seguinte mostra os resultados de uma consulta que calculou o valor médio de uma lista de números introduzidos pelo utilizador.

REST

Registe a extensão

Envie um pedido da API Vertex AI extensions.import para registar a extensão Code Interpreter.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu projeto Google Cloud .
REGION: Uma região do Compute Engine.
DISPLAY_NAME: o nome da extensão apresentado aos utilizadores, como "my_code_interpreter_extension".
DESCRIPTION: (Opcional) A descrição da extensão apresentada aos utilizadores, como "Uma extensão de intérprete de código".
SERVICE_ACCOUNT: (Opcional) A extensão Code Interpreter usa GOOGLE_SERVICE_ACCOUNT_AUTH conforme mostrado no corpo do pedido de exemplo. Se não especificar uma conta de serviço, a extensão usa a conta de serviço Vertex AI Extension Service Agent predefinida. Se especificar uma conta de serviço diferente, conceda a autorização iam.serviceAccounts.getAccessToken à conta de serviço do agente do serviço de extensão do Vertex AI na conta de serviço especificada.
INPUT_BUCKET: (Opcional) O contentor do Cloud Storage que a extensão vai usar para ler ficheiros de entrada, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, tem de atribuir a função roles/storage.objectViewer neste contentor à conta de serviço do agente do serviço de código personalizado da extensão do Vertex AI.
OUTPUT_BUCKET: (Opcional) O contentor do Cloud Storage que a extensão vai usar para escrever ficheiros de saída, incluindo o prefixo gs://, por exemplo, gs://sample-bucket-name. Se especificado, tem de atribuir a função roles/storage.objectUser a este contentor à conta de serviço do agente do serviço de código personalizado da extensão do Vertex AI.

Método HTTP e URL:

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

Corpo JSON do pedido:

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

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Execute a extensão

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

Exemplos de consultas:

Consulta simples: encontrar o valor máximo de uma lista de números.
Consultar dados inline: os dados a consultar são fornecidos no corpo do pedido.
Consulta com dados de ficheiros: imprima dados de ficheiros.
Consultar com dados do Cloud Storage: ler dados do Cloud Storage.

Consulta simples

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu projeto Google Cloud .
REGION: Uma região do Compute Engine.
EXTENSION_ID: o ID da sua extensão do interpretador de código listado nos Detalhes da extensão na Google Cloud consola.

Método HTTP e URL:

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

Corpo JSON do pedido:

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Dados inline

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu projeto Google Cloud .
REGION: Uma região do Compute Engine.
EXTENSION_ID: o ID da sua extensão do interpretador de código listado nos Detalhes da extensão na Google Cloud consola.

Método HTTP e URL:

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

Corpo JSON do pedido:

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

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Impressão de ficheiros

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu projeto Google Cloud .
REGION: Uma região do Compute Engine.
EXTENSION_ID: o ID da sua extensão do interpretador de código listado nos Detalhes da extensão na Google Cloud consola.
FILE_NAME: Os dados do ficheiro CSV no corpo do pedido são escritos neste ficheiro no diretório de trabalho.
BASE64_ENCODED_FILE_BYTES: os bytes do ficheiro no corpo do pedido têm de estar 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 do pedido:

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Leitura do Cloud Storage

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu projeto Google Cloud .
REGION: Uma região do Compute Engine.
EXTENSION_ID: o ID da sua extensão do interpretador de código listado nos Detalhes da extensão na Google Cloud consola.
BUCKET_NAME: o contentor do Cloud Storage que contém o ficheiro CSV a imprimir. Tem de ter especificado este bucket de entrada quando registou a extensão do intérprete de código.
FILE_NAME: os dados do ficheiro CSV no BUCKET_NAME a imprimir.

Método HTTP e URL:

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

Corpo JSON do pedido:

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Extensão do Intérprete de código Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Registe, consulte e execute a extensão do interpretador de código

Consola

REST

curl

PowerShell

Consulta simples

curl

PowerShell

Dados inline

curl

PowerShell

Impressão de ficheiros

curl

PowerShell

Leitura do Cloud Storage

curl

PowerShell

Extensão do Intérprete de código