Ce document explique comment enregistrer et utiliser l'extension de l'interpréteur de code fournie par Google à partir de la console Google Cloud et de l'API Vertex AI. Cette extension vous permet de générer et d'exécuter du code Python pour :
- Analysez, nettoyez, transformez et remodelez vos ensembles de données
- Visualiser des données dans des graphiques
- Exécuter des calculs
L'extension de l'interpréteur de code utilise code_interpreter_tool
pour générer et exécuter du code Python à partir d'une description en langage naturel. code_interpreter_tool
est défini dans un fichier de Spécification OpenAPI 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 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
Pour en savoir plus sur les extensions Google avec des tutoriels de bout en bout, consultez les notebooks Jupyter suivants :
- Workflow des analystes commerciaux avec Vertex AI Extensions : utilisez l'extension Code Interpreter et l'extension Vertex AI Search pour remplir un rapport de recherche sur les opportunités d'investissement dans le logement pour les partenaires commerciaux.
Colab | GitHub | Vertex AI Workbench - Exploration des données et entraînement des modèles avec l'interpréteur de code des extensions Vertex AI : effectuez des tâches de data science ordinaires, telles que l'analyse d'ensembles de données et l'entraînement des modèles.
Colab | GitHub | Vertex AI Workbench - Workflow d'analyse des avis sur les jeux avec Vertex AI Extensions : utilisez l'extension Code Interpreter pour analyser les avis sur les jeux dans Steam. Utilisez l'extension Vertex AI Search pour résumer les avis sur les jeux provenant de sites Web. Utilisez l'extension de l'interpréteur de code pour créer un rapport avec tous les éléments générés.
Colab | GitHub | Vertex AI Workbench - Travailler avec Pandas à l'aide de l'extension Vertex AI Extensions Code Interpreter : utilisez le code DataFrame pandas généré par l'extension Code Interpreter pour travailler avec des ensembles de données particulièrement volumineux.
Colab | GitHub | Vertex AI Workbench - Workflow de développeur Web avec Vertex AI Extensions : utilisez l'extension Code Interpreter pour créer et déployer une application Web statique.
Colab | GitHub | Vertex AI Workbench
Avant de commencer
- 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.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Vertex AI API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Vertex AI API.
Enregistrer, interroger et exécuter l'extension de l'interpréteur de code
Les sections suivantes expliquent comment enregistrer l'extension Code Interpréteur à l'aide de la console Google Cloud et de l'API Vertex AI. Une fois l'extension enregistrée, vous pouvez l'interroger à l'aide de la console Google Cloud ou l'exécuter à l'aide de l'API Vertex AI.
Console
Enregistrer l'extension
Procédez comme suit pour enregistrer l'extension de l'interpréteur de code à l'aide de la console Google Cloud.
Dans la console Google Cloud, accédez à la page Extensions de Vertex AI.
Cliquez sur Créer une extension.
Dans la boîte de dialogue Créer une extension, procédez comme suit :
- Nom de l'extension: saisissez un nom pour votre extension, par exemple "code_interpreter_extension".
- Description (facultatif): saisissez une description de l'extension, par exemple "Une extension de l'interpréteur de code".
- Type d'extension: sélectionnez
Code interpreter
.
Dans la section Fichier de spécification OpenAPI qui s'affiche, vérifiez que les champs suivants sont correctement définis :
- Nom d'API:
code_interpreter_tool
- Description de l'API:
Tool to generate and run valid Python code from a natural language description, or to run custom Python code...
- Source:
Cloud Storage
- Spécification OpenAPI:
vertex-extension-public/code_interpreter.yaml
- Authentication:
Google service account
.
- Nom d'API:
(Facultatif) Dans la section Configurations d'exécution, indiquez le bucket d'entrée et le bucket de sortie.
- Le bucket d'entrée est le bucket Cloud Storage que l'extension utilisera pour lire les fichiers d'entrée, y compris le préfixe
gs://
, par exemplegs://sample-bucket-name
. Si spécifié, vous devez attribuer le rôleroles/storage.objectViewer
sur ce bucket au compte de service Agent de service de code personnalisé de l'extension Vertex. - Le bucket de sortie est le bucket Cloud Storage que l'extension utilisera pour écrire des fichiers de sortie, y compris le préfixe
gs://
(par exemple,gs://sample-bucket-name
). Si spécifié, vous devez attribuer le rôleroles/storage.objectUser
sur ce bucket au compte de service Agent de service de code personnalisé de l'extension Vertex.
- Le bucket d'entrée est le bucket Cloud Storage que l'extension utilisera pour lire les fichiers d'entrée, y compris le préfixe
Cliquez sur Créer une extension.
(Facultatif) Interroger l'extension
Vous pouvez utiliser la console Google Cloud pour tester votre extension Code Interpreter. Pour appeler l'extension avec des requêtes en langage naturel, procédez comme suit:
Dans la console Google Cloud, accédez à la page Extensions de Vertex AI.
Cliquez sur le nom de l'extension Code Interpreter pour ouvrir la page Détails des extensions.
Dans la zone Saisir un message, saisissez une requête, puis affichez la réponse. Développez les sections "Réponse d'extension" pour afficher le code que l'extension a généré et exécuté pour produire le résultat.
L'exemple suivant montre les résultats d'une requête ayant calculé la valeur moyenne d'une liste de nombres saisis par l'utilisateur.
REST
Enregistrer l'extension
Envoyez une requête extensions.import
de l'API Vertex AI pour enregistrer l'extension de l'interpréteur de code.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud.
- REGION : région Compute Engine.
- DISPLAY_NAME : extension de nom visible par les utilisateurs, telle que "my_code_interpreter_extension".
- DESCRIPTION (facultatif) : description de l'extension affichée pour les utilisateurs, telle que "Une extension de l'interpréteur de code".
- SERVICE_ACCOUNT (facultatif) : l'extension Code Interpreter utilise GOOGLE_SERVICE_ACCOUNT_AUTH comme indiqué dans l'exemple de corps de la requête. Si vous ne spécifiez pas de compte de service, l'extension utilise le compte de service Agent de service de l'extension Vertex AI par défaut.
Si vous spécifiez un autre compte de service, accordez l'autorisation
iam.serviceAccounts.getAccessToken
au compte de service de l'agent de service Vertex AI Extension sur le compte de service spécifié. - INPUT_BUCKET (facultatif) : bucket Cloud Storage que l'extension utilisera pour lire les fichiers d'entrée, y compris le préfixe
gs://
, par exemplegs://sample-bucket-name
. Si spécifié, vous devez attribuer le rôleroles/storage.objectViewer
sur ce bucket au compte de service Agent de service de code personnalisé de l'extension Vertex. - OUTPUT_BUCKET (facultatif) : bucket Cloud Storage que l'extension utilisera pour écrire des fichiers de sortie, y compris le préfixe
gs://
, par exemplegs://sample-bucket-name
. Si spécifié, vous devez attribuer le rôleroles/storage.objectUser
sur ce bucket au compte de service Agent de service de code personnalisé de l'extension Vertex.
Méthode HTTP et URL :
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import
Corps JSON de la requête :
{ "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" } } }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Exécuter l'extension
Vous pouvez envoyer une opération execute
à l'API Vertex AI pour générer et exécuter du code Python en fonction d'une requête en langage naturel.
Exemples de requêtes:
- Requête simple: déterminer la valeur maximale d'une liste de nombres.
- Interroger les données intégrées : les données à interroger sont fournies dans le corps de la requête.
- Requête avec des données de fichier : imprimer les données de fichier.
- Requête avec des données Cloud Storage : lire les données Cloud Storage.
Requête simple
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud.
- REGION : région Compute Engine.
- EXTENSION_ID: ID de votre extension de l'interpréteur de code répertorié dans les détails de l'extension dans la console Google Cloud.
Méthode HTTP et URL :
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Corps JSON de la requête :
{ "operation_id":"generate_and_execute", "operation_params":{ "query":"find the max value in the list: [1,2,3,4,-5]" } }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Données intégrées
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud.
- REGION : région Compute Engine.
- EXTENSION_ID: ID de votre extension de l'interpréteur de code répertorié dans les détails de l'extension dans la console Google Cloud.
Méthode HTTP et URL :
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Corps JSON de la requête :
{ "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" } }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Imprimer des fichiers
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud.
- REGION : région Compute Engine.
- EXTENSION_ID: ID de votre extension de l'interpréteur de code répertorié dans les détails de l'extension dans la console Google Cloud.
- FILE_NAME : les données du fichier CSV dans le corps de la requête sont écrites dans ce fichier dans le répertoire de travail.
- BASE64_ENCODED_FILE_BYTES : les octets de fichier dans le corps de la requête doivent être encodés en base64.
Méthode HTTP et URL :
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Corps JSON de la requête :
{ "operation_id":"generate_and_execute", "operation_params":{ "query":"print the csv file", "files":[ { "name":"FILE_NAME", "contents":"BASE64_ENCODED_FILE_BYTES" } ] } }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Lecture Cloud Storage
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud.
- REGION : région Compute Engine.
- EXTENSION_ID: ID de votre extension de l'interpréteur de code répertorié dans les détails de l'extension dans la console Google Cloud.
- BUCKET_NAME: bucket Cloud Storage contenant le fichier CSV à imprimer. Vous devez avoir enregistré ce bucket d'entrée lorsque vous avez enregistré l'extension de l'interpréteur de code.
- FILE_NAME : données du fichier CSV dans BUCKET_NAME à imprimer.
Méthode HTTP et URL :
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
Corps JSON de la requête :
{ "operation_id":"generate_and_execute", "operation_params":{ "query":"print the csv file", "file_gcs_uris": ["gs://BUCKET_NAME/FILE_NAME"] } }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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