Extension de l'interpréteur de code

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 :

  • Analyser, nettoyer, transformer et remodeler vos ensembles de données
  • Visualiser les données dans des graphiques
  • Effectuer 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 code_interpreter.yaml OpenAPI Specification.

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

    

Avant de commencer

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

  3. Verify that billing is enabled for your Google Cloud project.

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

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

  6. Verify that billing is enabled for your Google Cloud project.

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

  8. Enregistrer, interroger et exécuter l'extension de l'interpréteur de code

    Les sections suivantes expliquent comment enregistrer l'extension Code Interpreter à 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

    Pour enregistrer l'extension de l'interpréteur de code à l'aide de la console Google Cloud , procédez comme suit.

    1. Dans la console Google Cloud , accédez à la page Extensions de Vertex AI.

      Accéder à Vertex AI Extensions

    2. Cliquez sur Créer une extension.

    3. 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.
    4. 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.
    5. (Facultatif) Dans la section Configurations d'environnement d'exécution, indiquez le bucket d'entrée et le bucket de sortie.

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

    1. Dans la console Google Cloud , accédez à la page Extensions de Vertex AI.

      Accéder à Vertex AI Extensions

    2. Cliquez sur le nom de l'extension Code Interpreter pour ouvrir la page Détails des extensions.

      Nom de l'interpréteur de code.

    3. Dans la zone Saisissez un message, saisissez une requête, puis consultez 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 qui a calculé la valeur moyenne d'une liste de nombres saisis par l'utilisateur.

      Requête de valeur moyenne.

    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, effectuez les remplacements suivants :

    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, effectuez les remplacements suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • REGION : région Compute Engine.
    • EXTENSION_ID : ID de votre extension d'interpréteur de code répertorié dans les détails de l'extension de 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, effectuez les remplacements suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • REGION : région Compute Engine.
    • EXTENSION_ID : ID de votre extension d'interpréteur de code répertorié dans les détails de l'extension de 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, effectuez les remplacements suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • REGION : région Compute Engine.
    • EXTENSION_ID : ID de votre extension d'interpréteur de code répertorié dans les détails de l'extension de 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, effectuez les remplacements suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • REGION : région Compute Engine.
    • EXTENSION_ID : ID de votre extension d'interpréteur de code répertorié dans les détails de l'extension de 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