Code Interpreter-Erweiterung

In diesem Dokument erfahren Sie, wie Sie die von Google bereitgestellte Erweiterung des Code Interpreter über die Google Cloud Console und die Vertex AI API registrieren und verwenden. Mit dieser Erweiterung können Sie Python-Code generieren und ausführen, um Folgendes zu tun:

Datasets analysieren, bereinigen, transformieren und umformen
Daten in Diagrammen und Grafiken visualisieren
Berechnungen durchführen

Die Erweiterung „Code Interpreter“ verwendet code_interpreter_tool, um Python-Code aus einer Beschreibung in natürlicher Sprache zu generieren und auszuführen. Das code_interpreter_tool ist in der code_interpreter.yaml-Datei der OpenAPI-Spezifikation definiert.

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

In den folgenden Jupyter-Notebooks erfahren Sie mehr über Google-Erweiterungen mit End-to-End-Anleitungen:

Business Analyst-Workflow mit Vertex AI Extensions: Verwenden Sie die Code Interpreter-Erweiterung und die Vertex AI Search-Erweiterung, um einen Forschungsbericht zu Immobilieninvestitionen für Business-Stakeholder fertigzustellen.
Colab | GitHub | Vertex AI Workbench
Datenexploration und Modelltraining mit dem Vertex AI Extensions Code Interpreter: Führen Sie normale Data-Science-Aufgaben wie die Dataset-Analyse und das Modelltraining aus.
Colab | GitHub | Vertex AI Workbench
Workflow zur Analyse von Spielbewertungen mit Vertex AI Extensions: Verwenden Sie die Erweiterung "Code Interpreter", um Spielrezensionen von Steam zu analysieren. Verwenden Sie die Vertex AI Search-Erweiterung, um Rezensionen von Websites zusammenzufassen. Mit der Erweiterung „Code Interpreter“ können Sie einen Bericht mit allen generierten Assets erstellen.
Colab | GitHub | Vertex AI Workbench
Mit Pandas mithilfe der Erweiterung "Vertex AI Extensions Code Interpreter" arbeiten: Verwenden Sie pandas-DataFrames-Code, der von der Code Interpreter-Erweiterung generiert wird, um mit besonders großen Datasets zu arbeiten.
Colab | GitHub | Vertex AI Workbench
Workflow für Webentwickler mit Vertex AI Extensions: Verwenden Sie die Erweiterung "Code Interpreter", um eine statische Webanwendung zu erstellen und bereitzustellen.
Colab | GitHub | Vertex AI Workbench

Vorbereitung

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

Code Interpreter-Erweiterung registrieren, abfragen und ausführen

In den folgenden Abschnitten wird gezeigt, wie Sie die Erweiterung „Code Interpreter“ mit der Google Cloud Console und der Vertex AI API registrieren. Nach der Registrierung der Erweiterung können Sie sie mit der Google Cloud Console abfragen oder mit der Vertex AI API ausführen.

Console

Erweiterung registrieren

Führen Sie die folgenden Schritte aus, um die Code Interpreter-Erweiterung bei der Google Cloud Console zu registrieren.

Rufen Sie in der Google Cloud Console die Seite „Vertex AI Extensions“ auf.

Zu „Vertex AI Extensions“
Klicken Sie auf Erweiterung erstellen.
Führen Sie im Dialogfeld Neue Erweiterung erstellen die folgenden Schritte aus:
- Erweiterungsname: Geben Sie einen Namen für die Erweiterung ein, z. B. „code_interpreter_extension“.
- Beschreibung: (Optional) Geben Sie eine Beschreibung für die Erweiterung ein, z. B. „Eine Code-Interpreter-Erweiterung“.
- Erweiterungstyp: Wählen Sie Code interpreter aus.
Prüfen Sie im nun angezeigten Abschnitt OpenAPI-Spezifikationsdatei, ob die folgenden Felder korrekt festgelegt sind:
- API-Name: code_interpreter_tool.
- API-Beschreibung: Tool to generate and run valid Python code from a natural language description, or to run custom Python code...
- Quelle: Cloud Storage.
- OpenAPI-Spezifikation: vertex-extension-public/code_interpreter.yaml.
- Authentifizierung: Google service account.
(Optional) Geben Sie im Bereich Laufzeitkonfigurationen den Eingabe-Bucket und den Ausgabe-Bucket an.
- Der Eingabe-Bucket ist der Cloud Storage-Bucket, den die Erweiterung zum Lesen von Eingabedateien verwendet, einschließlich des Präfixes gs://, z. B. gs://sample-bucket-name. Wenn angegeben, müssen Sie die Rolle roles/storage.objectViewer für diesen Bucket dem Dienstkonto Dienst-Agent für benutzerdefinierten Vertex Extension Code zuweisen.
- Der Ausgabe-Bucket ist der Cloud Storage-Bucket, in den die Erweiterung zum Schreiben von Ausgabedateien verwendet wird, einschließlich des Präfixes gs://, z. B. gs://sample-bucket-name. Wenn angegeben, müssen Sie die Rolle roles/storage.objectUser für diesen Bucket dem Dienstkonto Dienst-Agent für benutzerdefinierten Vertex Extension Code zuweisen.
Klicken Sie auf Erweiterung erstellen.

Optional: Erweiterung abfragen

Sie können die Google Cloud Console verwenden, um mit Ihrer Code Interpreter-Erweiterung zu experimentieren. Führen Sie die folgenden Schritte aus, um die Erweiterung mit Aufforderungen in natürlicher Sprache aufzurufen.

Rufen Sie in der Google Cloud Console die Seite „Vertex AI Extensions“ auf.

Zu „Vertex AI Extensions“
Klicken Sie auf den Namen der Erweiterung „Code Interpreter“, um die Seite Erweiterungsdetails zu öffnen.
Geben Sie im Feld Nachricht eingeben eine Abfrage ein und sehen Sie sich die Antwort an. Maximieren Sie die Abschnitte zur Antwort der Erweiterung, um den Code anzuzeigen, den die Erweiterung generiert und ausgeführt hat, um das Ergebnis zu erzeugen.

Das folgende Beispiel zeigt die Ergebnisse einer Abfrage, die den Mittelwert einer Liste von Zahlen berechnet hat, die der Nutzer eingegeben hat.

REST

Erweiterung registrieren

Senden Sie eine Vertex AI API-extensions.import-Anfrage, um die Code Interpreter-Erweiterung zu registrieren.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: ID Ihres Google Cloud-Projekts.
REGION: Eine Compute Engine-Region.
DISPLAY_NAME: Die Namenserweiterung, die Nutzern angezeigt wird, z. B. „my_code_interpreter_extension“.
DESCRIPTION: (Optional) Die Beschreibung der Erweiterung, die Nutzern angezeigt wird, z. B. „Eine Code Interpreter-Erweiterung“.
SERVICE_ACCOUNT: (Optional) Die Erweiterung „Code Interpreter“ verwendet GOOGLE_SERVICE_ACCOUNT_AUTH, wie im Beispielanfragetext gezeigt. Wenn Sie kein Dienstkonto angeben, verwendet die Erweiterung das Standarddienstkonto Vertex AI Extensions-Dienst-Agent. Wenn Sie ein anderes Dienstkonto angeben, gewähren Sie dem Dienstkonto des Vertex AI Extensions-Dienst-Agents im angegebenen Dienstkonto die Berechtigung iam.serviceAccounts.getAccessToken.
INPUT_BUCKET: (Optional) Der Cloud Storage-Bucket, den die Erweiterung zum Lesen von Eingabedateien verwendet, einschließlich des Präfixes gs://. Beispiel: gs://sample-bucket-name. Wenn angegeben, müssen Sie die Rolle roles/storage.objectViewer für diesen Bucket dem Dienstkonto Dienst-Agent für benutzerdefinierten Vertex-Code zuweisen.
OUTPUT_BUCKET: (Optional) Der Cloud Storage-Bucket, den die Erweiterung zum Schreiben von Ausgabedateien verwendet, einschließlich des Präfixes gs://, z. B. gs://sample-bucket-name. Wenn angegeben, müssen Sie die Rolle roles/storage.objectUser für diesen Bucket dem Dienstkonto Dienst-Agent für benutzerdefinierten Vertex-Code zuweisen.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud CLI angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Erweiterung ausführen

Sie können einen execute-Vorgang an die Vertex AI API senden, um Python-Code basierend auf einer Abfrage in natürlicher Sprache zu generieren und auszuführen.

Beispielabfragen:

Einfache Abfrage: Maximalwert einer Zahlenliste bestimmen.
Inline-Daten abfragen: Die abzufragenden Daten werden im Anfragetext bereitgestellt.
Mit Dateidaten abfragen: Dateidaten drucken.
Mit Cloud Storage-Daten abfragen: Cloud Storage-Daten lesen.

Einfache Abfrage

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: ID Ihres Google Cloud-Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code-Interpreter-Erweiterung, die in den Erweiterungsdetails in der Google Cloud Console aufgeführt ist.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Inline-Daten

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: ID Ihres Google Cloud-Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code-Interpreter-Erweiterung, die in den Erweiterungsdetails in der Google Cloud Console aufgeführt ist.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Dateidruck

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: ID Ihres Google Cloud-Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code-Interpreter-Erweiterung, die in den Erweiterungsdetails in der Google Cloud Console aufgeführt ist.
FILE_NAME: Die CSV-Dateidaten im Anfragetext werden in diese Datei im Arbeitsverzeichnis geschrieben.
BASE64_ENCODED_FILE_BYTES: Dateibyte im Anfragetext müssen base64-codiert sein.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Cloud Storage-Lesevorgänge

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: ID Ihres Google Cloud-Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code-Interpreter-Erweiterung, die in den Erweiterungsdetails in der Google Cloud Console aufgeführt ist.
BUCKET_NAME: Der Cloud Storage-Bucket, der die zu druckende CSV-Datei enthält. Registrierung der Code Interpreter-Erweiterung angegeben haben.
FILE_NAME: Die zu druckenden CSV-Dateidaten in BUCKET_NAME.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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