Codeausführung

Die Funktion „Code-Ausführung“ der Gemini API ermöglicht es dem Modell, Python-Code zu generieren und auszuführen und iterativ aus den Ergebnissen zu lernen, bis das Modell eine endgültige Ausgabe erstellt hat. Sie können diese Code-Ausführungsfunktion verwenden, um Anwendungen zu erstellen, die die Vorteile codebasierter Schlussfolgerungen nutzen und Textausgaben erzeugen. Die Codeausführung können Sie beispielsweise in einer Anwendung verwenden, die Gleichungen löst oder Text verarbeitet.

Die Gemini API stellt die Codeausführung ähnlich wie den Funktionsaufruf als Tool zur Verfügung. Nachdem Sie die Codeausführung als Tool hinzugefügt haben, entscheidet das Modell, wann es sie verwendet.

Die Code-Ausführungsumgebung enthält die folgenden Bibliotheken. Sie können keine eigenen Bibliotheken installieren.

Unterstützte Modelle

Die folgenden Modelle unterstützen die Code-Ausführung:

Klicken, um unterstützte Modelle einzublenden

Erste Schritte mit der Code-Ausführung

In diesem Abschnitt wird davon ausgegangen, dass Sie die Einrichtungs- und Konfigurationsschritte unter Erste Schritte mit der Gemini Enterprise Agent Platform ausgeführt haben.

Code-Ausführung aktivieren

Sie können die Codeausführung für das Modell aktivieren, indem Sie sie beim Konfigurieren des Modells der Liste tools hinzufügen:

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Google 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=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

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

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

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

Go

Go installieren oder aktualisieren

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Google 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=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithCodeExec shows how to generate text using the code execution tool.
func generateWithCodeExec(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	prompt := "Calculate 20th fibonacci number. Then find the nearest palindrome to it."
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: prompt},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{CodeExecution: &genai.ToolCodeExecution{}},
		},
		Temperature: genai.Ptr(float32(0.0)),
	}
	modelName := "gemini-2.5-flash"

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

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

	// Example response:
	// Gemini: Okay, I can do that. First, I'll calculate the 20th Fibonacci number. Then, I need ...
	//
	// Language: PYTHON
	//
	// def fibonacci(n):
	//    ...
	//
	// fib_20 = fibonacci(20)
	// print(f'{fib_20=}')
	//
	// Outcome: OUTCOME_OK
	// fib_20=6765
	//
	// Now that I have the 20th Fibonacci number (6765), I need to find the nearest palindrome. ...
	// ...

	return nil
}

Node.js

Installieren

npm install @google/genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Google 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=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateAndExecuteCode(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents:
      'Calculate 20th fibonacci number. Then find the nearest palindrome to it.',
    config: {
      tools: [{codeExecution: {}}],
      temperature: 0,
    },
  });

  console.debug(response.executableCode);

  // Example response:
  // Code:
  // function fibonacci(n) {
  //   if (n <= 0) {
  //     return 0;
  //   } else if (n === 1) {
  //     return 1;
  //   } else {
  //     let a = 0, b = 1;
  //     for (let i = 2; i <= n; i++) {
  //       [a, b] = [b, a + b];
  //     }
  //     return b;
  //   }
  // }
  //
  // const fib20 = fibonacci(20);
  // console.log(`fib20=${fib20}`);

  console.debug(response.codeExecutionResult);

  // Outcome:
  // fib20=6765

  return response.codeExecutionResult;
}

Java

Java installieren oder aktualisieren

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Google 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=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolCodeExecution;

public class ToolsCodeExecWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text using the Code Execution tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set codeExecution tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().codeExecution(ToolCodeExecution.builder().build()).build())
              .temperature(0.0F)
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              "Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
              contentConfig);

      System.out.println("Code: \n" + response.executableCode());
      System.out.println("Outcome: \n" + response.codeExecutionResult());
      // Example response
      // Code:
      // def fibonacci(n):
      //    if n <= 0:
      //        return 0
      //    elif n == 1:
      //        return 1
      //    else:
      //        a, b = 1, 1
      //        for _ in range(2, n):
      //            a, b = b, a + b
      //        return b
      //
      // fib_20 = fibonacci(20)
      // print(f'{fib_20=}')
      //
      // Outcome:
      // fib_20=6765
      return response.executableCode();
    }
  }
}

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • GENERATE_RESPONSE_METHOD: Der Typ 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.
  • 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:

Code-Ausführung im Chat verwenden

Sie können die Code-Ausführung auch im Rahmen eines Chats verwenden.

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/test-project/locations/global/publishers/google/models/gemini-3.5-flash: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."
        }
      }
    ]
  }'

(Nur Gemini 3 Flash) Code-Ausführung mit Bildern verwenden

Gemini 3 Flash kann Python-Code schreiben und ausführen, um Bilder aktiv zu bearbeiten und zu prüfen. Sie können die Codeausführung mit Bildern für Folgendes verwenden:

  • Bilder zoomen und prüfen: Erkennen Sie, wenn Details zu klein sind (z. B. beim Ablesen eines Messgeräts, das weit von der Kamera entfernt ist), und schreiben Sie Code, um den Bereich zuzuschneiden und mit einer höheren Auflösung noch einmal zu prüfen.

  • Visuelle Mathematik: Mehrstufige Berechnungen mithilfe von Code ausführen (z. B. Einzelposten auf einem Beleg addieren).

  • Bildannotation: Bilder annotieren, um Fragen zu beantworten, z. B. Pfeile zwischen Objekten zeichnen, um Beziehungen darzustellen.

Wenn Sie die Code-Ausführung mit Bildern verwenden möchten, aktivieren Sie die Code-Ausführung, wenn Sie das Modell konfigurieren, und senden Sie einen Prompt mit einem Bild, das das Modell prüfen soll:

Python

# Example input image
image_path = "https://storage.googleapis.com/cloud-samples-data/generative-ai/image/chips.jpeg"
image_bytes = requests.get(image_path).content
image = types.Part.from_bytes(
  data=image_bytes, mime_type="image/jpeg"
)

response = client.models.generate_content(
    model=MODEL_ID,
    contents=[image, "Locate the ESMT chip. What are the numbers on the chip?"],
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution)]
    ),
)

Code-Ausführung im Vergleich zu Funktionsaufrufen

Code-Ausführung und Funktionsaufrufe sind ähnliche Funktionen:

  • Mit der Codeausführung kann das Modell Code im API-Backend in einer festen, isolierten Umgebung ausführen.
  • Mit Funktionsaufrufen 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 Code-Ausführung ist einfacher zu verwenden (Sie müssen sie nur aktivieren) und wird in einer einzigen GenerateContent-Anfrage aufgelöst. Für Funktionsaufrufe ist eine zusätzliche GenerateContent-Anfrage erforderlich, um die Ausgabe jedes Funktionsaufrufs zurückzusenden.

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

Abrechnung

Für die Aktivierung der Code-Ausführung über die Gemini API fallen keine zusätzlichen Gebühren an. Die Abrechnung erfolgt zum aktuellen Preis für Eingabe- und Ausgabetokens, je nachdem, welches Gemini-Modell Sie verwenden.

Hier sind ein paar weitere Dinge, die Sie zur Abrechnung der Code-Ausführung wissen sollten:

  • Ihnen werden nur einmal die Eingabetokens in Rechnung gestellt, die Sie an das Modell übergeben, und die Zwischeneingabetokens, die durch die Verwendung des Code-Ausführungstools generiert werden.
  • Ihnen werden die endgültigen Ausgabetokens in Rechnung gestellt, die in der API-Antwort zurückgegeben werden.

Diagramm des Abrechnungsablaufs für die Nutzung des Codeausführungstools, wie im Text 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 Code-Ausführung verwendet, werden der ursprüngliche Prompt, der generierte Code und das Ergebnis des ausgeführten Codes als Zwischentokens gekennzeichnet und als Eingabetokens abgerechnet.
  • Gemini erstellt 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 Anzahl von Zwischentokens, sodass Sie alle zusätzlichen Eingabetokens im Blick behalten können, die über die in Ihrem ursprünglichen Prompt übergebenen Tokens 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.
  • Das Tool zur Code-Ausführung unterstützt keine Datei-URIs als Eingabe/Ausgabe. Das Code-Ausführungstool unterstützt jedoch Dateieingaben und Diagrammausgaben als Inline-Bytes. Mit diesen Eingabe- und Ausgabefunktionen können Sie CSV- und Textdateien hochladen, Fragen zu den Dateien stellen und Matplotlib-Diagramme als Teil des Code-Ausführungsergebnisses generieren lassen. Die unterstützten MIME-Typen für Inline-Bytes sind .cpp, .csv, .java, .jpeg, .js, .png, .py, .ts und .xml.
  • Die Code-Ausführung kann maximal 30 Sekunden dauern, bevor eine Zeitüberschreitung auftritt.
  • In einigen Fällen kann die Aktivierung der Code-Ausführung zu Regressionen in anderen Bereichen der Modellausgabe führen (z. B. beim Schreiben einer Geschichte).

Best Practices und Hinweise

Beachten Sie bei der Verwendung der Code-Ausführung die folgenden Best Practices und Richtlinien:

  • Explizite Ausführungsanweisungen: Large Language Models verwenden standardmäßig linguistische Schlussfolgerungen, sofern Sie nichts anderes angeben. Verwenden Sie beim Bereitstellen von Anweisungen zur Codeausführung explizite Anweisungen (z. B. „Skript IMMER ausführen“ oder „NICHT direkt berechnen“).
  • Netzwerkisolation: Die Sandbox für die Codeausführung hat keinen Zugriff auf das öffentliche Internet. Scripts können keine externen HTTP-Anfragen stellen oder externe Ressourcen herunterladen.
  • Zustandslose Ausführung: Jede Ausführung erfolgt in einem sitzungsspezifischen Container. Dateien, die während einer Runde erstellt oder geändert werden, bleiben in nachfolgenden Runden oder Sitzungen nicht erhalten.
  • Abhängigkeiten: Es sind nur Standard-Python-Bibliotheken und vorinstallierte Pakete zur Datenbearbeitung (z. B. numpy oder pandas) verfügbar. Die Umgebung unterstützt keine dynamischen Laufzeitpaketinstallationen (z. B. pip install).
  • Standard-E/A: Schreiben Sie Skripts, die Eingaben von Befehlszeilenargumenten (sys.argv) oder Standardeingaben (sys.stdin) akzeptieren und das Ergebnis direkt in die Standardausgabe (sys.stdout) schreiben.