Codeausführung

Mit der Codeausführungsfunktion der Gemini API kann das Modell Python-Code generieren und ausführen und iterativ aus den Ergebnissen lernen, bis eine endgültige Ausgabe erreicht wird. Mit dieser Codeausführungsfunktion können Sie Anwendungen erstellen, die von codebasierter Argumentation profitieren und Textausgaben generieren. Sie können die Codeausführung beispielsweise in einer Anwendung verwenden, die Gleichungen löst oder Text verarbeitet.

Die Codeausführung ist sowohl in Vertex AI Studio als auch in der Gemini API verfügbar. In Vertex AI Studio können Sie die Codeausführung unter Erweiterte Einstellungen aktivieren. Die Gemini API bietet die Codeausführung als Tool, ähnlich wie der Funktionsaufruf. Nachdem Sie die Codeausführung als Tool hinzugefügt haben, entscheidet das Modell, wann es verwendet werden soll.

Die Codeausführungsumgebung umfasst die folgenden Bibliotheken. Sie können keine eigenen Bibliotheken installieren.

Unterstützte Modelle

Die Codeausführung wird vom gemini-2.0-flash-exp-Modell unterstützt.

Erste Schritte mit der Codeausführung

In diesem Abschnitt wird davon ausgegangen, dass Sie die Einrichtungs- und Konfigurationsschritte in der Kurzanleitung für die Gemini API ausgeführt haben.

Codeausführung für das Modell aktivieren

So aktivieren Sie die grundlegende Codeausführung:

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • GENERATE_RESPONSE_METHOD: Die Art der Antwort, die das Modell generieren soll. Wählen Sie eine Methode aus, mit der generiert wird, wie die Antwort des Modells zurückgegeben werden soll:
    • streamGenerateContent: Die Antwort wird während der Generierung gestreamt, um die Wahrnehmung der Latenz für menschliche Zielgruppen zu reduzieren.
    • generateContent: Die Antwort wird zurückgegeben, nachdem sie vollständig generiert wurde.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll. Folgende Optionen sind verfügbar:

    Klicken Sie, um eine unvollständige Liste der verfügbaren Regionen einzublenden

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: Ihre Projekt-ID.
  • MODEL_ID: Die Modell-ID des Modells, das Sie verwenden möchten.
  • ROLE: Die Rolle in einer Unterhaltung, die mit dem Inhalt verknüpft ist. Die Angabe einer Rolle ist auch bei Anwendungsfällen mit nur einem Schritt erforderlich. Unter anderem sind folgende Werte zulässig:
    • USER: Gibt Inhalte an, die von Ihnen gesendet werden
    • MODEL: Gibt die Antwort des Modells an.
  • TEXT
     Die Textanleitung, die in den Prompt eingefügt werden soll.

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. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben: 

cat > request.json << 'EOF'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
EOF

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben: 

@'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden: 

$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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

Python

from google import genai
from google.genai.types import Tool, ToolCodeExecution, GenerateContentConfig

client = genai.Client()
model_id = "gemini-2.0-flash-exp"

code_execution_tool = Tool(
    code_execution=ToolCodeExecution()
)
response = client.models.generate_content(
    model=model_id,
    contents="Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
    config=GenerateContentConfig(
        tools=[code_execution_tool],
        temperature=0,
    ),
)
for part in response.candidates[0].content.parts:
    if part.executable_code:
        print(part.executable_code)
    if part.code_execution_result:
        print(part.code_execution_result)
# Example response:
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='The 20th Fibonacci number is: 6765\n'
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='Lower Palindrome: 6666\nHigher Palindrome: 6776\nNearest Palindrome to 6765: 6776\n'

Go

import (
  "bytes"
  "context"
  "flag"
  "fmt"
  "io"

  genai "google.golang.org/genai"
)

// codeExecution generates code for the given text prompt using Code Execution as a Tool.
func codeExecution(w io.Writer) error {
  modelName := "gemini-2.0-flash-exp"
  client, err := genai.NewClient(context.TODO(), &genai.ClientConfig{})
  if err != nil {
    return fmt.Errorf("NewClient: %w", err)
  }

  codeExecTool := genai.Tool{
    CodeExecution: &genai.ToolCodeExecution{},
  }
  config := &genai.GenerateContentConfig{
    Tools: []*genai.Tool{&codeExecTool},
  }

  textpart := genai.Text(`Calculate 20th fibonacci number. Then find the nearest palindrome to it.`)

  result, err := client.Models.GenerateContent(context.TODO(), modelName,
    &genai.ContentParts{textpart}, config)
  if err != nil {
    return fmt.Errorf("GenerateContent: %w", err)
  }

  for _, part := range result.Candidates[0].Content.Parts {
    if part.ExecutableCode != nil {
      fmt.Fprintf(w, "Code (%s):\n%s\n", part.ExecutableCode.Language, part.ExecutableCode.Code)
    }
    if part.CodeExecutionResult != nil {
      fmt.Fprintf(w, "Result (%s):\n %s\n", part.CodeExecutionResult.Outcome, part.CodeExecutionResult.Output)
    }
  }
  return nil
}

Codeausführung in Google Chat verwenden

Sie können die Codeausführung auch in einem Chat verwenden.

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/test-project/locations/us-central1/publishers/google/models/gemini-2.0-flash-exp:generateContent -d \
$'{
    "tools": [{'code_execution': {}}],
    "contents": [
      {
        "role": "user",
        "parts": {
          "text": "Can you print \"Hello world!\"?"
        }
      },
      {
        "role": "model",
        "parts": [
          {
            "text": ""
          },
          {
            "executable_code": {
              "language": "PYTHON",
              "code": "\nprint(\"hello world!\")\n"
            }
          },
          {
            "code_execution_result": {
              "outcome": "OUTCOME_OK",
              "output": "hello world!\n"
            }
          },
          {
            "text": "I have printed \"hello world!\" using the provided python code block. \n"
          }
        ],
      },
      {
        "role": "user",
        "parts": {
          "text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."
        }
      }
    ]
  }'

Codeausführung im Vergleich zum Funktionsaufruf

Die Codeausführung und der Funktionsaufruf sind ähnliche Funktionen:

  • Bei der Codeausführung kann das Modell Code im API-Backend in einer festen, isolierten Umgebung ausführen.
  • Mit dem Funktionsaufruf können Sie die vom Modell angeforderten Funktionen in einer beliebigen Umgebung ausführen.

Im Allgemeinen sollten Sie die Codeausführung bevorzugen, wenn sie für Ihren Anwendungsfall geeignet ist. Die Codeausführung ist einfacher zu verwenden (Sie müssen sie nur aktivieren) und führt zu einer einzelnen GenerateContent-Anfrage, sodass nur eine Gebühr anfällt. Für den Funktionsaufruf ist eine zusätzliche GenerateContent-Anfrage erforderlich, um die Ausgabe jedes Funktionsaufrufs zurückzugeben. Daher fallen mehrere Kosten an.

In den meisten Fällen sollten Sie den Funktionsaufruf verwenden, wenn Sie eigene Funktionen haben, die Sie lokal ausführen möchten. Verwenden Sie die Codeausführung, wenn die API Python-Code für Sie schreiben und ausführen und das Ergebnis zurückgeben soll.

Abrechnung

Für die Aktivierung der Codeausführung über die Gemini API fallen keine zusätzlichen Kosten an. Die Kosten werden Ihnen zum aktuellen Tarif für Eingabe- und Ausgabezeichen in Rechnung gestellt.

Weitere Informationen zur Abrechnung der Codeausführung:

  • Die Eingabe-Tokens, die Sie an das Modell übergeben, werden Ihnen nur einmal in Rechnung gestellt. Außerdem werden Ihnen die endgültigen Ausgabe-Tokens in Rechnung gestellt, die vom Modell zurückgegeben werden.
  • Tokens, die generierten Code darstellen, werden als Ausgabetokens gezählt.
  • Ergebnisse der Codeausführung werden ebenfalls als Ausgabetokens gezählt.

Beschränkungen

  • Das Modell kann nur Code generieren und ausführen. Andere Artefakte wie Mediendateien können nicht zurückgegeben werden.
  • Die Funktion unterstützt keine Datei-I/O und keine Anwendungsfälle, bei denen keine Textausgabe erfolgt (z. B. Datenplots oder der Upload einer CSV-Datei).
  • Die Codeausführung kann maximal 30 Sekunden dauern, bevor eine Zeitüberschreitung auftritt.
  • In einigen Fällen kann die Aktivierung der Codeausführung zu Rückschritten in anderen Bereichen der Modellausgabe führen, z. B. beim Schreiben einer Geschichte.