Hugging Face's logo

LeRobot documentation

Bộ xử lý

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Bộ xử lý

Processor là lớp biến đổi dữ liệu giữa robot, tập dữ liệu và policy. Một pipeline là một chuỗi các ProcessorStep; mỗi bước khai báo cách nó biến đổi cả dữ liệu lẫn hợp đồng đặc trưng.

Xem Giới thiệu về Robot Processors để nắm các khái niệm, Tự triển khai processor của bạn để viết một bước, và Chẩn đoán pipeline processor của bạn khi pipeline hoạt động sai.

ProcessorStep

lớp lerobot.processor.ProcessorStep

< >

( )

Lớp trừu tượng cơ sở cho một bước trong quy trình xử lý dữ liệu.

Mỗi bước phải triển khai phương thức __call__ để thực hiện phép biến đổi trên một chuyển tiếp dữ liệu và phương thức transform_features để mô tả cách nó thay đổi hình dạng hoặc kiểu của các đặc trưng dữ liệu.

Các lớp con có thể tùy chọn là có trạng thái bằng cách triển khai state_dict và load_state_dict.

get_config

< >

( )

Trả về cấu hình của bước cho mục đích xuất chuỗi.

load_state_dict

< >

( state: dict[str, torch.Tensor] )

Tham số

  • state — Một từ điển chứa các tensor trạng thái.

Tải trạng thái của bước từ một từ điển trạng thái.

đặt lại

< >

( )

Đặt lại trạng thái nội bộ của bước xử lý, nếu có.

save_artifacts

< >

( save_directory: Path )

Lưu các tài sản không phải tensor và ánh xạ các đối số khởi tạo map tới các đường dẫn tương đối.

state_dict

< >

( )

Trả về trạng thái của bước (ví dụ: các tham số đã học, các giá trị trung bình chạy).

transform_features

< >

( features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

Tham số

  • features — Một từ điển mô tả các đặc trưng đầu vào cho các quan sát, hành động, v.v.

Định nghĩa cách bước này thay đổi mô tả của các tính năng pipeline.

Phương pháp này được sử dụng để theo dõi các thay đổi về hình dạng dữ liệu, dtype hoặc chế độ dữ liệu khi dữ liệu đi qua pipeline, mà không cần phải xử lý dữ liệu thực tế.

DataProcessorPipeline

lớp lerobot.processor.DataProcessorPipeline

< >

( steps: Sequence[ProcessorStep] = <factory>name: str = 'DataProcessorPipeline'to_transition: Callable[[TInput], EnvTransition] = <factory>to_output: Callable[[EnvTransition], TOutput] = <factory>before_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory>after_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory> )

Tham số

  • steps — Một chuỗi các đối tượng ProcessorStep tạo nên pipeline.
  • name — Tên mô tả cho pipeline.
  • to_transition — Một hàm để chuyển đổi dữ liệu đầu vào thô sang định dạng EnvTransition đã được chuẩn hóa.
  • to_output — Một hàm để chuyển đổi EnvTransition cuối cùng sang định dạng đầu ra mong muốn.
  • before_step_hooks — Một danh sách các hàm sẽ được gọi trước khi mỗi bước được thực thi.
  • after_step_hooks — Một danh sách các hàm sẽ được gọi sau khi mỗi bước được thực thi.

Một pipeline tuần tự để xử lý dữ liệu, được tích hợp với Hugging Face Hub.

Lớp này kết nối nhiều instance ProcessorStep với nhau để tạo thành một quy trình xử lý dữ liệu hoàn chỉnh. Nó mang tính tổng quát, cho phép tùy chỉnh kiểu dữ liệu đầu vào và đầu ra, được xử lý bởi các bộ chuyển đổi to_transition và to_output.

from_config

< >

( config: dict[str, Any]state_dict: dict[str, dict[str, torch.Tensor]] | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None )

Tham số

  • config — Một từ điển cấu hình có cùng cấu trúc với JSON của bộ xử lý đã lưu.
  • state_dict — Tùy chọn, trạng thái pipeline trong bộ nhớ được nhóm theo khóa trạng thái không có hậu tố.
  • overrides — Các ghi đè tùy chọn cho constructor, được định danh theo tên registry hoặc tên lớp.
  • to_transition — Bộ chuyển đổi tùy chọn từ dữ liệu đầu vào sang EnvTransition.
  • to_output — Bộ chuyển đổi tùy chọn từ EnvTransition sang dữ liệu đầu ra.

Xây dựng một pipeline từ cấu hình trong bộ nhớ và các tensor trạng thái tùy chọn.

from_pretrained

< >

( pretrained_model_name_or_path: str | Pathconfig_filename: strforce_download: bool = Falseresume_download: bool | None = Noneproxies: dict[str, str] | None = Nonetoken: str | bool | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falserevision: str | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None**kwargs )

Tham số

  • pretrained_model_name_or_path — Định danh của kho trên Hugging Face Hub, đường dẫn đến một thư mục cục bộ, hoặc đường dẫn đến một tệp cấu hình đơn lẻ.
  • config_filename — Tên tệp cấu hình JSON của pipeline. Luôn bắt buộc để tránh mơ hồ khi có nhiều cấu hình (ví dụ: preprocessor so với postprocessor).
  • force_download — Xác định có nên buộc (tải lại) các tệp hay không.
  • resume_download — Được giữ lại để đảm bảo tương thích ngược và bị bỏ qua. Việc tải xuống sẽ tự động tiếp tục.
  • proxies — Được giữ lại để đảm bảo tương thích ngược và bị bỏ qua. Hãy sử dụng HTTP_PROXY và HTTPS_PROXY thay thế.
  • token — Token được sử dụng làm HTTP bearer authorization cho các kho Hub riêng tư.
  • cache_dir — Đường dẫn đến thư mục cache cụ thể để lưu trữ các tệp đã tải xuống.
  • local_files_only — Nếu là True, tránh tải tệp từ Hub.
  • revision — Phiên bản mô hình cụ thể cần sử dụng (ví dụ: tên nhánh, tên tag, hoặc id commit).
  • overrides — Một từ điển để ghi đè cấu hình của các bước cụ thể. Các khóa nên khớp với tên lớp hoặc tên đăng ký của bước đó.
  • to_transition — Một hàm tùy chỉnh để chuyển đổi dữ liệu đầu vào thành EnvTransition.
  • to_output — Một hàm tùy chỉnh để chuyển đổi EnvTransition cuối cùng sang định dạng đầu ra.
  • **kwargs — Các đối số bổ sung (không được sử dụng).

Gây ra

FileNotFoundError hoặc ValueError hoặc ImportError hoặc KeyError hoặc ProcessorMigrationError

  • FileNotFoundError — Nếu không tìm thấy tệp cấu hình.
  • ValueError — Nếu cấu hình không rõ ràng hoặc việc khởi tạo thất bại.
  • ImportError — Nếu không thể nhập class của một bước.
  • KeyError — Nếu một khóa ghi đè không khớp với bất kỳ bước nào trong pipeline.
  • ProcessorMigrationError — Nếu mô hình yêu cầu di chuyển sang định dạng processor.

Tải một pipeline từ thư mục cục bộ, tệp đơn hoặc kho lưu trữ Hugging Face Hub.

Phương pháp này triển khai một quy trình tải đơn giản hóa với khả năng phát hiện di chuyển thông minh:

Chiến lược tải đơn giản hóa:

  1. Tải cấu hình (_load_config):

    • Thư mục: Nạp config_filename được chỉ định từ thư mục
    • Một tệp: Nạp tệp trực tiếp (bỏ qua config_filename)
    • Kho Hub: Tải xuống config_filename được chỉ định từ Hub

  2. Thẩm định cấu hình (_validate_loaded_config):

    • Kiểm tra định dạng: Đảm bảo cấu hình là định dạng bộ xử lý hợp lệ
    • Phát hiện di chuyển: Hướng dẫn người dùng di chuyển các mô hình LeRobot cũ
    • Xử lý lỗi: Cung cấp thông báo lỗi có thể hành động

  3. Xây dựng bước (_build_steps_with_overrides):

    • Giải quyết lớp: Tra cứu trong Registry hoặc nhập động
    • Ghép đè: Tham số của người dùng đè lên cấu hình đã lưu
    • Tải trạng thái: Tải các tệp .safetensors cho các bước có trạng thái

  4. Ghi đè Xác thực (_validate_overrides_used):

    • Đảm bảo tất cả các ghi đè của người dùng đã được áp dụng (phát hiện lỗi chính tả)
    • Cung cấp thông báo lỗi hữu ích kèm theo các khóa khả dụng

Phát hiện di cư:

  • Phát hiện thông minh: Phân tích các tệp JSON để phát hiện các mô hình LeRobot cũ
  • Định vị chính xác: Tránh dương tính giả trên các mô hình HuggingFace khác
  • Hướng dẫn rõ ràng: Cung cấp chính xác lệnh di chuyển cần chạy
  • Chế độ lỗi: Luôn gây ra ProcessorMigrationError để người dùng có hành động rõ ràng

Tải các ví dụ:

# Directory loading
pipeline = DataProcessorPipeline.from_pretrained("/models/my_model", config_filename="processor.json")

# Single file loading
pipeline = DataProcessorPipeline.from_pretrained(
    "/models/my_model/processor.json", config_filename="processor.json"
)

# Hub loading
pipeline = DataProcessorPipeline.from_pretrained("user/repo", config_filename="processor.json")

# Multiple configs (preprocessor/postprocessor)
preprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_preprocessor.json"
)
postprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_postprocessor.json"
)

Hệ thống ghi đè:

  • Khớp chính: Sử dụng tên registry hoặc tên lớp làm khóa ghi đè
  • Gộp cấu hình: Các ghi đè của người dùng có ưu tiên cao hơn cấu hình đã lưu
  • Validation: Đảm bảo tất cả các khóa ghi đè khớp với các bước thực tế (phát hiện lỗi chính tả)
  • Ví dụ: overrides={“NormalizeStep”: {“device”: “cuda”}}

get_config

< >

( )

Trả về cấu hình pipeline có thể được serialize thành JSON.

load_state_dict

< >

( state_dict: dict[str, dict[str, torch.Tensor]] )

Tham số

  • state_dict — Một từ điển ánh xạ các khóa trạng thái không có hậu tố tới các từ điển trạng thái bước.

Gây ra

KeyError

  • KeyError — Nếu quá trình tải phát hiện trạng thái mong đợi bị thiếu hoặc trạng thái thừa không mong muốn.

Nạp các tensor trạng thái pipeline vào các bước hiện có.

process_action

< >

( action: PolicyAction | RobotAction | EnvAction )

Tham số

  • action — Dữ liệu hành động.

Chỉ xử lý phần hành động của một bước chuyển tiếp thông qua pipeline.

process_complementary_data

< >

( complementary_data: dict[str, Any] )

Tham số

  • complementary_data — Từ điển dữ liệu bổ sung.

Chỉ xử lý phần dữ liệu bổ sung của một bước chuyển đổi thông qua pipeline.

process_done

< >

( done: bool | torch.Tensor )

Tham số

  • done — Cờ done.

Chỉ xử lý cờ done của một transition qua pipeline.

process_info

< >

( info: dict[str, Any] )

Tham số

  • info — Từ điển thông tin.

Chỉ xử lý từ điển thông tin của một bước chuyển đổi thông qua đường ống.

process_observation

< >

( observation: RobotObservation )

Tham số

  • observation — Từ điển quan sát.

Chỉ xử lý phần quan sát của một bước chuyển tiếp thông qua pipeline.

process_reward

< >

( reward: float | torch.Tensor )

Tham số

  • reward — Giá trị phần thưởng.

Chỉ xử lý phần thưởng của một bước chuyển tiếp thông qua pipeline.

process_truncated

< >

( truncated: bool | torch.Tensor )

Tham số

  • truncated — Cờ truncated.

Chỉ xử lý cờ bị cắt ngắn của một bước chuyển tiếp qua đường ống.

register_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Tham số

  • fn — Một hàm có thể gọi, nhận vào chỉ số bước và transition hiện tại.

Đăng ký một hàm để được gọi sau mỗi bước.

register_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Tham số

  • fn — Một hàm có thể gọi, nhận vào chỉ số bước và transition hiện tại.

Đăng ký một hàm để được gọi trước mỗi bước.

đặt lại

< >

( )

Đặt lại trạng thái của tất cả các bước có trạng thái trong pipeline.

save_pretrained

< >

( save_directory: str | Path | None = Nonerepo_id: str | None = Nonepush_to_hub: bool = Falsecard_kwargs: dict[str, Any] | None = Noneconfig_filename: str | None = None**push_to_hub_kwargs )

Tham số

  • save_directory — Thư mục nơi pipeline sẽ được lưu. Nếu là None, sẽ lưu vào HF_LEROBOT_HOME/processors/{sanitized_pipeline_name}.
  • repo_id — ID của kho của bạn trên Hub. Chỉ được sử dụng nếu push_to_hub=true.
  • push_to_hub — Có nên đẩy đối tượng của bạn lên Hugging Face Hub sau khi lưu hay không.
  • card_kwargs — Các đối số bổ sung được truyền vào mẫu thẻ để tùy chỉnh thẻ.
  • config_filename — Tên của tệp cấu hình JSON. Nếu là None, tên sẽ được tạo từ thuộc tính name của pipeline.
  • **push_to_hub_kwargs — Các đối số từ khóa bổ sung được truyền đến phương thức push_to_hub.

Lưu cấu hình và trạng thái của pipeline vào một thư mục.

Phương pháp này tạo ra một tệp cấu hình JSON xác định cấu trúc của pipeline (tên và các bước). Đối với mỗi bước có trạng thái, nó cũng lưu một tệp .safetensors chứa từ điển trạng thái của bước đó.

state_dict

< >

( )

Trả về các tensor trạng thái pipeline được nhóm theo khóa trạng thái.

step_through

< >

( data: TInput )

Tham số

  • data — Dữ liệu đầu vào.

Xử lý dữ liệu từng bước, tạo ra sự chuyển tiếp ở mỗi giai đoạn.

Đây là một phương thức generator hữu ích để gỡ lỗi và kiểm tra trạng thái trung gian của dữ liệu khi nó đi qua pipeline.

transform_features

< >

( initial_features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

Tham số

  • initial_features — Một từ điển mô tả các đặc trưng ban đầu.

Áp dụng các phép biến đổi đặc trưng từ tất cả các bước một cách tuần tự.

Phương pháp này truyền một từ điển mô tả đặc trưng qua phương pháp transform_features của từng bước, cho phép pipeline xác định tĩnh đặc tả đặc trưng đầu ra mà không cần xử lý bất kỳ dữ liệu thực nào.

unregister_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Tham số

  • fn — Đối tượng hàm chính xác đã được đăng ký trước đó.

Gây ra

ValueError

  • ValueError — Nếu không tìm thấy hook trong danh sách.

Hủy đăng ký một hook ‘after_step’.

unregister_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Tham số

  • fn — Đối tượng hàm chính xác đã được đăng ký trước đó.

Gây ra

ValueError

  • ValueError — Nếu không tìm thấy hook trong danh sách.

Hủy đăng ký một hook ‘before_step’.

PolicyProcessorPipeline

lerobot.processor.DataProcessorPipeline

( *args**kwargs )

Update on GitHub

←Chính sách Môi trường→