LeRobot documentation
Chính sách
Chính sách
Mọi policy đều kế thừa PreTrainedPolicy, kết hợp torch.nn.Module với Hub mixin, nên bất kỳ policy nào cũng có thể được đẩy lên và tải từ Hugging Face Hub bằng cùng hai lệnh gọi.
Mỗi policy có hướng dẫn riêng kèm công thức huấn luyện và kết quả — ACT, SmolVLA, π₀, π₀.₅ và các policy khác được liệt kê dưới Policies. Để thêm một policy, xem Adding a Policy.
PreTrainedPolicy
Lớp cơ sở cho các mô hình chính sách.
Khai báo hợp đồng mặc định của tác giả cho việc phục vụ chunk quan sát hiện tại.
Việc kế thừa cài đặt này tuyên bố rằng predict_action_chunk thực hiện mọi công việc chuẩn bị cần thiết cho các bên gọi trực tiếp, nhận quan sát hiện tại đầy đủ và trả về [B, chunk_size, A] trong hệ tọa độ của mô hình. Cặp bộ xử lý chính thức của nó phải hỗ trợ các chunk hoàn chỉnh. n_action_steps là lát cắt phát lại thông thường; RTC giữ nguyên chân trời dự đoán đầy đủ.
Một policy yêu cầu chuẩn bị chỉ với select_action, các bố cục hành động khác, hoặc lấy mẫu theo thời gian phải ghi đè phương thức này và từ chối các cấu hình không được hỗ trợ hoặc cung cấp một runner tùy chỉnh. Sự hiện diện của phương thức hoặc một lần warmup thành công không phải là bằng chứng cho hợp đồng này. Trạng thái của policy/processor chỉ được phép trong một phiên độc quyền và reset() phải xóa nó cho một lần chạy mới.
Số lượng hành động đã được tính toán và đang chờ được phục vụ.
0 đối với chính sách không giữ hàng đợi hành động (không bao giờ chia nhỏ) hoặc hàng đợi hiện đang trống (sắp tính toán một khối mới). Đọc cùng các hàng đợi mà drop_queued_actions xóa, được đặt tên trong :attr:_action_queue_attrs.
Bỏ qua các hành động đã được tính toán trước bởi các lệnh gọi select_action trước đó.
Buộc thực hiện một lần truyền tiến mới ở lần gọi select_action tiếp theo để thay đổi điều kiện giữa tập (ví dụ: một chỉ thị mới) có hiệu lực ngay lập tức thay vì sau khi hàng đợi được xả hết. Khác với reset, phần còn lại của trạng thái tập được giữ nguyên. Gọi hàm này từ luồng gọi select_action. Xóa các hàng đợi được liệt kê trong :attr:_action_queue_attrs; một chính sách không giữ hàng đợi hành động sẽ kế thừa một thao tác không làm gì (no-op).
forward
< source >( batch: dict[str, Tensor] ) → tuple[Tensor, dict | None]
tóm tắt
from_pretrained
< source >( pretrained_name_or_path: str | Pathconfig: PreTrainedConfig | None = Noneforce_download: bool = Falseresume_download: bool | None = Noneproxies: dict | None = Nonetoken: str | bool | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falserevision: str | None = Nonestrict: bool = False**kwargs )
Chính sách mặc định được đặt ở chế độ đánh giá bằng policy.eval() (các module dropout bị vô hiệu hóa). Để huấn luyện, bạn cần đặt lại nó về chế độ huấn luyện bằng policy.train().
Chạy đầu văn bản của chính sách trên một lô quan sát đã được tiền xử lý.
Yêu cầu được truyền theo batch dưới dạng dữ liệu bổ sung (:data:~lerobot.utils.constants.QUERY_KIND / QUERY_TEXT); phản hồi next_subtask được đưa trực tiếp vào set_task, do đó nó phải là
đúng một subtask, không phải một kế hoạch hay danh sách đánh số. Trả về văn bản đã tạo và không được
thay đổi trạng thái tạo hành động (hàng đợi, lịch sử quan sát).
Trả về các tham số cụ thể của chính sách (parameters hoặc param groups) để truyền cho optimizer.
Trả về chunk hành động (đối với các chính sách chunk hành động) cho một quan sát nhất định, có thể ở chế độ batch.
Các lớp con sử dụng action chunking nên gọi phương thức này bên trong select_action để tạo thành action chunk được lưu đệm để chọn.
Một policy hỗ trợ từ khóa noise sẽ bắt đầu quá trình lấy mẫu từ tensor đó, với hình dạng giống như cách policy sẽ tạo ra nó. Khi noise là None, policy sẽ tạo ra nó như bình thường.
Có thể trả về một PolicyOutput chứa chunk và dự đoán của nó, giống như select_action.
push_model_to_hub
< source >( cfg: TrainPipelineConfigpeft_model = Nonestate_dict: dict[str, Tensor] | None = Nonedataset_meta: LeRobotDatasetMetadata | None = None )
Tham số
- cfg (TrainPipelineConfig) — Cấu hình huấn luyện; được lưu dưới dạng train_config.json và được sử dụng để hiển thị thẻ mô hình.
- peft_model — Lớp bọc PEFT khi huấn luyện adapter, trọng số của nó thay thế cho trọng số của toàn bộ mô hình trong kho đã công bố. Mặc định là None.
- state_dict (dict[str, Tensor] | None) — Bỏ qua; trọng số hiện được thu thập bên trong khi chính sách được chia mảnh. Mặc định là None.
- dataset_meta (LeRobotDatasetMetadata | None) — Metadata của dataset cho model card, nếu có. Mặc định là None.
Công bố chính sách này lên Hub.
Đã ngừng hỗ trợ: hãy dùng lerobot.common.train_utils.publish_trained_model() thay thế, hàm này cũng xuất bản cả bộ tiền xử lý/sau xử lý cùng với mô hình.
Được gọi mỗi khi môi trường được đặt lại.
Thực hiện các thao tác như xóa bộ nhớ đệm.
Trả về một hành động để thực thi trong môi trường (có thể ở chế độ hàng loạt).
Khi mô hình sử dụng lịch sử quan sát, hoặc xuất ra một chuỗi hành động, phương pháp này xử lý việc đệm (caching).
Trả về một tensor hành động thô, hoặc một PolicyOutput: một batch, được đánh khóa giống như batch đầu vào, chứa hành động dưới "action" và những gì chính sách kỳ vọng hoặc tin tưởng ngoài hành động đó dưới "prediction" (một PolicyPrediction). Phần dự đoán được batch hóa giống như hành động, một giá trị cho mỗi môi trường, và mỗi mục được đánh khóa theo thứ mà nó tham chiếu: các khung hình dự đoán theo khóa quan sát mà chúng dự đoán, ngôn ngữ theo phong cách chú thích (“subtask”, “plan”, “memory”), các hộp (sơ đồ VQA chú thích) theo camera mà chúng được vẽ trên đó. Người gọi chuẩn hóa hai kiểu trả về bằng lerobot.processor.policy_output_to_transition; —display_data hiển thị phần dự đoán của môi trường đầu tiên.
Một dự đoán giữ các giá trị cho bước hiện tại: một giá trị trải dài trên một khối (ví dụ một đoạn clip được tưởng tượng) sẽ được trả về từng phần, kèm theo hành động mà mỗi phần đó thuộc về. Mỗi mục sẽ được hiển thị cho đến khi nó được trả về lần nữa. Việc dự đoán là tùy chọn thông qua một trường cấu hình do chính sách lựa chọn, và không được phép thay đổi các hành động; văn bản cần điều hướng chính sách sẽ được xử lý qua generate_text.
Liệu chính sách này có triển khai ngữ nghĩa suy luận Real-Time Chunking hay không.
Liệu chính sách này có triển khai generate_text không (ghi đè cả hai cùng lúc).
Xác thực các đầu vào chính tắc trước khi phục vụ, với hình dạng chính xác theo mặc định.
Các chính sách (policies) có thể ghi đè hợp đồng này nếu chúng thực hiện việc thay đổi kích thước hoặc che mờ (mask) các đầu vào bị thiếu một cách tường minh. Những ngoại lệ như vậy phải thuộc về chính sách, không bao giờ thuộc về lớp truyền tải (transport). Schema dây (wire schema) đã đàm phán vẫn cố định hình dạng của mọi đặc trưng (feature) được cung cấp.
wrap_with_peft
< source >( peft_config = Nonepeft_cli_overrides: dict | None = None )
Tham số
- peft_config — Cấu hình adapter PEFT tùy chọn (ví dụ: LoraConfig). Nếu được cung cấp, sẽ được sử dụng trực tiếp (với các ghi đè từ CLI được áp dụng).
- peft_cli_overrides — dict tùy chọn chứa các ghi đè CLI (method_type, target_modules, r, v.v.) Chúng được gộp với các giá trị mặc định của policy để xây dựng cấu hình cuối cùng.
Bọc chính sách này bằng các bộ thích ứng PEFT để tinh chỉnh hiệu quả tham số.
Phương thức này là điểm vào duy nhất cho tích hợp PEFT. Các lớp con nên ghi đè _get_default_peft_targets() để cung cấp các module đích mặc định, và _validate_peft_config() cho việc xác thực cụ thể theo chính sách.
PreTrainedConfig
lớp lerobot.configs.PreTrainedConfig
< source >( n_obs_steps: int = 1input_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>output_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>device: str | None = Nonedtype: torch.dtype | None = Noneuse_amp: bool = Falseuse_peft: bool = Falsepush_to_hub: bool = Truerepo_id: str | None = Noneprivate: bool | None = Nonetags: list[str] | None = Nonelicense: str | None = Nonepretrained_path: pathlib.Path | None = Nonepretrained_revision: str | None = None )
Tham số
- n_obs_steps — Số bước môi trường của các quan sát cần truyền cho chính sách (bao gồm bước hiện tại và các bước bổ sung trước đó).
- input_features — Một từ điển định nghĩa PolicyFeature của dữ liệu đầu vào cho policy. Khóa đại diện cho tên dữ liệu đầu vào, và giá trị là PolicyFeature, bao gồm các thuộc tính FeatureType và shape.
- output_features — Một từ điển định nghĩa PolicyFeature của dữ liệu đầu ra cho chính sách. Khóa đại diện cho tên dữ liệu đầu ra, và giá trị là PolicyFeature, bao gồm các thuộc tính FeatureType và shape.
- normalization_mapping — Một từ điển ánh xạ từ một giá trị str của FeatureType (ví dụ: “STATE”, “VISUAL”) sang NormalizationMode tương ứng (ví dụ: NormalizationMode.MIN_MAX)
Lớp cấu hình cơ bản cho các mô hình chính sách.
make_policy
lerobot.policies.make_policy
< source >( cfg: PreTrainedConfigds_meta: LeRobotDatasetMetadata | None = Noneenv_cfg: EnvConfig | None = Nonerename_map: dict[str, str] | None = Nonedefer_weight_load: bool = Falsepretrained_path: str | Path | None = None ) → PreTrainedPolicy
Tham số
- cfg (PreTrainedConfig) — Cấu hình cho chính sách sẽ được tạo. Nếu
cfg.pretrained_pathđược đặt, chính sách sẽ được tải với trọng số từ đường dẫn đó. - ds_meta (LeRobotDatasetMetadata | None) — Metadata của dataset được dùng để suy ra hình dạng và kiểu của các đặc trưng. Đồng thời cung cấp thống kê cho các lớp chuẩn hóa.
- env_cfg (EnvConfig | None) — Cấu hình môi trường được dùng để suy ra hình dạng và kiểu của các đặc trưng. Phải cung cấp một trong
ds_metahoặcenv_cfg. - rename_map (dict[str, str] | None) — Bản ánh xạ tùy chọn từ các khóa đặc trưng của bộ dữ liệu hoặc môi trường sang tên đặc trưng chính sách mong đợi (ví dụ:
"left"→"camera1"). - defer_weight_load (bool) — Xây dựng chính sách y hệt như
from_pretrainedsẽ xây dựng — cùng cách phân giải cấu hình, cùng các bộ đệm suy ra từ thống kê, cùng vị trí thiết bị và chế độ eval — nhưng bỏ qua bước nạp trọng lượng safetensors. Được sử dụng khi khôi phục từ checkpoint DCP, trong đó các trọng lượng phân mảnh sẽ được truyền vào sauaccelerator.prepare()(động cơ checkpoint phân tán sẽ ghi đè lên khởi tạo ngẫu nhiên). Đối với chính sách PEFT, chỉ các trọng lượng adapter bị bỏ qua, còn các trọng lượng cơ sở vẫn được nạp như bình thường. - pretrained_path (str | Path | None) — Nạp trọng số (hoặc bộ thích ứng PEFT) từ đây thay vì từ
cfg.pretrained_path, vốn vẫn giữ tên của mô hình mà chính sách đã được tinh chỉnh từ đó sau khi chính sách được xây dựng. Được sử dụng khi tiếp tục từ một điểm kiểm tra.
Trả về
PreTrainedPolicy
Mô hình chính sách đã được khởi tạo và đặt trên thiết bị.
Gây ra
ValueError hoặc NotImplementedError
ValueError— Nếu cả hai hoặc không códs_metavàenv_cfgnào được cung cấp.NotImplementedError— Nếu cố gắng sử dụng một tổ hợp policy-backend không được hỗ trợ (ví dụ: VQBeT với ‘mps’).
Tạo một mô hình chính sách.
Hàm factory này xử lý logic tạo một policy, đòi hỏi phải xác định hình dạng của các đặc trưng đầu vào và đầu ra. Các hình dạng này có thể được suy ra từ một đối tượng LeRobotDatasetMetadata hoặc một đối tượng EnvConfig. Hàm này có thể khởi tạo một policy mới từ đầu hoặc tải một policy đã được huấn luyện trước đó.