Codeausführung

Die Funktion Codeausfü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 Codeausfü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 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 Schritte zur Einrichtung und Konfiguration in der Kurzanleitung zur Gemini API ausgeführt haben.

Codeausführung aktivieren

Sie können das Modell so konfigurieren, dass es die Codeausführung verwendet, indem Sie sie bei der Konfiguration 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 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_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.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

Informationen zum Installieren oder Aktualisieren von Go

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=global
export GOOGLE_GENAI_USE_VERTEXAI=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 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_VERTEXAI=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

Informationen zum Installieren oder Aktualisieren von Java

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=global
export GOOGLE_GENAI_USE_VERTEXAI=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. 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:

Codeausführung im Chat verwenden

Sie können die Codeausfü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-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."
        }
      }
    ]
  }'

(Nur Gemini 3 Flash) Codeausführung mit Bildern verwenden

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

  • Bilder vergrößern und untersuchen: Erkennen, wenn Details zu klein sind (z. B. beim Lesen eines Messgeräts, das weit von der Kamera entfernt ist), und Code schreiben, um den Bereich zuzuschneiden und mit einer höheren Auflösung neu zu untersuchen.

  • Visuelle Mathematik: Führen Sie mehrstufige Berechnungen mit Code aus (z. B. Addieren von Posten auf einer Rechnung).

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

Wenn Sie die Codeausführung mit Bildern verwenden möchten, aktivieren Sie die Codeausführung bei der Konfiguration des Modells und senden Sie einen Prompt mit einem Bild, das das Modell untersuchen 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)]
    ),
)
      

Codeausführung im Vergleich zum Funktionsaufruf

Codeausführung und Funktionsaufruf sind ähnliche Funktionen:

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

Im Allgemeinen sollten Sie die Codeausführung bevorzugen, wenn sie Ihren Anwendungsfall abdecken kann. Die Codeausführung ist einfacher zu verwenden (Sie müssen sie nur aktivieren) und führt zu einer einzigen GenerateContent-Anfrage. Für den Funktionsaufruf ist eine zusätzliche GenerateContent-Anfrage erforderlich, um die Ausgabe von jedem Funktionsaufruf zurückzusenden.

In den meisten Fällen sollten Sie den Funktionsaufruf verwenden, wenn Sie eigene Funktionen haben, die Sie lokal ausführen möchten. Die Codeausführung sollten Sie verwenden, 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 Abrechnung erfolgt zum aktuellen Preis für Eingabe- und Ausgabetokens, je nachdem, welches Gemini-Modell Sie verwenden.

Hier sind einige 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 Zwischen-Eingabetokens, die vom Codeausführungstool verwendet werden.
  • Sie werden für die endgültigen Ausgabetokens in Rechnung gestellt, die in der API-Antwort an Sie zurückgegeben werden.

Diagramm des Abrechnungsablaufs für die Nutzung des Codeausführungstools, wie im folgenden Text beschrieben.

  • Die Abrechnung erfolgt zum aktuellen Preis für Eingabe- und Ausgabetokens, je nachdem, welches Gemini-Modell Sie verwenden.
  • Wenn Gemini die Codeausführung beim Generieren Ihrer Antwort verwendet, werden der ursprüngliche Prompt, der generierte Code und das Ergebnis des ausgeführten Codes als Zwischentokens gekennzeichnet und als Eingabetokens in Rechnung gestellt.
  • 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 in Rechnung gestellt.
  • 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 angegebenen 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. Es kann keine anderen Artefakte wie Mediendateien zurückgeben.
  • Das Codeausführungstool unterstützt keine Datei-URIs als Eingabe/Ausgabe. Das Codeausführungstool unterstützt jedoch die Dateieingabe und die Grafikausgabe 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 Codeausführungsergebnisses generieren lassen. Die unterstützten MIME-Typen für Inline-Bytes sind .cpp, .csv, .java, .jpeg, .js, .png, .py, .ts und .xml.
  • Die Codeausführung kann maximal 30 Sekunden dauern, bevor eine Zeitüberschreitung auftritt.
  • In einigen Fällen kann die Aktivierung der Codeausführung zu Regressionen in anderen Bereichen der Modellausgabe führen (z. B. beim Schreiben einer Geschichte).