Your own policy
roboloomはmodelの形を決めません.方策は reset() と infer(observation) を持つobjectで,記録と同じ観測を受け取り,関節の絶対目標を返します.LeRobotのcheckpointを使うときは LeRobotの方策 を参照してください.
The policy's shape
reset() と infer(observation) を持つobjectを返す関数を書きます(roboloom.Policy).
# .roboloom/<robot>/my_policy.py, or an installed package
import numpy as np
class MyPolicy:
def __init__(self, checkpoint: str): ...
def bind(self, spec): # optional; called once, right after loading
if "observation.images.left_wrist" not in spec.observation:
raise ValueError("add left_wrist to observe")
def reset(self): ... # called when an episode starts
def infer(self, observation) -> np.ndarray:
state = observation["observation.state"] # float32 [n]
image = observation["observation.images.left_wrist"] # uint8 [h, w, 3], RGB
task = observation["task"]
return self.model(state, image, task) # [n] or [H, n]
def load(checkpoint: str) -> MyPolicy:
return MyPolicy(checkpoint)
- 観測:keyは記録したdatasetの特徴量と同じです(
observation.state,observation.images.<名前>,observation.<入力の名前>など).値はnumpyで,画像は[h, w, 3]のuint8(RGB)です.taskも渡されます.特徴量の一覧は datasetの特徴量 にあります. - 出力:関節の目標値を,記録した
actionと同じ並び(followerを設定の順につないだもの)と単位で返します.1手[n]か,まとめた行動[H, n]です. - robotごとの観測の名前と大きさ,行動の並び・要素数・単位は,各robotのページにあります(Rakuda2,開発中の PiPER).
bind(spec)(任意):読み込みの直後,episodeより前に1回呼ばれます.spec(roboloom.policy.PolicySpec)の中身は次のとおりです.observation:観測の名前ごとのdtype,shape,namesaction:行動の各要素の名前(left.joint1,…,right_gripper.gripper)rate_hz,dataset_fps
学習したときと違う構成なら例外を出してください.controllerは failed になり,理由を画面に出して,episodeを始めません.roboloom infer と Session.wait_ready は,待たずに理由を示して終わります.bind を書かない方策も,これまでどおり動きます.
Pythonの型と関数は Python API:方策 にあります.
Selecting observations
Rakuda2のtemplateは,DIGITなしで関節状態とRealSenseを方策に渡します.nodes/policy.yaml の observe を,学習時に使った入力に合わせます.followerの関節状態は常に渡されます.
| 方策に渡す観測 | observe |
有効にするoption |
|---|---|---|
| 関節状態+RealSense(既定) | [camera] |
policy |
| 関節状態+RealSense+左右DIGIT | [camera, digit_left, digit_right] |
digit,policy |
| 関節状態のみ | [] |
policy |
digit を有効にするだけでは,方策の入力は変わりません.observe に追加したsensorは,sensors にも存在する必要があります.observe から外しても,sensors にあるsensorは開いて記録します.cameraも使わない構成では,config.yaml の sensors から camera を外してください.起動ごとに選ぶ方法は sensor選択 にあります.
DIGITを入力とする学習済み方策を,DIGITなしでそのまま使えるわけではありません.DIGITなしの入力で学習した方策を使います.LeRobotの読み込みは,必要な入力が足りなければ開始前に拒否します.自作の方策では bind(spec) で同じ検査を書けます.
既存projectの設定は,package更新では上書きされません.roboloom init rakuda2 --update が,足りないfile(nodes/policy.yaml など)を足し,config.yaml に足りないoptionを一覧にします.以前のtemplateから移行するときは,config.yaml の options.policy から requires: [digit] を削除し,nodes/policy.yaml を observe: [camera] に変更します.評価の保存先はDIGITなしなら datasets/rakuda2-eval,digit も有効なら datasets/rakuda2-digit-eval です.
When the policy fails during an episode
inferやresetが例外を出すと,controllerは指令を止めてfailedになり,followerは保持します.理由は画面のcontrollerの行に出ます.roboloom infer,Session.record,操作画面の時間指定の実行は,そのepisodeを破棄します(保存しません).Session.recordはEpisodeFailedを上げます.stopかdiscardでepisodeを終えると,方策はreadyに戻ります.再起動は要りません.次のstartはpolicy.reset()から始めます.理由の表示は次のstartまで残ります.- 読み込めなかった方策(
bindの例外を含む)はfailedのままです.直してから起動し直してください. - followerがFAULTかESTOPになったepisodeも,同じく破棄します.
History, joints left alone, and fresh samples
最新のframe以外にmodelが要るものは,controllerに頼みます.modelを作り替えるたびに書き直す必要はありません.正規化,画像の縮小,model独自の行動(差分,一部の関節だけ)を関節の目標へ直す処理は,方策の側に書きます.
observation_history: 4 # default 1: only the latest frame
hold: [follower.torso_yaw, follower.head_yaw, follower.head_pitch] # default []
observation_history: N:観測を行動1手ごと(1/rate_hzごと)に1回採ります.まとめた行動のうち推論しない手でも採ります.inferにはobservation["history"]も渡ります.観測の各配列を[N, ...]に重ねたもので,古い順に並び,最後が今のframeです.episodeの始めは,最初のframeで履歴を埋めます.history["action"](float32[N, n])は,各frameの前に実行した行動です(始めはfollowerが保持していた目標).値はfollowerへ送った指令で,recorderがactionに書くものと同じです.方策の出力がmax_speedを超えて削られたときは,削られたあとの値が入ります.過去の行動を読むmodelに使います.N = 1なら観測は今までと同じです.hold:行動のうち方策が動かさない要素(<follower>.<joint>)です.方策がそこに何を返しても(NaNでも),followerが保持している目標に置き換えます.一部の関節だけで学習したmodelも,[n]か[H, n]を返せば済みます.ほかの要素は有限でなければならず,そうでなければepisodeを止めます.記録したactionにもその entry が入ります.hold の置換の後に明示的な write claim を持つ hook が変更できます(dataの形式).-
options()(任意):方策が自分でこれらを指定できます.YAMLより優先します.modelを差し替えても設定を書き換えずに済みます.def options(self) -> dict: return { "observation_history": 4, "hold": ["follower.torso_yaw"], "action_horizon": 8, } -
bind(spec)にはspec.history,spec.hold,spec.units(行動の各要素の単位),spec.inference(syncかasync)も渡ります. - 新しい観測だけを使う:観測する入力やsensorの最新の値が,recorderの
max_age_ms.<node>より古いと,方策を止めます(controllerの行にstale_observation).指令を送らず,followerは保持します.補間の途中でも止めます.値が新しくなると,方策をreset()して始め直します.max_age_msは recorderの設定 にあります.
From a recording to your own model
roboloomはmodelの形を決めません.方策には,記録と同じ観測,その履歴,実行した行動を渡し,関節の絶対目標を受け取ります.modelごとに変わる処理は方策の側に書きます.
| 処理 | 書く場所 |
|---|---|
| modelが動かす関節の選択 | 方策.ほかの関節には何を返してもよく(NaN),その関節を hold に挙げる |
| 正規化(学習dataの統計) | 方策.統計はcheckpointと一緒に保存する |
| 画像の縮小や切り出しなどの前処理 | 方策 |
| 行動の形(状態からの差分,一部の関節だけ) | 方策が infer の中で絶対目標に戻す |
| 観測の履歴,過去の行動 | roboloom(observation_history) |
| 記録より低い行動周期 | k行おきに学習し,rate_hz を dataset_fps / k にする |
| 制御周期への補間,速度の制限,安全の検査 | roboloom |
repositoryの examples/policies/chunk_mlp.py は,これらを一通り行う小さなmodelです(関節状態だけを使い,CPUで数秒で学習できます).記録したdatasetの observation.state と action の列を読んで学習し,統計・動かす関節・履歴の長さをcheckpointに保存して,options() でroboloomに伝えます.
uv run python examples/policies/chunk_mlp.py train \
--dataset .roboloom/rakuda2/datasets/rakuda2 --out outputs/chunk_mlp.pt \
--history 4 --horizon 8 --stride 3 --exclude torso_yaw head_yaw head_pitch
PYTHONPATH=$PWD/examples/policies uv run roboloom infer rakuda2 --seconds 20 \
--policy chunk_mlp:load --policy-kwargs "{\"checkpoint\": \"$PWD/outputs/chunk_mlp.pt\"}"
15 fpsの記録で --stride 3 なら,方策の周期は5 Hzです.nodes/policy.yaml を rate_hz: 5 にします.学習でdatasetを読むとき,表の列(observation.state,action,action.valid,episode_index,index)は LeRobotDataset(...).hf_dataset にあります.画像は dataset[i] で1行ずつ復号します.action.valid が0の行の扱いは 欠損の扱い にあります.
Hooks
Mock only
policy は bind の後に hooks() -> Sequence[Hook] を提供できます.local action period の処理は Hook.step(action, ctx),終了処理は on_episode_ended(event) に実装します.writing hook には hooks: YAML の from: policy と write limit が必須です.hold は hook の前に置換し,claim した held joint は hook が変更できます.hooks の release gate と,async inference と state を共有する前に threading を参照してください.