Robotik için Live API

gemini-robotics-er-2-streaming-preview modeli uç noktası, Live API ile entegre olan özel bir akış uç noktası sunar. Bu sayede uygulamanız ile robot arasında gerçek zamanlı ve çift yönlü etkileşim sağlanır. Bu nedenle, hızlı geri bildirim döngülerine ve çevreye tepkisel yanıtlara ihtiyaç duyan temsilciler için uygundur.

Kullanım alanları

  • Çoklu robot koordinasyonu: Görev durumunu ileten ve alt görevleri paylaşılan bir oturum aracılığıyla devreden birden fazla robot.
  • Sürekli izleme: Bir sahneyi gözlemleyen ve belirli etkinlikler (ör. bir kabın doluluk seviyesine ulaşması) gerçekleştiğinde işlemleri tetikleyen robotlar.
  • Depo ve lojistik: Öğeleri görsel olarak doğrulayan, paketleme sürecini takip eden ve hataları düzelten toplama ve paketleme temsilcileri.

Teknik özellikler

Aşağıdaki tabloda, Live API'nin teknik özellikleri özetlenmiştir:

Kategori Ayrıntılar
Giriş biçimleri Ses (ham 16 bit PCM ses, 16 kHz, little-endian), resimler (JPEG <= 1 FPS), metin
Çıkış biçimleri Metin
Protokol Durumlu WebSocket bağlantısı (WSS)

Temsilci tabanlı bir kurulum oluşturma

Live API'de oluşturulan her robotik aracı üç adımı izler:

  1. Robot yeteneklerini araç olarak beyan edin. Robotun gerçekleştirebileceği her işlem (ör. gezinme, kavrama, konuşma), ad, açıklama ve parametre şeması içeren bir işlev bildirimi haline gelir. Fiziksel işlemler "behavior": "BLOCKING" kullanmalıdır. Böylece model, sonraki adımı seçmeden önce robotun işlemi tamamlamasını bekler.
  2. Çok formatlı girişi kalıcı bir oturuma aktarın. Bir live.connect oturum açın ve görevin süresi boyunca açık tutun. Robotunuzun sensörlerinden gelen video karelerini, sesleri veya metinleri gönderin.
  3. Araç çağrılarını bir alma döngüsünde işleyin. Model her işlem seçtiğinde tool_call mesajı gönderir. Alım döngünüz, robot SDK'nıza karşı işlevi yürütür ve tool_response geri gönderir. Oturum açık kalır ve model, sonuca göre sonraki işlemi seçer.

Aşağıdaki bölümlerde, bu adımların üç yaygın düzene nasıl uygulanacağı gösterilmektedir: temel aracı döngüsü, kalp atışı ile proaktif sahne izleme ve konuşmayı TTS üzerinden yönlendirme.

İşlev çağrısı aracılığıyla robot yönetme

Aşağıdaki örnekte, üç adımın tamamı tek bir Python komut dosyasıyla birbirine bağlanmış şekilde gösterilmektedir.

1. adım: Araç tanımları. Robot özelliklerini işlev bildirimleri olarak bildirir. navigate işlevi "behavior": "BLOCKING" kullandığından model, başka bir aracı çağırmadan önce robotun ara noktaya ulaşmasını bekler. Ek robot özelliklerini kullanıma sunmak için aynı listeye daha fazla işlev bildirimi ekleyin.

2. adım: Giriş yardımcıları. Oturuma farklı modalite girişleri aktaran üç işlevi gösterir: send_text komutlar için, send_image isteğe bağlı metin istemi içeren kamera çerçeveleri için ve send_audio mikrofondan alınan ham PCM ses için.

3. adım olan alma döngüsü eşzamanlı olarak çalışır ve iki tür mesajı işler: server_content mesajları (modelin metin çıkışı) ve tool_call mesajları (modelin robot işlemi isteği). Bir araç çağrısı geldiğinde döngü, execute_tool — gerçek robot SDK'nızla değiştirdiğiniz bir kaba kod — çağrısı yapar ve ardından tool_response gönderir. Böylece model, sonraki işlemi seçebilir.

import asyncio
from google import genai
from google.genai import types

MODEL = "gemini-robotics-er-2-streaming-preview"

# ── Tool definitions ─────────────────────────────────────────────────────────
tools = [
   {
       "function_declarations": [
           {
               "name": "navigate",
               "description": "Navigate the robot to a named waypoint.",
               "behavior": "BLOCKING",
               "parameters": {
                   "type": "OBJECT",
                   "properties": {"name": {"type": "STRING"}},
                   "required": ["name"],
               },
           },
           # Add more function definitions here
       ]
   }
]

# ── Stub tool executor (replace with real robot SDK calls) ───────────────────
def execute_tool(name: str, args: dict) -> dict:
   print(f"  [Tool] {name}({args})")
   return {"status": "success"}

# ── Input helpers ────────────────────────────────────────────────────────────
def send_text(session, text: str):
   """Send a text turn."""
   return session.send_client_content(
       turns=types.Content(role="user", parts=[types.Part(text=text)]),
       turn_complete=True,
   )

def send_image(session, image_bytes: bytes, prompt: str = ""):
   """Send a JPEG image with an optional text prompt."""
   parts = [
       types.Part(
           inline_data=types.Blob(data=image_bytes, mime_type="image/jpeg")
       )
   ]
   if prompt:
       parts.append(types.Part(text=prompt))
   return session.send_client_content(
       turns=types.Content(role="user", parts=parts),
       turn_complete=True,
   )

def send_audio(session, audio_chunk: bytes):
   """Stream a chunk of raw PCM audio (16-bit, 16 kHz, mono)."""
   return session.send_realtime_input(
       media=types.Blob(data=audio_chunk, mime_type="audio/pcm;rate=16000")
   )

# ── Receive loop ─────────────────────────────────────────────────────────────
async def receive_loop(session):
   """Print model text and handle tool calls until the session ends."""
   async for message in session.receive():
       if message.server_content:
           sc = message.server_content
           if sc.model_turn and sc.model_turn.parts:
               for part in sc.model_turn.parts:
                   if part.text:
                       print(f"Model: {part.text}", end="", flush=True)
           if sc.turn_complete:
               print("\n[Turn Complete]")
       elif message.tool_call:
           responses = []
           for call in message.tool_call.function_calls:
               print(f"\n[Tool Call] {call.name}({call.args})")
               result = execute_tool(call.name, call.args)
               responses.append(
                   types.FunctionResponse(
                       name=call.name,
                       response=result,
                       id=call.id,
                   )
               )
           await session.send_tool_response(function_responses=responses)

# ── Main ─────────────────────────────────────────────────────────────────────
async def main():
   client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
   config = types.LiveConnectConfig(
       response_modalities=["TEXT"],
       tools=tools,
       system_instruction=types.Content(
           parts=[types.Part(text="You are a robot controller. Use tools to execute commands.")]
       ),
   )
   async with client.aio.live.connect(model=MODEL, config=config) as session:
       recv_task = asyncio.create_task(receive_loop(session))
       # Connect robot perception callbacks and user inputs to the helpers above.
       recv_task.cancel()

asyncio.run(main())

Alım döngüsü, her araç yanıtından sonra etkin kalır. Model, tüm işlem sırasını önceden kodlamanıza gerek kalmadan uzun vadeli bir plan oluşturur ve revize eder.

Proaktif zamansal-mekansal akıl yürütme

Live API, video akışı yapar ancak video kareleri tek başına yeni bir muhakeme dönüşünü tetiklemez. Video karelerine, model yanıtını tetiklemek için metin veya ses istemi eşlik etmelidir. Arka plan bilgisi için Live API özellikleri başlıklı makaleyi inceleyin.

Proaktif akıl yürütmeyi etkinleştirmek için kalp atışı uygulayın: Modeli sahneyi incelemeye ve açık bir karar vermeye zorlayan kısa bir metin istemiyle birlikte en son kamera karesini düzenli olarak gönderin. Video girişi, saniyede bir kare ile sınırlıdır.

Bu eş yordamı önceki bölümdeki alma döngüsünün yanına ekleyin. Aynı oturumda ayrı bir asyncio görevi olarak çalışır:

async def heartbeat(session, camera):  # camera is your robot camera API
    while True:
        frame = await camera.latest_jpeg()
        await session.send_realtime_input(
            video=types.Blob(data=frame, mime_type="image/jpeg")
        )
        await session.send_realtime_input(
            text=(
                "[HEARTBEAT] If no task is active, call 'ack' and wait for user"
                " input. If a task is active: observe the scene. If the current"
                " step is progressing correctly, call 'ack'. If the current step"
                " is complete, call 'run_instruction' with the next step. If the"
                " overall goal is achieved, call 'reset' and inform the user."
            )
        )
        await asyncio.sleep(1)

Robot işlemleri sırasında kalp atışını duraklatmanız gerekmez. Örtülü başarı algılayıcı olarak kullanıldığında, modelin çalışmaya devam etmesi, devam eden işlemi sürekli olarak gözlemlemesini (ör. tutma işleminin güvenli olup olmadığını, dökme işleminin doğru yapılıp yapılmadığını veya bir nesnenin doğru şekilde yerleşip yerleşmediğini takip etmesini) ve sonuç netleştiği anda tepki vermesini sağlar.

Harici TTS aracılığıyla ses çıkışı

Gemini Robotics ER 2, metin döndürür. Uygulamanız, tamamlanan yanıtları yerleştirilen bir geri çağırma yoluyla ayrı bir TTS sağlayıcıya (ör. Gemini TTS) yönlendirir. Bu sayede konuşma gecikmesi, ses seçimi ve kesinti davranışını kontrol edebilir, temsilci mantığını değiştirmeden TTS arka uçlarını değiştirebilirsiniz.

Ayrıca, modeli "bir şey söyle" komutunu "kolu hareket ettir" komutuyla aynı şekilde değerlendirmesi için TTS'yi bir araç olarak da bildirebilirsiniz. İlk bölümdeki tools listenize aşağıdaki işlev bildirimini ekleyin:

TOOLS = [
    {
        "name": "send_message",
        "description": (
            "Speak a message aloud via TTS, then deliver it to the"
            " specified target. Use target='user' to speak directly"
            " to the user, or a peer agent name (e.g., 'duo') to"
            " communicate with another robot."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "target": {
                    "type": "string",
                    "description": "Recipient: 'user' or a peer agent name.",
                },
                "message": {
                    "type": "string",
                    "description": "The message to speak and deliver.",
                },
            },
            "required": ["target", "message"],
        },
    },
]

TTS'yi bir işlev beyanına sarmalayarak model, konuşmayı diğer tüm robot işlemleriyle aynı araç çağrısı yolu üzerinden işler. Uygulamanız, yerleştirilmiş bir geri arama ile aramayı tamamlıyor.

GitHub'daki örnekler

Spot robotun atıştırmalık alma demosu ve Tinybot'un pan-tilt merhaba dünya demosu da dahil olmak üzere tam çalışan örnekler için Robotics Live API örnekleri'ne bakın.

Sırada ne var?