Utiliser Gemini 3.8 Flash sur EvoLink : guide de mise en production

Démarrage rapide

curl https://direct.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "Return three rollout risks for an AI API migration."}
    ],
    "max_tokens": 500
  }'

Ce dont vous avez besoin

• Un compte EvoLink et une clé API stockée dans une variable d'environnement, jamais commitée dans le dépôt.
• Un client capable d'envoyer des requêtes JSON en HTTPS, ou un SDK compatible OpenAI avec une base_url personnalisée.
• Un petit jeu d'évaluation représentatif et des règles d'acceptation mesurables.
• Une journalisation de l'ID du modèle, du statut, de la latence, de l'usage de tokens, des retries et de l'acceptation applicative.
• Un modèle de fallback tel que Gemini 3.7 Flash pendant le déploiement.

Gemini 3.8 Flash accepte du texte, des images, de la vidéo, de l'audio et des PDF en entrée, et renvoie du texte. Google documente un contexte d'entrée de 1 048 576 tokens et jusqu'à 65 536 tokens en sortie. Considérez ces limites comme une capacité, pas comme une raison de remplir chaque requête.

Choisir la surface d'API

EvoLink expose deux styles de requête utiles pour les charges Gemini :

Exemple Python compatible OpenAI

Installez le package Python OpenAI, puis pointez-le vers EvoLink :

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["EVOLINK_API_KEY"],
    base_url="https://direct.evolink.ai/v1",
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {
            "role": "system",
            "content": "Answer with concise, testable recommendations.",
        },
        {
            "role": "user",
            "content": "Review this deployment plan and identify missing rollback gates.",
        },
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

Gardez la première requête simple. Confirmez l'authentification, l'accès à la route, le parsing de la réponse et les champs d'usage avant d'ajouter des outils, du contexte long ou du streaming.

Exemple de requête native Gemini

curl "https://direct.evolink.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Create a five-step canary checklist for this API release."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 800,
      "thinkingConfig": {"thinkingLevel": "medium"}
    }
  }'

Niveaux de thinking et règles de migration

Quand vous migrez un client Gemini plus ancien, auditez les points suivants :

Une requête qui renvoie HTTP 200 ne suffit pas. Revalidez la sortie structurée, les arguments d'outils, l'état multi-tours et le comportement de refus après la migration.

Entrée multimodale sans gaspiller le contexte

Le modèle comprend le texte, les images, la vidéo, l'audio et les PDF, mais une fenêtre de 1M tokens ne rend pas utile chaque gros payload. Construisez le contexte délibérément :

• Incluez les sections de document ou les segments de média nécessaires à la décision.
• Gardez les instructions système stables, les consignes de dépôt et les schémas d'outils dans un préfixe constant pour que le cache ait une chance d'aider.
• Récupérez les preuves pertinentes avant d'attacher une archive entière.
• Fixez un budget de sortie adapté à la tâche ; le maximum de 65 536 tokens est un plafond.
• Enregistrez séparément les tokens d'entrée et les tokens lus en cache pour que le « contexte long » ne masque pas une dépense évitable.

Pour les longs documents répétés, comparez le comportement des hits de cache sur un préfixe de prompt stable. Le tarif de lancement de Google pour la lecture de cache est de $0.075 par million de tokens jusqu'au 31 décembre 2026, mais la facturation EvoLink doit être vérifiée dans votre compte en direct.

Mise en production en cinq étapes

1. Vérifier l'accès et les tarifs

Créez une clé de test restreinte, confirmez que le modèle apparaît dans les routes disponibles du compte, envoyez une petite requête et vérifiez l'enregistrement d'usage ou de facturation qui en résulte. Une page modèle publique confirme une disponibilité prévue, pas le chemin d'appel propre à votre compte.

2. Valider le contrat de requête

Testez d'abord les requêtes synchrones. Testez ensuite, comme cas séparés, le streaming, la sortie structurée, les outils, le contexte long et l'entrée multimodale. Cela isole les échecs de protocole des échecs de qualité du modèle.

3. Rejouer un jeu d'évaluation figé

Comparez 3.8 Flash à la référence actuelle au même niveau de thinking. Mesurez la réussite au premier passage, les livrables acceptés, les tokens de sortie et de thinking, les hits de cache, les tool calls valides, la latence, les corrections humaines et le taux de fallback.

4. Canary sur du trafic observable

Commencez par un petit pourcentage ou une classe de charge à faible risque. Attachez l'ID du modèle choisi et la cohorte d'évaluation à chaque trace. Évitez toute promotion automatique fondée sur le seul succès HTTP agrégé.

5. Promouvoir ou revenir en arrière selon des seuils écrits

Ne promouvez le modèle que s'il franchit des seuils prédéfinis de qualité, de coût et de latence. Revenez en arrière en restaurant la valeur de modèle précédente dès que les erreurs critiques, le coût par tâche acceptée ou la latence dépassent leur limite.

La gestion des erreurs qui a sa place en production

N'utilisez des retries bornés que pour les échecs transitoires : limites de débit, indisponibilité en amont ou timeouts de transport. Ne réessayez pas à l'identique des payloads mal formés ou des paramètres non pris en charge.

Comportement recommandé :

• Réessayez les échecs transitoires avec backoff exponentiel et jitter.
• Fixez un nombre maximal de tentatives et une échéance de bout en bout.
• Réutilisez une stratégie d'idempotence là où l'application peut produire des effets de bord.
• Journalisez les ID de requête et les corps d'erreur nettoyés ; ne journalisez jamais les clés API ni les prompts sensibles.
• Routez vers un fallback testé quand l'échéance ou le seuil d'erreurs est atteint.
• Traitez les erreurs 4xx répétées comme un problème de contrat à corriger, pas comme un manque de capacité qu’il suffirait d’attendre.

Checklist d'observabilité

Pour chaque requête, capturez :

• la fonctionnalité applicative et la cohorte d'évaluation ;
• l'ID de modèle demandé et l'ID de modèle servi ;
• le protocole et la famille d'endpoint ;
• le niveau de thinking et la limite de sortie ;
• les tokens d'entrée, de sortie, de thinking et de lecture de cache quand ils sont renvoyés ;
• la latence, le statut, la classe d'erreur et le nombre de retries ;
• la validité des tool calls ou le résultat de la validation de schéma ;
• l'acceptation applicative, la correction par un relecteur et l'issue du fallback.

Ces données permettent à un gateway d'API unifié de soutenir la sélection de modèle au lieu de devenir un proxy opaque. Vous pouvez garder plusieurs routes Gemini derrière un seul client tout en sachant laquelle crée de la valeur.

Les erreurs de configuration les plus fréquentes

• Envoyer gemini-3-8-flash au lieu de gemini-3.8-flash comme ID de modèle.
• Utiliser des contents natifs Gemini sur l'endpoint compatible OpenAI.
• Compter sur la rétrogradation silencieuse de minimal vers low, combiner thinkingBudget et thinkingLevel, s'appuyer sur des contrôles d'échantillonnage ignorés, ou terminer la conversation par le rôle model.
• Remplir la fenêtre de contexte sans récupération ni filtrage par pertinence.
• Supposer que le tarif public de Google est identique au tarif en direct du compte EvoLink.
• Déclarer le succès après un seul HTTP 200 sans vérifier la forme de la réponse et la facturation.
• Changer le modèle de production par défaut sans voie de fallback mesurée.

FAQ

Quel est l'ID du modèle Gemini 3.8 Flash ?

Quel endpoint EvoLink dois-je utiliser ?

Puis-je utiliser le SDK Python OpenAI ?

Par quel niveau de thinking commencer ?

Gemini 3.8 Flash prend-il en charge les images, la vidéo, l'audio et les PDF ?

Oui, comme modalités d'entrée. Il renvoie du texte et ne propose pas de génération d'images, d'audio ni de flux en direct.

3.8 Flash est-il moins cher que 3.7 Flash ?

Pas selon la grille tarifaire pendant la période de lancement de Google : leurs tarifs d'entrée, de sortie et de lecture de cache sont identiques. Google indique que 3.8 consomme plus de tokens ; comparez donc le coût complet par tâche acceptée.

Comment confirmer que mon intégration est prête pour la production ?

Vérifiez un appel réussi et son enregistrement de facturation, testez chaque fonctionnalité de protocole que vous utilisez, rejouez un jeu d'évaluation figé, faites un canary sur du trafic réel et conservez un rollback explicite.

Où comparer toutes les routes Gemini ?

Sources et notes de vérification

• Google : lancement de Gemini 3.8 Flash
• Google AI for Developers : modèle Gemini 3.8 Flash
• Google AI for Developers : tarifs de l'API Gemini
• Google Cloud : guide Gemini 3.8 Flash
• EvoLink : démarrage rapide de l'API Gemini native
• EvoLink : référence de l'API Gemini native
• EvoLink : démarrage rapide compatible OpenAI pour Gemini