Alat

LeRobot mendukung tool calls dalam kebijakan — pesan asisten dapat mengeluarkan pemanggilan terstruktur seperti say(text="OK, starting now") yang kemudian di-dispatch oleh runtime ke implementasi nyata (TTS, controller, logger, …).

Halaman ini membahas:

1. Lokasi katalog alat.
2. Bagaimana pipeline anotasi menghasilkan atom pemanggilan alat.
3. Cara menambahkan alat Anda sendiri.

Di mana alat dideklarasikan

Dua lapisan.

Katalog — daftar skema fungsi bergaya OpenAI — berada di meta/info.json["tools"] pada setiap dataset. Contoh:

{
  "features": { "...": "..." },
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "say",
        "description": "Speak a short utterance to the user via the TTS executor.",
        "parameters": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "description": "The verbatim text to speak."
            }
          },
          "required": ["text"]
        }
      }
    }
  ]
}

Baca melalui akses metadata dataset:

from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata

meta = LeRobotDatasetMetadata(repo_id="pepijn/super_poulain_final_annotations")
tools = meta.tools     # list[dict] — OpenAI tool schemas

Jika info.json dari dataset tidak mendeklarasikan alat apa pun, meta.tools mengembalikan DEFAULT_TOOLS dari lerobot.datasets.language — saat ini berupa daftar satu entri dengan skema say yang kanonik. Dengan demikian, dataset yang tidak dianotasi dan konsumen chat-template tetap berfungsi tanpa konfigurasi apa pun:

prompt_str = tokenizer.apply_chat_template(
    sample["messages"],
    tools=meta.tools,                 # works either way
    add_generation_prompt=False,
    tokenize=False,
)

Implementasi — Python yang dapat dijalankan — akan berada di bawah src/lerobot/tools/, satu file per alat. Dispatcher runtime dan implementasi say kanonikal (yang membungkus pocket-tts dari Kyutai) bukan bagian dari lapisan katalog yang dijelaskan di sini; saat ini lapisan ini hanya menyediakan penyimpanan skema dan konstanta fallback DEFAULT_TOOLS.

Pemanggilan alat per baris

Katalog di atas menjelaskan apa yang dapat dipanggil. Panggilan aktual — nama fungsi beserta nilai argumen — disimpan per baris, pada atom asisten di language_events:

{
  "role": "assistant",
  "content": null,
  "style": null,
  "timestamp": 12.4,
  "camera": null,
  "tool_calls": [
    { "type": "function",
      "function": { "name": "say", "arguments": { "text": "On it." } } }
  ]
}

Recipes menyisipkan ini ke dalam pesan yang dirender melalui tool_calls_from:

user_interjection_response:
  bindings:
    speech: "emitted_at(t, role=assistant, tool_name=say)"
  messages:
    - { role: user, content: "${task}", stream: high_level }
    - {
        role: assistant,
        content: "${current_plan}",
        stream: high_level,
        target: true,
        tool_calls_from: speech,
      }

Target pelatihan model adalah satu giliran asisten yang membawa teks rencana dan pemanggilan alat say. Saat inferensi, runtime mengurai teks yang dihasilkan kembali menjadi tool_calls terstruktur dan meneruskannya ke implementasi yang sesuai.

Cara menambahkan alat Anda sendiri

Catatan: Langkah 2 dan 3 di bawah ini menjelaskan lapisan runtime (src/lerobot/tools/, protokol Tool, TOOL_REGISTRY, get_tools(meta)) yang belum menjadi bagian dari lapisan katalog yang disediakan saat ini — modul-modul tersebut belum ada di dalam tree. Langkah 1 saja sudah cukup untuk membuat tool terlihat oleh chat template melalui meta.tools sehingga model dapat belajar untuk menghasilkan panggilan; mengeksekusi panggilan pada saat inferensi memerlukan lapisan runtime.

Tiga langkah. Contoh konkret: sebuah alat record_observation yang dapat dipanggil oleh kebijakan untuk menangkap observasi tambahan di luar loop kontrol reguler.

Langkah 1 — deklarasikan skema

Tambahkan entri di bawah meta/info.json["tools"] dengan mengedit file langsung di disk sebelum menjalankan pipeline anotasi (akan dipertahankan).

{
  "tools": [
    { "type": "function", "function": { "name": "say", "...": "..." } },
    {
      "type": "function",
      "function": {
        "name": "record_observation",
        "description": "Capture a high-resolution still image for the user.",
        "parameters": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "Short label for the saved image."
            }
          },
          "required": ["label"]
        }
      }
    }
  ]
}

Skema ini mengikuti konvensi pemanggilan fungsi OpenAI secara persis, sehingga template chat dapat merendernya secara native.

Langkah 2 — implementasikan panggilan

Buat src/lerobot/tools/record_observation.py:

from .base import Tool
from typing import Any

RECORD_OBSERVATION_SCHEMA: dict[str, Any] = { "...": "..." }   # mirrors the JSON above


class RecordObservationTool:
    name = "record_observation"
    schema = RECORD_OBSERVATION_SCHEMA

    def __init__(self, schema: dict | None = None, output_dir: str = "."):
        self.output_dir = output_dir

    def call(self, arguments: dict) -> str:
        label = arguments["label"]
        # ... save the latest camera frame to <output_dir>/<label>.png ...
        return f"saved {label}.png"

Satu file per alat menjaga ketergantungan tetap terisolasi — record_observation mungkin menarik pillow, sementara say menarik pocket-tts. Pengguna yang hanya menginstal alat yang mereka butuhkan dapat menghindari ketergantungan transitif yang berat.

Langkah 3 — daftarkan

Tambahkan ke src/lerobot/tools/registry.py:

from .record_observation import RecordObservationTool

TOOL_REGISTRY["record_observation"] = RecordObservationTool

Itu saja. Saat runtime, get_tools(meta) mencari setiap skema di meta.tools, menginstansiasi kelas terdaftar yang cocok, dan mengembalikan dict nama → instance yang dapat dirutekan oleh dispatcher.

Jika Anda ingin menggunakan alat tanpa menulis implementasi (misalnya hanya untuk format template chat saat pelatihan), langkah 1 saja sudah cukup — model tetap belajar untuk menghasilkan panggilan tersebut. Langkah 2 dan 3 hanya diperlukan untuk benar-benar mengeksekusi panggilan tersebut saat inferensi.