Questo documento mostra come registrare e utilizzare l'estensione Interprete di codice fornita da Google dalla console Google Cloud e dall'API Vertex AI. Questa estensione consente di generare ed eseguire codice Python per:
- Analizza, pulisci, trasforma e rimodella i tuoi set di dati
- Visualizza i dati in diagrammi e grafici
- Calcoli eseguiti
L'estensione Interprete di 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="}] 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
Per scoprire di più sulle estensioni di Google con tutorial end-to-end, consulta i seguenti blocchi note Jupyter:
- Flusso di lavoro degli analisti aziendali con Vertex AI Extensions: usa 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 delle 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 provenienti dai siti web. Utilizza l'estensione Interprete di codice per creare un report con tutti gli asset generati.
Colab | GitHub | Vertex AI Workbench - Lavorare con Pandas utilizzando l'estensione Interprete di codice di Vertex AI Extensions: 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 di codice per creare ed eseguire il deployment di un'applicazione web statica.
Colab | GitHub | Vertex AI Workbench
Prima di iniziare
- Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Attiva l'API Vertex AI.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Attiva l'API Vertex AI.
Registra, esegui query ed esegui l'estensione Interprete di 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 eseguire una query utilizzando la console Google Cloud o eseguirla utilizzando l'API Vertex AI.
Console
Registrare l'estensione
Per registrare l'estensione Interprete di codice utilizzando la console Google Cloud, segui questi passaggi.
Nella console Google Cloud, vai alla pagina Estensioni di Vertex AI.
Fai clic su Crea estensione.
Nella finestra di dialogo Crea una nuova estensione, procedi nel seguente modo:
- Nome estensione: inserisci un nome per l'estensione, ad esempio "code_interpreter_extension".
- Descrizione: (facoltativo) inserisci una descrizione dell'estensione, ad esempio "Un'estensione dell'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
.
- Nome API:
(Facoltativo) Nella sezione Configurazioni di runtime, specifica il bucket di input e il bucket di output.
- Il bucket di input è il bucket Cloud Storage che l'estensione utilizzerà per leggere i file di input, incluso il prefisso
gs://
, ad esempiogs://sample-bucket-name
. Se specificato, devi assegnare il ruoloroles/storage.objectViewer
su questo bucket all'account di servizio Vertex Extension Custom Code Service Agent. - Il bucket di output è il bucket Cloud Storage che l'estensione utilizzerà per scrivere i file di output, incluso il prefisso
gs://
, ad esempiogs://sample-bucket-name
. Se specificato, devi assegnare il ruoloroles/storage.objectUser
su questo bucket all'account di servizio Vertex Extension Custom Code Service Agent.
- Il bucket di input è il bucket Cloud Storage che l'estensione utilizzerà per leggere i file di input, incluso il prefisso
Fai clic su Crea estensione.
(Facoltativo) Eseguire una query sull'estensione
Puoi utilizzare la console Google Cloud per sperimentare l'estensione Interprete di codice. Per richiamare l'estensione con prompt in linguaggio naturale, procedi nel seguente modo:
Nella console Google Cloud, vai alla pagina Estensioni di Vertex AI.
Fai clic sul nome dell'estensione Interprete di codice per aprire la pagina Dettagli estensioni.
Nella casella Inserisci un messaggio, inserisci una query e visualizza la risposta. Espandi le sezioni Risposta dell'estensione per visualizzare il codice generato e eseguito dall'estensione per produrre il risultato.
L'esempio seguente mostra i risultati di una query che ha calcolato il valore medio di un elenco di numeri inseriti dall'utente.
REST
Registrare l'estensione
Invia una richiesta dell'API Vertex AI extensions.import
per registrare l'estensione Interprete di codice.
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.
- DISPLAY_NAME: l'estensione name mostrata agli utenti, ad esempio "my_code_interpreter_extension".
- DESCRIPTION (Facoltativo) L'estensione description mostrata agli utenti, ad esempio "Un'estensione per 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 dell'agente di servizio estensione Vertex AI per l'account di servizio specificato. - INPUT_BUCKET (facoltativo) il bucket Cloud Storage che verrà utilizzato dall'estensione per leggere i file di input, incluso il prefisso
gs://
, ad esempiogs://sample-bucket-name
. Se specificato, devi assegnare il ruoloroles/storage.objectViewer
su questo bucket all'account di servizio Vertex Extension Custom Code. - OUTPUT_BUCKET (Facoltativo) Il bucket Cloud Storage
che verrà utilizzato dall'estensione per scrivere i file di output, incluso il prefisso
gs://
, ad esempiogs://sample-bucket-name
. Se specificato, devi assegnare il ruoloroles/storage.objectUser
su questo bucket all'account di servizio Vertex Extension Custom Code.
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
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: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 il 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.
- Query con dati di 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, 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 nei 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
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
Dati incorporati
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 nei 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, 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 nei 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
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
Lettura Cloud Storage
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 nei Dettagli dell'estensione nella console Google Cloud.
- BUCKET_NAME: il bucket Cloud Storage che contiene il file CSV da stampare. Devi aver specificato questo bucket di input al momento della registrazione dell'estensione Interprete di 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
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