Communitygithub.com

johannstark/GeminiRobotics-Skills

Gemini Robotics-ER 2 모델을 사용하여 로봇의 지각(perception), 계획(planning), 검증(verification)을 구축합니다. Google Gen AI SDK 2.x의 Interactions API 및 Live API를 통해 gemini-robotics-er-2-preview 및 gemini-robotics-er-2-streaming-preview 모델을 호출합니다.

GeminiRobotics-Skills란 무엇인가요?

이 스킬은 로봇의 임베디드 추론(Embodied Reasoning)을 위한 비전-언어 모델인 Gemini Robotics-ER 2를 활용하는 방법을 상세히 설명합니다. ER 2는 이미지, 비디오, 오디오를 입력받아 텍스트(JSON 포인트, 바운딩 박스, 궤적, 계획, 로봇 함수 호출)를 출력하며, 모터를 직접 구동하지 않고 'ER이 제안하고, 결정론적 코드가 실행'하는 패러다임을 따릅니다. 이 스킬은 Interactions API(비실시간, 공간 추론, 코드 실행, 함수 호출 오케스트레이션, 비디오 이해)와 Live API(실시간, 연속 비디오/오디오, 차단형 도구 호출) 두 가지 엔드포인트를 지원하며, 각각의 용도와 제약 사항을 명확히 제시합니다. 또한 좌표계 규칙([y,x] 정규화 0-1000), 방어적 파싱, 프롬프트 최적화 전략, 2D-3D 리프팅 방법, 안전 수칙 등 실전에서 발생할 수 있는 주요 버그와 함정을 방지하는 10가지 핵심 규칙을 제공합니다. Franka 픽 앤 플레이스 데모를 참조 애플리케이션으로 삼아 구체적인 구현 예시와 SDK 1.x에서 2.x로의 마이그레이션 가이드도 포함되어 있어, 기존 코드를 업데이트하거나 새로운 로봇 지각/제어 시스템을 개발하는 AI 에이전트 개발자에게 매우 실용적인 참고 자료가 됩니다.

지원 대상~Claude Code~Codex CLI~Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/johannstark/GeminiRobotics-Skills/tree/HEAD/gemini-robotics-er
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

Gemini Robotics-ER 2

Gemini Robotics-ER(임베디드 추론)은 로봇을 위한 비전-언어 모델입니다. 이미지, 비디오, 오디오를 입력받습니다. JSON 포인트, 박스, 계획, 또는 로봇 함수 호출을 텍스트로 반환합니다. 모터를 직접 구동하지 않습니다. ER이 제안하고, 결정론적 코드가 실행됩니다.

여기의 모든 내용은 공식 문서(ai.google.dev, 2026년 10월), ER 2 노트북(gemini_robotics_er.ipynb), google-genai 2.31 / @google/genai 2.30을 기준으로 확인되었습니다.

1. 엔드포인트와 API 선택

모델API용도지원되지 않음
gemini-robotics-er-2-previewInteractions API client.interactions.create (레거시 generateContent도 가능)포인팅, 박스, 궤적, 공간 논리, 코드 실행, 함수 호출 오케스트레이션, 비디오 모멘트 찾기 및 진행률Live API
gemini-robotics-er-2-streaming-previewLive API client.aio.live.connect / ai.live.connect (WebSocket)실시간 에이전트: ≤1 FPS의 연속 비디오, 오디오, BLOCKING 도구 호출구조화된 출력, 코드 실행, 캐싱, Interactions
gemini-robotics-er-1.6-preview—2026년 8월 31일 지원 종료 예정. 모델 문자열만 바꾸면 됩니다. 비디오 진행률과 스트리밍은 ER 2가 필요합니다.

두 ER 2 엔드포인트 모두 텍스트, 이미지, 비디오, 오디오를 입력받고 텍스트만 출력합니다. 한도: 131,072 입력 토큰, 65,536 출력 토큰. 기본 thinking은 high입니다. 수준은 minimal, low, medium, high입니다. 문서에서는 지연 시간과 품질 사이의 균형을 위해 medium을 권장합니다.

2. 패턴 선택

스크립트 모션을 위한 원샷 타겟이 필요하신가요?         -> 공간 질의 (포인트/박스)    references/spatial-reasoning.md
작은 텍스트, 게이지, 개수 세기, 자르기/확대, 주석?     -> 에이전트 비전 (code_execution)   references/agentic-vision.md
로봇 API를 통한 다단계 작업, 단계별로?                -> 오케스트레이션 (함수 호출)  references/orchestration.md
작동했나요? 언제? 얼마나 진행되었나요?               -> 비디오 이해               references/video-progress.md
카메라/음성에 지속적으로 반응, <1초 루프?           -> Live API + 스트리밍 모델        references/live-api.md
요청/응답 형태, SDK 세부 정보, 마이그레이션?         -> Interactions API 참조        references/interactions-api.md

scripts/er_tools.py는 테스트된 헬퍼 함수(이미지 인코딩, 응답 형식, 방어적 파서, 오케스트레이션 루프, 비디오 업로드 및 타임스탬프 파싱)를 제공합니다. --selftest(키 불필요) 또는 --help와 함께 실행하세요.

3. 최소한의 올바른 호출

Python (pip install "google-genai>=2.9.0"; 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": [                       # 또는 플랫 파트 리스트
        {"type": "image", "data": png_b64, "mime_type": "image/png"},  # 텍스트 앞에 미디어
        {"type": "text", "text": "빨간 큐브를 가리켜 주세요. 포인트는 0-1000으로 정규화된 [y, x]입니다."},
    ]}],
    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; 요청 필드는 snake_case; 서버 측에서 실행):

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

interaction.output_text(최종 텍스트), interaction.steps(타임라인: thought, function_call, code_execution_call, code_execution_result, model_output), interaction.id(previous_interaction_id로 전달)를 사용하여 응답을 읽습니다.

4. 대부분의 버그를 방지하는 규칙

  1. 좌표는 [y, x], 0-1000으로 정규화되며, 보낸 이미지를 기준으로 합니다. 박스는 [ymin, xmin, ymax, xmax]입니다. u = x/1000*W, v = y/1000*H로 변환합니다. 모든 프롬프트에 형식을 명시하세요.
  2. Interactions 형태를 사용하세요. input=[{"type": "image" | "text" | "video", ...}], generation_config={...}, response_format={...}를 사용합니다. config=types.GenerateContentConfig(...), PIL 이미지, 또는 Interaction에서 .text / .function_calls를 읽지 마세요. 그것들은 generateContent에 속합니다.
  3. tools, system_instruction, generation_config는 턴마다 설정해야 합니다. previous_interaction_id를 사용하는 턴을 포함하여 매 interactions.create 호출 시 다시 전송하세요.
  4. ER 2 / Gemini 3+에서는 thinking_budget을 사용하지 마세요. 400 오류가 발생할 수 있습니다. thinking_level을 사용하세요.
  5. 스키마가 있어도 방어적으로 파싱하세요. 펜스를 제거하고, 외부 JSON까지 슬라이스하고, 중복 및 범위를 벗어난 좌표를 제거하고, 개수를 제한하세요(er_tools.parse_er_json).
  6. 캡처 카메라는 역투영 카메라와 동일해야 합니다. 동일한 포즈, 내부 파라미터, 자르기, 종횡비를 사용하세요. 캡처 시 로봇이 대상을 가리지 않도록 하세요.
  7. 로봇 함수는 실제 결과를 반환합니다. 실패 시 is_error: true와 사유를 전송하여 모델이 재계획하도록 하세요. 도구 루프를 max_steps로 제한하세요. 이동 전에 모든 대상을 작업 공간 및 관절 한계에 대해 검증하세요.
  8. Live API: "behavior": "BLOCKING" 도구만 사용하고, 초당 최대 1개의 비디오 프레임을 전송하며, 다음 하트비트 전에 turn_complete를 기다리고(그렇지 않으면 바지인(barge-in)이 작업을 취소함), tool_call_cancellation을 처리하세요.
  9. 키: 제한 없는 API 키는 403을 반환하므로 AI Studio에서 제한을 추가하세요. 키를 브라우저로 전송하지 마세요. Interactions에는 백엔드 프록시를, Live에는 임시 토큰(Live에서만 작동)을 사용하세요.
  10. 스토리지: interactions는 기본적으로 저장됩니다(store=true: 유료 55일, 무료 1일). store=false는 previous_interaction_id를 비활성화합니다. Interactions는 Gemini Developer API 기능이며 gs:// URI는 읽을 수 없으므로 Files API를 사용하세요.

5. 효과적인 프롬프팅 (문서 및 노트북 발췌)

  • 일반 언어를 사용하세요. 용어가 실패하면 동의어를 시도하세요("와셔" 또는 "링").
  • "설명과 부분적으로만 일치하는 항목은 감지하지 마십시오"라고 말하면 거짓 양성을 줄일 수 있습니다.
  • 개수를 제한하세요("25개 이하 항목"). 특정 부품이 필요할 때는 쿼리당 하나의 포인트를 요청하세요.
  • 복잡한 작업은 별도의 프롬프트로 나누고, 독립적인 쿼리는 병렬로 실행하세요(노트북은 ThreadPoolExecutor를 사용).
  • 정밀도를 위해 여러 번 질의하고 중앙값 포인트를 취하세요.
  • 이미지를 약 800px 너비로 조정하면(노트북에서 이렇게 함) 토큰을 절약할 수 있습니다. 작은 물체의 경우 자르거나 확대하세요.
  • Thinking: 단순 감지나 포인팅에는 low를, 개수 계산, 페이로드나 어포던스 추론, 성공 감지, 비디오에는 high를 사용하세요. medium이 기본 절충안입니다.
  • 여러 이미지나 비디오 그리드의 경우 프롬프트에 레이아웃을 설명하세요("처음 4개 이미지 = 시작, 마지막 4개 = 현재"; "보기 왼쪽에서 오른쪽: 상단, 손목").

6. 2D를 3D로 리프팅 (요약)

설정방법
브라우저 시뮬레이션 (Three.js)캡처 카메라에서 NDC (x/500-1, 1-y/500)를 통한 레이캐스트. threejs-rendering 스킬을 참조하세요.
Python MuJoCo동일한 카메라에서 깊이를 렌더링하고 역투영(mujoco-physics/scripts/panda_pick_place.py의 er_point_to_world). 가림(occlusion)을 위해 세그멘테이션을 확인하세요.
실제 RGB-DZ = 중앙값 깊이, X = (u−cx)Z/fx, Y = (v−cy)Z/fy, 그 다음 T_base←cam.
실제 RGB, 테이블만광선을 평면 z = z_table과 교차시킨 후 물체 높이의 절반을 더합니다.

깊이 샘플 또는 레이캐스트는 상단 표면에 닿으므로 그립 높이까지 아래로 오프셋합니다. 박스 종횡비가 그리퍼 요를 결정합니다. 짧은 쪽을 가로질러 닫습니다. 0-1000 정수 그리드는 단위당 대략 FOV/1000으로 양자화됩니다(1m 너비 뷰의 경우 약 1mm/단위).

7. Franka 데모에서

Franka 픽 앤 플레이스 데모(React + Vite + mujoco-js + Three.js)는 이러한 스킬이 구축된 참조 앱입니다. 아래 파일 이름은 이 앱을 참조합니다.

  • App.tsx::handleErSend는 고정된 탑 뷰에서 ≤640px PNG를 캡처하고 ER을 호출합니다. thinkingBudget: 0과 함께 SDK 1.x ai.models.generateContent 를 사용합니다. 포인트와 박스 중심은 RenderSystem.project2DTo3D로 레이캐스트됩니다. 그런 다음 SequenceAnimator는 모든 대상에 대해 블라인드 15단계 픽을 실행합니다. 검증, 오케스트레이션 또는 Live API는 없습니다.
  • 키는 Vite define(process.env.API_KEY)을 통해 브라우저에 노출됩니다. 데모에는 괜찮지만 프로덕션 용도로는 적합하지 않습니다.
  • 정확한 1.x→2.x 차이점은 references/interactions-api.md#migrating-the-franka-demo를, 폐쇄 루프 동작 추가는 references/orchestration.md / references/video-progress.md를 참조하세요.

8. 안전

ER은 환각(hallucination)을 일으키거나 물체를 부분적으로 일치시킬 수 있습니다. 모든 출력을 제안으로 취급하세요:

  • 작업 공간 경계, 도달 가능성(IK 잔차), 충돌 및 속도 한계를 확인하세요.
  • 중요한 작업에는 사람의 확인을 요구하고, 물리적 비상 정지 장치를 유지하세요.
  • 하드웨어로 교체하기 전에 동일한 로봇 API 뒤의 시뮬레이션에서 개발하세요.
  • 카메라 및 마이크 데이터는 사람을 캡처할 수 있습니다. 동의를 얻고, 얼굴을 흐리게 처리하며, 보존 기간을 최소화하세요. https://deepmind.google/models/gemini-robotics/safety를 참조하세요.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

johannstark/GeminiRobotics-Skills

Renders MuJoCo simulations with Three.js (in-browser WASM, a streamed Python MuJoCo process, or logs). Use for Z-up scene setup, converting MuJoCo geoms and meshes to Three.js meshes, per-frame body pose sync (wxyz quaternions), capturing camera snapshots and canvas video for Gemini Robotics-ER, mapping ER [y, x] 0-1000 points to 3D by raycasting, projecting 3D back to image coordinates, and debugging sideways, twisted, mis-sized or blank renders.

관련 스킬

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community