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 Gemini API bietet die Codeausführung als Tool, ähnlich wie beim 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 folgenden Modelle unterstützen die Codeausführung:

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/v1/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/v1/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:

Gen AI SDK for Python

Gen AI SDK for Python installieren oder aktualisieren

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import (
    HttpOptions,
    Tool,
    ToolCodeExecution,
    GenerateContentConfig,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.0-flash-001"

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,
    ),
)
print("# Code:")
print(response.executable_code)
print("# Outcome:")
print(response.code_execution_result)

# Example response:
# # Code:
# def fibonacci(n):
#     if n <= 0:
#         return 0
#     elif n == 1:
#         return 1
#     else:
#         a, b = 0, 1
#         for _ in range(2, n + 1):
#             a, b = b, a + b
#         return b
#
# fib_20 = fibonacci(20)
# print(f'{fib_20=}')
#
# # Outcome:
# fib_20=6765

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/v1/projects/test-project/locations/us-central1/publishers/google/models/gemini-2.0-flash-001: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. Für den Funktionsaufruf ist eine zusätzliche GenerateContent-Anfrage erforderlich, um die Ausgabe jedes Funktionsaufrufs zurückzugeben.

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 für Eingabe- und Ausgabetokens werden Ihnen je nach verwendetem Gemini-Modell in Rechnung gestellt.

Weitere Informationen zur Abrechnung der Codeausführung:

  • Sie werden nur einmal für die Eingabetokens in Rechnung gestellt, die Sie an das Modell übergeben, und für die Zwischeneingabetokens, die vom Codeausführungstool generiert werden.
  • Sie werden für die endgültigen Ausgabetokens in Rechnung gestellt, die Ihnen in der API-Antwort zurückgegeben werden.

Diagramm des Abrechnungsvorgangs für die Verwendung des Tools zur Codeausführung, wie unten beschrieben.

  • Die Abrechnung erfolgt zum aktuellen Preis für Eingabe- und Ausgabetokens, je nachdem, welches Gemini-Modell Sie verwenden.
  • Wenn Gemini bei der Generierung Ihrer Antwort die Codeausführung verwendet, werden der ursprüngliche Prompt, der generierte Code und das Ergebnis des ausgeführten Codes als Zwischen-Tokens gekennzeichnet und als Eingabe-Tokens abgerechnet.
  • Gemini generiert dann eine Zusammenfassung und gibt den generierten Code, das Ergebnis des ausgeführten Codes und die endgültige Zusammenfassung zurück. Diese werden als Ausgabetokens abgerechnet.
  • Die Gemini API enthält in der API-Antwort eine Zwischentokenanzahl, damit Sie zusätzliche Eingabetokens im Blick behalten können, die über die in Ihrem ursprünglichen Prompt übergebenen hinausgehen.

Der generierte Code kann sowohl Text als auch multimodale Ausgaben wie Bilder enthalten.

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.