Exécution du code

La fonctionnalité d'exécution de code de l'API Gemini permet au modèle de générer et d'exécuter du code Python ainsi que d'apprendre des résultats de façon itérative jusqu'à ce qu'il parvienne à une sortie finale. Vous pouvez vous servir de cette fonctionnalité pour créer des applications qui bénéficient d'un raisonnement basé sur du code et qui produisent des sorties textuelles. Par exemple, vous pouvez utiliser l'exécution de code dans une application qui résout des équations ou traite du texte.

L'API Gemini fournit l'exécution de code en tant qu'outil, tout comme l'appel de fonction. Ainsi, une fois que vous l'avez ajoutée en tant qu'outil, le modèle décide quand l'utiliser.

L'environnement d'exécution du code inclut les bibliothèques suivantes. Vous ne pouvez pas installer vos propres bibliothèques.

• Altair
• Chess
• Cv2
• Matplotlib
• Mpmath
• NumPy
• Pandas
• Pdfminer
• Reportlab
• Seaborn
• sklearn
• Statsmodels
• Striprtf
• SymPy
• Tabulate

Modèles compatibles

Les modèles suivants sont compatibles avec l'exécution de code :

• Gemini 2.5 Flash-Lite
  previewPreview
• Gemini 2.0 Flash avec l'API en direct
  previewPreview
• Optimiseur de modèle Vertex AI
  scienceExpérimental
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Premiers pas avec l'exécution de code

Cette section suppose que vous avez suivi les étapes de configuration décrites dans le guide de démarrage rapide de l'API Gemini.

Activer l'exécution de code sur le modèle

Vous pouvez activer l'exécution de code de base, comme indiqué ci-dessous :

pip install --upgrade google-genai

# 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

# 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},
		}},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{CodeExecution: &genai.ToolCodeExecution{}},
		},
		Temperature: genai.Ptr(0.0),
	}
	modelName := "gemini-2.0-flash-001"

	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
}

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

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"

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

$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

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Okay, I understand. You want me to calculate the sum of the first 10 positive integers and to use code to do so. Here's my plan: I will use a loop to add the numbers from 1 to 10 and then return the final sum.\n\n"
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "\ntotal = 0\nfor i in range(1, 11):\n    total += i\nprint(f'{total=}')\n"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OUTCOME_OK",
              "output": "total=55\n"
            }
          },
          {
            "text": "The sum of the first 10 positive numbers is 55.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.19436789,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.17441037
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.0685376,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14903527
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.23231025,
          "severity": "HARM_SEVERITY_LOW",
          "severityScore": 0.2436427
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08269742,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.10818888
        }
      ],
      "score": -0.50845032930374146,
      "avgLogprobs": -0.0046222757209431042
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 34,
    "candidatesTokenCount": 110,
    "totalTokenCount": 144,
    "billablePromptUsage": {
      "textCount": 119
    },
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2024-12-09T23:33:47.842964Z",
  "responseId": "W35XZ9S5M6acmecP3vDFkQU"
}

Utiliser l'exécution de code dans le chat

Vous pouvez également utiliser l'exécution de code dans un chat.

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."
        }
      }
    ]
  }'

Exécution de code ou appel de fonction

L'exécution de code et l'appel de fonction sont des fonctionnalités similaires :

• L'exécution de code permet au modèle d'exécuter du code dans le backend de l'API au sein d'un environnement fixe et isolé.
• L'appel de fonction permet d'exécuter les fonctions demandées par le modèle, dans l'environnement de votre choix.

En général, il est préférable d'utiliser l'exécution de code si elle peut gérer votre cas d'utilisation. L'exécution de code est plus simple à utiliser (il suffit de l'activer) et se résout en une seule requête GenerateContent. L'appel de fonction nécessite une requête GenerateContent supplémentaire pour renvoyer la sortie de chaque appel de fonction.

Dans la plupart des cas, vous devez utiliser l'appel de fonction si vous devez exécuter vos propres fonctions en local, et l'exécution de code si vous souhaitez que l'API écrive et exécute du code Python, et renvoie le résultat.

Facturation

L'exécution de code à partir de l'API Gemini n'entraîne aucuns frais supplémentaires. Vous serez facturé au tarif actuel des jetons d'entrée et de sortie en fonction du modèle Gemini que vous utilisez.

Voici quelques autres points à connaître concernant la facturation de l'exécution du code :

• Vous ne serez facturé qu'une seule fois pour les jetons d'entrée que vous transmettez au modèle et les jetons d'entrée intermédiaires générés par l'outil d'exécution de code.
• Vous êtes facturé pour les jetons de sortie finaux qui vous sont renvoyés dans la réponse de l'API.

• Vous êtes facturé au tarif actuel des jetons d'entrée et de sortie en fonction du modèle Gemini que vous utilisez.
• Si Gemini utilise l'exécution de code pour générer votre réponse, la requête d'origine, le code généré et le résultat du code exécuté sont désignés comme des jetons intermédiaires et sont facturés en tant que jetons d'entrée.
• Gemini génère ensuite un résumé et renvoie le code généré, le résultat du code exécuté et le résumé final. Ils sont facturés en tant que jetons de sortie.
• L'API Gemini inclut un nombre de jetons intermédiaires dans la réponse de l'API. Vous pouvez ainsi suivre tous les jetons d'entrée supplémentaires au-delà de ceux transmis dans votre requête initiale.

Le code généré peut inclure des sorties textuelles et multimodales, comme des images.

Limites

• Le modèle ne peut que générer et exécuter du code. Il ne peut pas renvoyer d'autres artefacts tels que des fichiers multimédias.
• L'outil d'exécution de code n'accepte pas les URI de fichier en tant qu'entrée/sortie. Toutefois, il accepte l'entrée de fichier et la sortie de graphique en tant qu'octets intégrés. Grâce à ces fonctionnalités d'entrée et de sortie, vous pouvez importer des fichiers CSV et des fichiers texte, poser des questions sur les fichiers et générer des graphiques Matplotlib dans le résultat de l'exécution du code. Les types MIME compatibles pour les octets intégrés sont .cpp, .csv, .java, .jpeg, .js, .png, .py, .ts et .xml.
• L'exécution du code peut durer au maximum 30 secondes avant l'expiration du délai.
• Dans certains cas, l'activation de l'exécution du code peut entraîner des régressions dans d'autres domaines de la sortie du modèle (par exemple, l'écriture d'une histoire).