johannstark/GeminiRobotics-Skills

Gemini Robotics-ER 2

Gemini Robotics-ER (Embodied Reasoning) ist ein visuell-sprachliches Modell für Roboter. Es sieht Bilder, Video und Audio. Es gibt Text zurück: JSON-Punkte und -Boxen, Pläne oder Aufrufe an Ihre Roboterfunktionen. Es steuert niemals direkt Motoren. ER schlägt vor, und deterministischer Code führt aus.

Alles hier wurde gegen die offiziellen Dokumentationen (ai.google.dev, Okt. 2026), das ER 2 Notebook (gemini_robotics_er.ipynb) und google-genai 2.31 / @google/genai 2.30 geprüft.

1. Wählen Sie den Endpunkt und die API

Modell	API	Verwendung für	Nicht unterstützt
gemini-robotics-er-2-preview	Interactions API client.interactions.create (auch Legacy generateContent)	Zeigen, Boxen, Trajektorien, räumliche Logik, Code-Ausführung, Funktionsaufruf-Orchestrierung, Videomomentfindung und Fortschritt	Live API
gemini-robotics-er-2-streaming-preview	Live API client.aio.live.connect / ai.live.connect (WebSocket)	Echtzeit-Agenten: kontinuierliches Video mit ≤1 FPS, Audio, BLOCKING Tool-Aufrufe	Strukturierte Ausgabe, Code-Ausführung, Caching, Interactions
gemini-robotics-er-1.6-preview	—	Veraltet ab 31. Aug. 2026. Ersetzen Sie die Modellzeichenfolge. Videofortschritt und Streaming benötigen ER 2.

Beide ER 2 Endpunkte akzeptieren Text, Bilder, Video und Audio und geben nur Text aus. Grenzen: 131.072 Eingabe-Token und 65.536 Ausgabe-Token. Das Standard-Denken ist high. Ebenen sind minimal, low, medium und high. Die Dokumente empfehlen medium als Kompromiss zwischen Latenz und Qualität.

2. Wählen Sie das Muster

Benötigen Sie ein One-Shot-Ziel für eine skriptgesteuerte Bewegung?         -> Räumliche Abfrage (Punkte / Boxen)    references/spatial-reasoning.md
Kleiner Text, Messgeräte, Zählen, Zuschneiden/Zoomen, Annotieren?         -> Agentisches Sehen (code_execution)   references/agentic-vision.md
Mehrschrittige Aufgabe durch Ihre Roboter-API, Schritt für Schritt?       -> Orchestrierung (function calling)  references/orchestration.md
Hat es funktioniert? Wann? Wie weit fortgeschritten?                      -> Videoverständnis               references/video-progress.md
Kontinuierlich auf Kamera / Stimme reagieren, < 1 s Schleife?             -> Live API + Streaming-Modell        references/live-api.md
Anfrage/Antwort-Formen, SDK-Details, Migration?                            -> Interactions API-Referenz        references/interactions-api.md

scripts/er_tools.py bietet getestete Helfer: Bildkodierung, Antwortformate, einen defensiven Parser, die Orchestrierungsschleife, Video-Upload und Zeitstempel-Parsing. Führen Sie es mit --selftest aus (kein Schlüssel nötig) oder --help.

3. Minimale korrekte Aufrufe

Python (pip install "google-genai>=2.9.0"; liest 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": [                       # oder eine flache Liste von Teilen
        {"type": "image", "data": png_b64, "mime_type": "image/png"},  # Medien VOR dem Text
        {"type": "text", "text": "Zeige auf den roten Würfel. Punkte sind [y, x] normalisiert auf 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; Anfragefelder sind snake_case; führen Sie es serverseitig aus):

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 ?? '{}');

Lesen Sie die Antwort mit interaction.output_text (endgültiger Text), interaction.steps (typisierte Zeitleiste: thought, function_call, code_execution_call, code_execution_result, model_output) und interaction.id (übergeben Sie es als previous_interaction_id).

4. Regeln, die die meisten Fehler verhindern

1. Koordinaten sind [y, x], normalisiert 0–1000, relativ zu dem Bild, das Sie gesendet haben. Boxen sind [ymin, xmin, ymax, xmax]. Konvertieren Sie mit u = x/1000*W und v = y/1000*H. Geben Sie das Format in jeder Eingabeaufforderung an.
2. Verwenden Sie die Interactions-Formen. input=[{"type": "image" | "text" | "video", ...}], generation_config={...} und response_format={...}. Übergeben Sie niemals config=types.GenerateContentConfig(...), PIL-Bilder oder lesen Sie .text / .function_calls auf einer Interaction. Diese gehören zu generateContent.
3. tools, system_instruction und generation_config sind pro Durchlauf. Senden Sie sie bei jedem interactions.create erneut, einschließlich der Durchläufe, die previous_interaction_id verwenden.
4. Verwenden Sie thinking_budget nicht mit ER 2 / Gemini 3+. Es kann 400-Fehler zurückgeben. Verwenden Sie thinking_level.
5. Parsen Sie defensiv, selbst mit einem Schema. Entfernen Sie Begrenzungen, schneiden Sie auf das äußere JSON zu, entfernen Sie Duplikate und Koordinaten außerhalb des Bereichs und begrenzen Sie die Anzahl (er_tools.parse_er_json).
6. Die Aufnahmekamera muss mit der Rückprojektionskamera übereinstimmen: gleiche Pose, intrinsische Parameter, Beschnitt und Seitenverhältnis. Halten Sie den Roboter davon ab, das Ziel bei der Aufnahme zu verdecken.
7. Ihre Roboterfunktionen geben reale Ergebnisse zurück. Senden Sie bei Fehlern is_error: true mit einem Grund, damit das Modell neu plant. Begrenzen Sie Tool-Schleifen mit max_steps. Validieren Sie jedes Ziel vor einer Bewegung auf den Arbeitsraum und die Gelenkgrenzen.
8. Live API: Verwenden Sie nur "behavior": "BLOCKING" Tools, senden Sie höchstens 1 Videobild pro Sekunde, warten Sie auf turn_complete vor dem nächsten Heartbeat (ansonsten bricht Barge-in die Aktion ab), und behandeln Sie tool_call_cancellation.
9. Schlüssel: Uneingeschränkte API-Schlüssel geben 403, fügen Sie daher Einschränkungen in AI Studio hinzu. Versenden Sie niemals einen Schlüssel an einen Browser. Verwenden Sie einen Backend-Proxy für Interactions und ephemere Token für Live (diese funktionieren nur mit Live).
10. Speicher: Interactions werden standardmäßig gespeichert (store=true: 55 Tage kostenpflichtig, 1 Tag kostenlos). store=false deaktiviert previous_interaction_id. Interactions ist ein Feature der Gemini Developer API, und gs://-URIs sind nicht lesbar, verwenden Sie daher die Files API.

5. Eingabeaufforderung, die funktioniert (aus den Dokumenten und dem Notebook)

• Verwenden Sie einfache Sprache. Wenn ein Begriff fehlschlägt, versuchen Sie ein Synonym ("Unterlegscheibe" oder "Ring").
• Sagen Sie "Erkenne KEINE Objekte, die nur teilweise zur Beschreibung passen", um Fehlalarme zu reduzieren.
• Begrenzen Sie die Anzahl ("nicht mehr als 25 Objekte"). Fragen Sie nach einem Punkt pro Abfrage, wenn Sie ein bestimmtes Teil benötigen.
• Teilen Sie komplexe Aufgaben in separate Eingabeaufforderungen auf und führen Sie unabhängige Abfragen parallel aus (das Notebook verwendet einen ThreadPoolExecutor).
• Fragen Sie für Präzision mehrmals ab und nehmen Sie den Median-Punkt.
• Ändern Sie die Bildgröße auf etwa 800 Pixel Breite (das Notebook tut dies), um Token zu sparen. Beschneiden oder zoomen Sie für kleine Objekte.
• Denken: Verwenden Sie low für einfache Erkennung oder Zeigen und high für Zählen, Nutzen oder Affordanz-Reasoning, Erfolgserkennung und Video. medium ist der Standard-Kompromiss.
• Beschreiben Sie bei mehreren Bildern oder Videogittern das Layout in der Eingabeaufforderung ("erste 4 Bilder = Start, letzte 4 = jetzt"; "Ansichten von links nach rechts: oben, Handgelenk").

6. 2D-zu-3D-Anhebung (Zusammenfassung)

Setup	Methode
Browser-Sim (Three.js)	Raycast von der Aufnahmekamera durch NDC (x/500-1, 1-y/500). Siehe Fähigkeit threejs-rendering.
Python MuJoCo	Tiefe von derselben Kamera rendern und deprojizieren (er_point_to_world in mujoco-physics/scripts/panda_pick_place.py). Segmente auf Verdeckung prüfen.
Echt RGB-D	Z = mediane Tiefe, X = (u−cx)Z/fx, Y = (v−cy)Z/fy, dann T_base←cam.
Echt RGB, nur Tisch	Strahl mit der Ebene z = z_table schneiden, dann die halbe Objekthöhe addieren.

Eine Tiefenprobe oder ein Raycast trifft die Oberseite, daher nach unten zur Greifhöhe versetzen. Box-Aspect gibt die Greifer-Gier: Schließen Sie über die kurze Seite. Ein 0–1000 Integer-Gitter quantisiert auf ungefähr FOV/1000 pro Einheit (etwa 1 mm/Einheit für eine 1 m breite Ansicht).

7. Im Franka-Demo

Das Franka Pick-and-Place-Demo (React + Vite + mujoco-js + Three.js) ist die Referenz-App, aus der diese Fähigkeiten erstellt wurden. Dateinamen unten beziehen sich darauf.

• App.tsx::handleErSend nimmt ein ≤640 px PNG aus einer festen Draufsicht auf und ruft ER auf. Es verwendet SDK 1.x ai.models.generateContent mit thinkingBudget: 0. Punkte und Box-Zentren werden mit RenderSystem.project2DTo3D raycasted. SequenceAnimator führt dann einen blinden 15-Schritte-Pick für jedes Ziel aus. Es gibt keine Verifikation, Orchestrierung oder Live API.
• Der Schlüssel wird dem Browser über Vite define (process.env.API_KEY) zugänglich gemacht. Das ist in Ordnung für ein Demo, aber nicht für die Produktion.
• Siehe references/interactions-api.md#migrating-the-franka-demo für die genaue 1.x→2.x-Differenz und references/orchestration.md / references/video-progress.md zum Hinzufügen von Closed-Loop-Verhalten.

8. Sicherheit

ER kann halluzinieren oder Objekte teilweise falsch zuordnen. Behandeln Sie jede Ausgabe als Vorschlag:

• Prüfen Sie Arbeitsraumbegrenzungen, Erreichbarkeit (IK-Residuum), Kollisionen und Geschwindigkeitsgrenzen.
• Verlangen Sie menschliche Bestätigung für folgenreiche Aktionen und halten Sie einen physischen Not-Aus bereit.
• Entwickeln Sie in der Simulation hinter derselben Roboter-API, bevor Sie auf Hardware umsteigen.
• Kamera- und Mikrofondaten können Personen erfassen. Holen Sie Einwilligung ein, unkenntlich machen Sie Gesichter und minimieren Sie die Aufbewahrungsdauer. Siehe https://deepmind.google/models/gemini-robotics/safety.