johannstark/GeminiRobotics-Skills

Gemini Robotics-ER 2

Gemini Robotics-ER (raisonnement incarné) est un modèle vision-langage pour les robots. Il voit des images, des vidéos et de l'audio. Il renvoie du texte : des points et boîtes JSON, des plans, ou des appels à vos fonctions robotiques. Il ne pilote jamais directement les moteurs. ER propose, et le code déterministe exécute.

Tout ce qui suit a été vérifié par rapport à la documentation officielle (ai.google.dev, Oct 2026), le notebook ER 2 (gemini_robotics_er.ipynb), et google-genai 2.31 / @google/genai 2.30.

1. Choisir le point de terminaison et l'API

Modèle	API	Utilisation pour	Non supporté
gemini-robotics-er-2-preview	API Interactions client.interactions.create (également generateContent hérité)	Pointage, boîtes, trajectoires, logique spatiale, exécution de code, orchestration par appel de fonctions, recherche de moments vidéo et progression	API Live
gemini-robotics-er-2-streaming-preview	API Live client.aio.live.connect / ai.live.connect (WebSocket)	Agents temps réel : vidéo continue à ≤1 FPS, audio, appels d'outils BLOQUANTS	Sortie structurée, exécution de code, mise en cache, Interactions
gemini-robotics-er-1.6-preview	—	Obsolète depuis le 31 août 2026. Remplacez simplement la chaîne du modèle. La progression vidéo et le streaming nécessitent ER 2.

Les deux points de terminaison ER 2 acceptent du texte, des images, des vidéos et de l'audio, et ne produisent que du texte. Limites : 131 072 tokens d'entrée et 65 536 tokens de sortie. La pensée par défaut est high. Les niveaux sont minimal, low, medium et high. La documentation recommande medium comme le meilleur équilibre entre latence et qualité.

2. Choisir le motif

Besoin d'une cible ponctuelle pour un mouvement scripté ?         -> Requête spatiale (points / boîtes)    references/spatial-reasoning.md
Texte minuscule, jauges, comptage, recadrer/zoomer, annoter ?     -> Vision agentique (code_execution)   references/agentic-vision.md
Tâche multi-étapes via votre API robotique, tour par tour ?       -> Orchestration (appel de fonctions)  references/orchestration.md
Cela a-t-il fonctionné ? Quand ? Où en sommes-nous ?              -> Compréhension vidéo                  references/video-progress.md
Réagir en continu à une caméra / voix, boucle < 1 s ?            -> API Live + modèle streaming          references/live-api.md
Formes requête/réponse, détails SDK, migration ?                  -> Référence API Interactions            references/interactions-api.md

scripts/er_tools.py fournit des aides testées : encodage d'images, formats de réponse, un analyseur défensif, la boucle d'orchestration, le téléversement vidéo et l'analyse des horodatages. Lancez-le avec --selftest (pas de clé requise), ou --help.

3. Appels minimaux corrects

Python (pip install "google-genai>=2.9.0" ; lit GEMINI_API_KEY) :

from google import genai
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[{"type": "user_input", "content": [                       # ou une liste plate de parties
        {"type": "image", "data": png_b64, "mime_type": "image/png"},  # média AVANT le texte
        {"type": "text", "text": "Pointe vers le cube rouge. Les points sont [y, x] normalisés de 0 à 1000."},
    ]}],
    generation_config={"thinking_level": "medium"},
    response_format={"type": "text", "mime_type": "application/json", "schema": {
        "type": "object", "required": ["items"], "properties": {"items": {"type": "array", "items": {
            "type": "object", "required": ["point", "label"], "properties": {
                "point": {"type": "array", "items": {"type": "integer"}}, "label": {"type": "string"}}}}}}},
)
items = json.loads(interaction.output_text)["items"]

TypeScript (@google/genai >= 2.3.0 ; les champs de requête sont en snake_case ; exécuter côté serveur) :

import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const interaction = await client.interactions.create({
  model: 'gemini-robotics-er-2-preview',
  input: [{ type: 'image', data: pngB64, mime_type: 'image/png' }, { type: 'text', text: prompt }],
  generation_config: { thinking_level: 'medium' },
  response_format: { type: 'text', mime_type: 'application/json', schema },
});
const parsed = JSON.parse(interaction.output_text ?? '{}');

Lisez la réponse avec interaction.output_text (texte final), interaction.steps (chronologie typée : thought, function_call, code_execution_call, code_execution_result, model_output), et interaction.id (passez-le comme previous_interaction_id).

4. Règles qui préviennent la plupart des bugs

1. Les coordonnées sont [y, x], normalisées de 0 à 1000, relatives à l'image que vous avez envoyée. Les boîtes sont [ymin, xmin, ymax, xmax]. Convertissez avec u = x/1000*W et v = y/1000*H. Indiquez le format dans chaque prompt.
2. Utilisez les formes Interactions. input=[{"type": "image" | "text" | "video", ...}], generation_config={...} et response_format={...}. Ne passez jamais config=types.GenerateContentConfig(...), des images PIL, ou lisez .text / .function_calls sur une Interaction. Ceux-ci appartiennent à generateContent.
3. tools, system_instruction et generation_config sont par tour. Renvoyez-les à chaque interactions.create, y compris les tours qui utilisent previous_interaction_id.
4. N'utilisez pas thinking_budget avec ER 2 / Gemini 3+. Cela peut renvoyer des erreurs 400. Utilisez thinking_level.
5. Analysez défensivement, même avec un schéma. Supprimez les délimiteurs, découpez jusqu'au JSON externe, supprimez les doublons et les coordonnées hors limites, et limitez le compte (er_tools.parse_er_json).
6. La caméra de capture doit être identique à la caméra de rétroprojection : même pose, intrinsèques, recadrage et rapport hauteur/largeur. Empêchez le robot d'occulter la cible lors de la capture.
7. Vos fonctions robotiques renvoient des résultats réels. En cas d'échec, envoyez is_error: true avec une raison pour que le modèle réplanifie. Limitez les boucles d'outils avec max_steps. Validez chaque cible par rapport à l'espace de travail et aux limites articulaires avant de bouger.
8. API Live : utilisez uniquement des outils "behavior": "BLOCKING", envoyez au plus 1 image vidéo par seconde, attendez turn_complete avant le prochain heartbeat (sinon l'interruption interrompt l'action), et gérez tool_call_cancellation.
9. Clés : les clés API sans restriction obtiennent une erreur 403, donc ajoutez des restrictions dans AI Studio. N'envoyez jamais de clé dans un navigateur. Utilisez un proxy backend pour Interactions, et des jetons éphémères pour Live (ils ne fonctionnent qu'avec Live).
10. Stockage : les interactions sont stockées par défaut (store=true : 55 jours payant, 1 jour gratuit). store=false désactive previous_interaction_id. Interactions est une fonctionnalité de l'API Gemini Developer, et les URI gs:// ne sont pas lisibles, donc utilisez l'API Files.

5. Prompts qui fonctionnent (de la documentation et du notebook)

• Utilisez un langage simple. Si un terme échoue, essayez un synonyme ("rondelle" ou "anneau").
• Dites "NE détectez PAS les éléments qui ne correspondent que partiellement à la description" pour réduire les faux positifs.
• Limitez les comptes ("pas plus de 25 éléments"). Demandez un point par requête lorsque vous avez besoin d'une partie spécifique.
• Divisez les tâches complexes en prompts séparés, et exécutez les requêtes indépendantes en parallèle (le notebook utilise un ThreadPoolExecutor).
• Pour la précision, interrogez plusieurs fois et prenez le point médian.
• Redimensionnez les images à environ 800 px de large (le notebook le fait) pour économiser des tokens. Recadrez ou zoomez pour les petits objets.
• Pensée : utilisez low pour la détection simple ou le pointage, et high pour le comptage, le raisonnement sur la charge utile ou l'affordance, la détection de succès et la vidéo. medium est le compromis par défaut.
• Avec plusieurs images ou grilles vidéo, décrivez la disposition dans le prompt ("les 4 premières images = début, les 4 dernières = maintenant" ; "vues de gauche à droite : dessus, poignet").

6. Passage 2D à 3D (résumé)

Configuration	Méthode
Simulateur navigateur (Three.js)	Lancer un rayon depuis la caméra de capture à travers NDC (x/500-1, 1-y/500). Voir le skill threejs-rendering.
Python MuJoCo	Rendre la profondeur depuis la même caméra et déprojeter (er_point_to_world dans mujoco-physics/scripts/panda_pick_place.py). Vérifier la segmentation pour l'occlusion.
RGB-D réel	Z = profondeur médiane, X = (u−cx)Z/fx, Y = (v−cy)Z/fy, puis T_base←cam.
RGB réel, table uniquement	Intersecter le rayon avec le plan z = z_table, puis ajouter la moitié de la hauteur de l'objet.

Un échantillon de profondeur ou un lancer de rayon touche la surface supérieure, donc décalez vers le bas jusqu'à la hauteur de préhension. L'aspect de la boîte donne le lacet de la pince : fermez sur le petit côté. Une grille d'entiers de 0 à 1000 quantifie approximativement à FOV/1000 par unité (environ 1 mm/unité pour une vue de 1 m de large).

7. Dans la démo Franka

La démo de prise et dépôt Franka (React + Vite + mujoco-js + Three.js) est l'application de référence à partir de laquelle ces compétences ont été construites. Les noms de fichiers ci-dessous s'y réfèrent.

• App.tsx::handleErSend capture un PNG ≤640 px depuis une vue de dessus fixe et appelle ER. Elle utilise SDK 1.x ai.models.generateContent avec thinkingBudget: 0. Les points et les centres de boîtes sont projetés en 3D avec RenderSystem.project2DTo3D. SequenceAnimator exécute ensuite une prise aveugle en 15 étapes pour chaque cible. Il n'y a pas de vérification, d'orchestration ou d'API Live.
• La clé est exposée au navigateur via define de Vite (process.env.API_KEY). C'est acceptable pour une démo mais pas pour la production.
• Voir references/interactions-api.md#migrating-the-franka-demo pour la différence exacte 1.x→2.x, et references/orchestration.md / references/video-progress.md pour ajouter un comportement en boucle fermée.

8. Sécurité

ER peut halluciner ou faire correspondre partiellement des objets. Traitez chaque sortie comme une proposition :

• Vérifiez les limites de l'espace de travail, l'accessibilité (résidu IK), les collisions et les limites de vitesse.
• Exigez une confirmation humaine pour les actions importantes, et conservez un arrêt d'urgence physique.
• Développez en simulation derrière la même API robotique avant de passer au matériel.
• Les données de la caméra et du micro peuvent capturer des personnes. Obtenez le consentement, floutez les visages et minimisez la rétention. Voir https://deepmind.google/models/gemini-robotics/safety.