Công cụ

LeRobot hỗ trợ gọi công cụ trong các chính sách — các thông điệp trợ lý có thể phát ra các lời gọi có cấu trúc như say(text="OK, starting now") để runtime chuyển tiếp đến một triển khai thực sự (TTS, bộ điều khiển, trình ghi log, …).

Trang này bao gồm:

1. Nơi lưu trữ danh mục công cụ.
2. Cách pipeline chú thích tạo ra các nguyên tử gọi công cụ.
3. Cách thêm công cụ của riêng bạn.

Nơi khai báo các công cụ

Hai lớp.

Danh mục — một danh sách các schema hàm theo phong cách OpenAI — nằm tại meta/info.json["tools"] trên mỗi dataset. Ví dụ:

{
  "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"]
        }
      }
    }
  ]
}

Đọc nó thông qua bộ truy cập metadata của 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

Nếu info.json của bộ dữ liệu không khai báo công cụ nào, meta.tools sẽ trả về DEFAULT_TOOLS từ lerobot.datasets.language — hiện tại là một danh sách một phần tử chứa schema say chuẩn. Do đó, các bộ dữ liệu không chú thích và người dùng chat-template vẫn hoạt động bình thường mà không cần cấu hình gì:

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

Các phần triển khai — Python có thể chạy — sẽ nằm dưới src/lerobot/tools/, mỗi công cụ một tệp. Bộ điều phối thời gian chạy và phần triển khai say chuẩn (bao bọc pocket-tts của Kyutai) không thuộc về lớp danh mục được mô tả ở đây; hiện tại lớp này chỉ cung cấp bộ lưu trữ schema và hằng số dự phòng DEFAULT_TOOLS.

Gọi công cụ theo từng hàng

Danh mục ở trên mô tả điều gì có thể được gọi. Lời gọi thực tế — tên hàm cùng các giá trị tham số — được lưu trữ theo từng hàng, trên các nguyên tử trợ lý trong 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 chèn những điều này vào các tin nhắn đã render thông qua 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,
      }

Mục tiêu huấn luyện của mô hình là một lượt phản hồi của trợ lý chứa cả văn bản kế hoạch và lệnh gọi công cụ say. Khi suy luận, runtime sẽ phân tích văn bản được tạo ra thành các tool_calls có cấu trúc và chuyển đến phần triển khai tương ứng.

Cách thêm công cụ của riêng bạn

Lưu ý: Các bước 2 và 3 bên dưới mô tả lớp runtime (src/lerobot/tools/, giao thức Tool, TOOL_REGISTRY, get_tools(meta)) — đây là phần không thuộc về lớp catalog được phát hành hiện tại — các module đó chưa tồn tại trong cây thư mục. Chỉ riêng bước 1 đã đủ để công cụ hiển thị với chat template thông qua meta.tools để mô hình có thể học cách sinh lời gọi; việc thực thi lời gọi ở giai đoạn suy luận đòi hỏi lớp runtime.

Ba bước. Ví dụ cụ thể: công cụ record_observation mà chính sách có thể gọi để ghi nhận một quan sát bổ sung bên ngoài vòng lặp điều khiển thông thường.

Bước 1 — khai báo schema

Thêm một mục vào meta/info.json["tools"] bằng cách chỉnh sửa tệp trực tiếp trên đĩa trước khi chạy pipeline chú thích (nó sẽ được giữ nguyên).

{
  "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"]
        }
      }
    }
  ]
}

Sơ đồ tuân thủ chính xác quy ước gọi hàm của OpenAI, do đó mẫu chat có thể hiển thị nó một cách tự nhiên.

Bước 2 — triển khai cuộc gọi

Tạo 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"

Việc tách mỗi công cụ thành một tệp riêng giúp cách ly các phụ thuộc — record_observation có thể kéo theo pillow, trong khi say kéo theo pocket-tts. Người dùng chỉ cài đặt các công cụ cần thiết sẽ tránh được các phụ thuộc chuyển tiếp nặng nề.

Bước 3 — đăng ký

Thêm vào src/lerobot/tools/registry.py:

from .record_observation import RecordObservationTool

TOOL_REGISTRY["record_observation"] = RecordObservationTool

Đó là tất cả. Khi chạy, get_tools(meta) sẽ tra cứu từng schema trong meta.tools, khởi tạo lớp đã đăng ký tương ứng và trả về một dict tên → instance để dispatcher có thể định tuyến vào.

Nếu bạn muốn sử dụng một công cụ mà không cần viết phần triển khai (ví dụ chỉ để định dạng chat-template trong quá trình huấn luyện), chỉ cần thực hiện bước 1 là đủ — mô hình vẫn học được cách sinh ra lời gọi. Các bước 2 và 3 chỉ cần thiết để thực sự thực thi lời gọi đó ở giai đoạn suy luận.