Diese Seite wurde von der Cloud Translation API übersetzt.

Code Interpreter-Erweiterung

In diesem Dokument erfahren Sie, wie Sie die von Google bereitgestellte Code Interpreter-Erweiterung ü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:

Datasets analysieren, bereinigen, transformieren und umgestalten
Daten in Diagrammen und Grafiken visualisieren
Berechnungen ausfü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 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

Hinweise

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.

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

Verify that billing is enabled for your Google Cloud project.

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

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

Verify that billing is enabled for your Google Cloud project.

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

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.

Konsole

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- und den Ausgabebucket 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 dem Dienstkonto des Dienst-Agents für benutzerdefinierten Vertex-Erweiterungscode die Rolle roles/storage.objectViewer für diesen Bucket 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 dem Dienstkonto des Dienst-Agents für benutzerdefinierten Vertex-Erweiterungscode die Rolle roles/storage.objectUser für diesen Bucket 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 natürlichsprachlichen Prompts 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 Anfrage ein und sehen Sie sich die Antwort an. Maximieren Sie die Abschnitte mit den Erweiterungsantworten, um den Code zu sehen, der von der Erweiterung generiert und ausgeführt wurde, um das Ergebnis zu erzeugen.

Das folgende Beispiel zeigt die Ergebnisse einer Abfrage, mit der der Mittelwert einer Liste von Zahlen berechnet wurde, die vom Nutzer eingegeben wurden.

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: Die 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 des Dienst-Agents für benutzerdefinierten Vertex-Erweiterungscode 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 dem Dienstkonto des Dienst-Agents für benutzerdefinierten Vertex-Erweiterungscode die Rolle roles/storage.objectUser für diesen Bucket 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 Anfrage 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: „Gib die Dateidaten aus.“
Abfrage mit Cloud Storage-Daten: Cloud Storage-Daten lesen.

Einfache Abfrage

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code Interpreter-Erweiterung, die in den Erweiterungsdetails der Google Cloud -Konsole 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

Inlinedaten

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code Interpreter-Erweiterung, die in den Erweiterungsdetails der Google Cloud -Konsole 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

Dateiausgabe

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code Interpreter-Erweiterung, die in den Erweiterungsdetails der Google Cloud -Konsole aufgeführt ist.
FILE_NAME: Die CSV-Dateidaten im Anfragebody werden in diese Datei im Arbeitsverzeichnis geschrieben.
BASE64_ENCODED_FILE_BYTES: Die Dateibytes 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-Lesevorgang

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
REGION: Eine Compute Engine-Region.
EXTENSION_ID: Die ID Ihrer Code Interpreter-Erweiterung, die in den Erweiterungsdetails der Google Cloud -Konsole 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 CSV-Dateidaten, die in BUCKET_NAME ausgegeben werden sollen.

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

Code Interpreter-Erweiterung Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweise

Code Interpreter-Erweiterung registrieren, abfragen und ausführen

Konsole

REST

curl

PowerShell

Einfache Abfrage

curl

PowerShell

Inlinedaten

curl

PowerShell

Dateiausgabe

curl

PowerShell

Cloud Storage-Lesevorgang

curl

PowerShell

Code Interpreter-Erweiterung