Questa pagina è stata tradotta dall'API Cloud Translation.

Estensione Interprete codice

Questo documento mostra come registrare e utilizzare l'estensione Interprete codice fornita da Google dalla console Google Cloud e dall'API Vertex AI. Questa estensione consente di genera ed esegui il codice Python per:

Analizza, pulisci, trasforma e rimodella i tuoi set di dati
Visualizzare i dati in tabelle e grafici
Calcoli eseguiti

L'estensione Interprete codice utilizza code_interpreter_tool per generare ed eseguire codice Python da una descrizione in linguaggio naturale. code_interpreter_tool è definito in un file code_interpreter.yaml della specifica 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

Per scoprire di più sulle estensioni Google con tutorial end-to-end, consulta quanto segue. Blocchi note Jupyter:

Flusso di lavoro degli analisti aziendali con Vertex AI Extensions: utilizza l'estensione Interprete di codice e l'estensione Vertex AI Search per completare un report di ricerca sulle opportunità di investimento immobiliare per gli stakeholder aziendali.
Colab | GitHub | Vertex AI Workbench
Esplorazione dei dati e addestramento dei modelli con l'interprete del codice per le estensioni di Vertex AI: esegui le normali attività di data science, come l'analisi dei set di dati e l'addestramento dei modelli.
Colab | GitHub | Vertex AI Workbench
Flusso di lavoro di analisi delle recensioni dei giochi con le estensioni di Vertex AI: utilizza l'estensione Interprete di codice per analizzare le recensioni dei giochi da Steam. Utilizza l'estensione Vertex AI Search per riepilogare le recensioni dei giochi dei siti web. Utilizza l'estensione Interprete codice per creare un report con tutti gli asset generati.
Colab | GitHub | Vertex AI Workbench
Utilizzo di Pandas con l'estensione Interprete di codice delle estensioni di Vertex AI: utilizza il codice DataFrames pandas generato dall'estensione Interprete di codice per lavorare con set di dati in particolare di grandi dimensioni.
Colab | GitHub | Vertex AI Workbench
Flusso di lavoro per sviluppatori web con le estensioni Vertex AI: utilizza l'estensione Interprete codice per creare e implementare un'applicazione web statica.
Colab | GitHub | Vertex AI Workbench

Prima di iniziare

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

Registra, esegui query ed esegui l'estensione Interprete codice

Le sezioni seguenti mostrano come registrare l'estensione Interprete di codice utilizzando la console Google Cloud e l'API Vertex AI. Dopo aver registrato l'estensione, puoi la query utilizzando la console Google Cloud oppure eseguirla utilizzando l'API Vertex AI.

Console

Registrare l'estensione

Esegui i seguenti passaggi per registrare l'estensione Interprete codice utilizzando la console Google Cloud.

Nella console Google Cloud, vai a Vertex AI Estensioni.

Vai alle estensioni di Vertex AI
Fai clic su Crea estensione.
Nella finestra di dialogo Crea una nuova estensione:
- Nome estensione: inserisci un nome per l'estensione, ad esempio "code_interpreter_extension".
- (Facoltativo) Descrizione:inserisci una descrizione dell'estensione, ad esempio "Un'estensione di un interprete di codice".
- Tipo di estensione: seleziona Code interpreter.
Nella sezione File di specifica OpenAPI visualizzata, verifica che i seguenti campi siano impostati correttamente:
- Nome API: code_interpreter_tool.
- Descrizione API: Tool to generate and run valid Python code from a natural language description, or to run custom Python code...
- Fonte: Cloud Storage.
- Specifiche OpenAPI: vertex-extension-public/code_interpreter.yaml.
- Autenticazione: Google service account.
(Facoltativo) Nella sezione Configurazioni di runtime, fornisci il bucket di input e il bucket di output.
- Il bucket di input è Bucket Cloud Storage che l'estensione utilizzerà per leggere i file di input, incluso il prefisso gs://, ad esempio gs://sample-bucket-name. Se specificato, devi assegnare il valore roles/storage.objectViewer su questo bucket all'account di servizio Vertex Extension Custom Code.
- Il bucket di output è il bucket Cloud Storage che l'estensione utilizzerà per scrivere i file di output, incluso il prefisso gs://, ad esempio gs://sample-bucket-name. Se specificato, devi assegnare il valore roles/storage.objectUser su questo bucket all'account di servizio Vertex Extension Custom Code.
Fai clic su Crea estensione.

(Facoltativo) Eseguire una query sull'estensione

Puoi utilizzare la console Google Cloud per fare esperimenti con l'estensione Interprete codice. Per richiamare l'estensione con i seguenti comandi, procedi nel seguente modo: prompt in linguaggio naturale.

Nella console Google Cloud, vai alla pagina Estensioni di Vertex AI.

Vai a Vertex AI Extensions
Fai clic sul nome dell'estensione Interprete di codice per aprire i dettagli delle estensioni .
Nella casella Inserisci un messaggio, inserisci una query e visualizza la risposta. Espandi Sezioni Risposta dell'estensione per visualizzare il codice generato dall'estensione eseguito per produrre il risultato.

L'esempio seguente mostra i risultati di una query che calcolato il valore medio di un elenco di numeri inseriti dall'utente.

REST

Registrare l'estensione

Invia una richiesta per l'API Vertex AI extensions.import per registrare l'estensione Interprete codice.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
REGION: una regione Compute Engine.
DISPLAY_NAME: il nome mostrata agli utenti, ad esempio "my_code_interpreter_extension".
DESCRIPTION: (facoltativo) l'estensione description mostrato agli utenti, ad esempio "Estensione di un interprete di codice".
SERVICE_ACCOUNT: (facoltativo) l'estensione Interprete di codice utilizza GOOGLE_SERVICE_ACCOUNT_AUTH come mostrato nel corpo della richiesta di esempio. Se non specifichi un account di servizio, l'estensione utilizza l'account di servizio predefinito Vertex AI Extension Service Agent. Se specifichi un account di servizio diverso, concedi l'autorizzazione iam.serviceAccounts.getAccessToken all'account di servizio Vertex AI Extension Service Agent nell'account di servizio specificato.
INPUT_BUCKET: (facoltativo) il campo Bucket Cloud Storage che l'estensione utilizzerà per leggere i file di input, incluso il prefisso gs://, ad esempio gs://sample-bucket-name. Se specificato, devi assegnare il ruolo roles/storage.objectViewer a questo bucket all'account di servizio Vertex Extension Custom Code Service Agent.
OUTPUT_BUCKET: (facoltativo) il bucket Cloud Storage che l'estensione utilizzerà per scrivere i file di output, incluso il prefisso gs://, ad esempio gs://sample-bucket-name. Se specificato, devi assegnare il ruolo roles/storage.objectUser a questo bucket all'account di servizio Vertex Extension Custom Code Service Agent.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

{
  "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"
     }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: Il comando seguente presuppone che tu abbia eseguito l'accesso a l'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud di Google. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Esegui l'estensione

Puoi inviare un'operazione execute all'API Vertex AI per generare ed eseguire codice Python in base a una query in linguaggio naturale.

Esempi di query:

Query semplice: trova il valore massimo di un elenco di numeri.
Dati in linea della query: i dati su cui eseguire la query vengono forniti nel corpo della richiesta.
Esegui query con i dati del file: stampa i dati del file.
Query con i dati Cloud Storage: lettura dei dati Cloud Storage.

Query semplice

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
REGION: una regione di Compute Engine.
EXTENSION_ID: l'ID dell'estensione dell'interprete di codice elencato in Dettagli dell'estensione nella console Google Cloud.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dati in linea

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
REGION: una regione di Compute Engine.
EXTENSION_ID: l'ID dell'estensione dell'interprete di codice elencato in Dettagli dell'estensione nella console Google Cloud.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

{
  "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"
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Stampa di file

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
REGION: una regione di Compute Engine.
EXTENSION_ID: l'ID dell'estensione dell'interprete di codice elencato in Dettagli dell'estensione nella console Google Cloud.
FILE_NAME: i dati del file CSV nel corpo della richiesta vengono scritti in questo file nella directory di lavoro.
BASE64_ENCODED_FILE_BYTES: i byte del file nel corpo della richiesta devono avere codifica Base64.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Lettura di Cloud Storage

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
REGION: una regione di Compute Engine.
EXTENSION_ID: l'ID dell'estensione dell'interprete di codice elencato nel Dettagli dell'estensione nella console Google Cloud.
BUCKET_NAME: il bucket Cloud Storage contenente il file CSV da stampare. Devi aver specificato questo bucket di input quando hai registrato l'estensione di interpretazione del codice.
FILE_NAME: i dati del file CSV in BUCKET_NAME da stampare.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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