トラブルシューティング¶
工程が失敗すると、JSON の結果は "status": "error" になり、errors に失敗した検査の名前が入ります。役に立つコマンドは 3 つです。
urdf2vla doctor # マシンを検査する: GPU ドライバ、Docker、image、コンテナ、ディスク
urdf2vla diagnose --project projects/myrobot # 最後のログを既知の問題と照らし合わせ、対処を提案する
urdf2vla status --project projects/myrobot # どの工程が済んだか、次に何を実行するか
ロボットではなく環境の問題に見えるとき(コンテナが起動しない、GPU が見つからない)は、まず urdf2vla doctor を実行します。
各工程は、検査の元になった測定値を報告ファイルにも書きます: build/import_report.yaml、build/launch_report.yaml、
build/teleop_report.yaml、build/collect_report.yaml、build/convert_report.yaml、build/eval_report.yaml。
ログの全文は logs/ にあります。
設定の変え方
generated/ のファイルは編集しないでください(次に実行すると書き直されます)。変更は project.yaml の overrides:
に(生成されたファイルと同じ構造で)書き、そのファイルを作る工程と、その後の工程を実行し直します。
urdf2vla status で、もう一度実行が必要な工程が分かります。
症状から探す¶
グリッパは閉じるが、物体が滑り落ちる・落ちる¶
| 失敗した検査 | 工程 | 意味 | 対処 |
|---|---|---|---|
joint_limits_hold |
import_robot |
指の関節が押されて可動範囲を越えた。シミュレータで可動範囲が効いていない。簡略化された URDF のグリッパでよく起きる | グリッパを SimReady のアセットに付け替える: robot.gripper.simready(ガイド)。configure_robot からやり直す |
grasp_hold |
launch_sim |
指の間に置いた物体が、離した後に離れていった | overrides.robot.asset.solver_position_iterations を増やして(既定 32、SimReady のグリッパは 64)import_robot からやり直す。グリッパの力が不自然なら、トルク上限を確かめる |
grasp_opening |
launch_sim |
直動の指が物体の幅より狭く閉じた(めり込んだ) | overrides.robot.asset.solver_position_iterations を増やして import_robot からやり直す |
object_on_table:<object> |
launch_sim |
物体が、大きさから決まる高さで台の上に落ち着かない | たいていはアセットの問題(剛体や衝突形状が見た目と合わない)。task.objects から外し、build/launch_report.yaml(object_frames)を付けて報告してください |
asset_size:<object> |
launch_sim |
生成した物体の大きさがカタログと 15 % 以上違う(アセットの縮尺や単位の誤り) | task.objects から外して報告してください |
物体が複数あると、把持の検査は物体ごとに出ます(grasp_hold:<gripper>:<object>)。失敗した物体だけ task.objects から
外せば、ほかの物体はそのまま使えます。グリッパの開きより幅の広い物体は、configure_task が警告を出して除いています。
ロボットが姿勢を保てない・震える・吹き飛ぶ¶
| 失敗した検査 | 意味 | 対処 |
|---|---|---|
no_nan |
シミュレーションが発散した | 関節のゲインを下げる(下記)、URDF に質量や慣性のない link がないか確かめる、自己衝突を有効にしていたら無効にする(overrides.robot.asset.self_collision) |
default_pose_tracking |
初期姿勢に届かない関節がある | その関節のトルク上限(URDF が仮の値なら robot.effort_limits)と初期姿勢を確かめ、剛性を上げる(下記) |
within_limits |
初期姿勢が関節の可動範囲の外 | robot.default_pose を直す |
gripper_motion |
グリッパが開・閉の位置に届かない | 開く向き(grippers.0.open_position)と、指の関節のトルク・速度の上限を確かめる |
関節ゲインの変え方: actuators はリストで、overrides に書いたリストは生成されたものを丸ごと置き換えます。
generated/robot_config.yaml の actuators: のリスト全体を project.yaml の overrides.robot.actuators に写し、
stiffness / damping を変えて、configure_robot からやり直します。
手先が違う向きに動く¶
| 失敗した検査 | 工程 | 対処 |
|---|---|---|
ik_direction:<arm>:+x / +z / -y |
setup_teleoperation |
ある軸の方向に動かす指令で、別の方向に動いた。ロボットの正面(robot.front_axis)、手先の link(arms.0.ee_link)、初期姿勢が特異姿勢(腕が伸び切った姿勢)の近くでないかを確かめる |
action_label |
setup_teleoperation |
制御器が出す関節の目標がロボットと合わない。たいていは上の問題のどれかが原因 |
カメラに何も写らない・違うものが写る¶
| 失敗した検査 | 意味 | 対処 |
|---|---|---|
camera_not_black |
画像が(ほぼ)真っ黒。たいていはカメラがロボットの形状の中にある | 動かす: project.yaml の cameras:。手先カメラなら offset(- {preset: wrist, offset: 0.12})。configure_camera からやり直す |
camera_alive, camera_frames_updated |
2 つの step の間で画像が変わらなかった。止まったカメラは学習データを台無しにする | overrides.task.render_fix: true を書き、configure_task からやり直す(制御 step ごとに描画が 1 回増えます) |
camera_mount |
手先カメラが設定した位置にない | build/launch_report.yaml を付けて不具合として報告してください |
first_frame_fresh |
エピソードの最初の画像に前のエピソードが写っている | そのデータセットは使わず、新しい --dataset の名前で記録し直す |
画像を見てください: launch_sim の snapshots/<カメラ>_start.png と _end.png、または全カメラの視野を描く
urdf2vla view。
記録が失敗する・成功が少ない¶
build/collect_report.yaml に全試行が載っています(object_lift_m: 物体が持ち上がったか、object_to_target_m:
置き場所からどれだけ離れて終わったか)。snapshots/collect_fail_*.png は失敗した試行の最後の画像です。
- 物体が持ち上がらない — 掴む問題: 上のグリッパの項を見るか、掴む高さを調整する(
overrides.teleop.grasp_height_offset)。 - 持ち上がるが置けない — 置き場所に届きにくい:
overrides.task.target.posで近づける。 label_replayが失敗する — 記録した行動を再生しても同じ動きにならない(ラベルがロボットの動きを表していない)。 先にik_directionとグリッパの検査を確かめる。
変換・学習が失敗する¶
| 失敗した検査 | 対処 |
|---|---|
gr00t_loader |
GR00T が変換したデータセットを読めなかった。convert_dataset --force をやり直し、続くなら build/convert_report.yaml を付けて報告してください |
video_matches:<カメラ> |
エンコードした動画が記録した画像と違う。convert_dataset --force をやり直す |
finetune_args_valid |
GR00T が学習の引数を受け付けなかった。train_vla に渡した値を確かめる |
gripper_timing |
グリッパの切り替えが、どの学習サンプルでも実行できない位置にあり、モデルがそれを学べない。convert_dataset --force をやり直す(これを直すフレームを足します) |
release_check |
学習したモデルが、デモでグリッパを開く場所で開かない。評価では物体を運んだまま放さない。--force で変換し直し、gripper_timing を確かめてから学習し直す |
401 … Cannot access gated repo |
学習と評価には nvidia/Cosmos-Reason2-2B が必要。ライセンスに同意してログインする(インストール) |
| 「この GPU では GR00T N1.7 を学習できません」の警告 | エラーではありません。44 GB 以上のマシンで学習します(学習と評価) |
学習したモデルが評価で失敗する¶
evaluate_vla は失敗したエピソードごとに build/eval_report.yaml に原因(failure)を書き、いちばん多いものを
warnings に出します。そのエピソードの動画を --video で見てください。
failure |
起きたこと | 対処 |
|---|---|---|
never_closed |
グリッパが一度も閉じなかった | モデルが物体まで届いていない。デモを増やすか、カメラに物体が写っているか確かめる |
missed_grasp |
閉じたが物体が持ち上がらなかった | 把持がずれている。デモを増やすか、物体の位置のばらつきを減らす |
never_released |
物体を持ち上げたまま開かなかった | 上の gripper_timing と release_check を見る |
released_off_target |
放したが容器の中ではなかった | どこへ行くかを学べていない。デモか学習ステップを増やす |
環境の問題¶
まず urdf2vla doctor を実行します。ここにあるものをまとめて調べ、それぞれの直し方を示します。
| メッセージ・症状 | 原因 | 対処 |
|---|---|---|
nvidia-smi が失敗する、nvidia-container-cli: … driver not loaded |
GPU ドライバが読み込まれていない。カーネルが自動更新され、新しいカーネル用のドライバのモジュールが入っていないことが多い | urdf2vla doctor が、ドライバとカーネル用のモジュールを一緒に更新する apt install のコマンド(その後に再起動)か、代わりに起動できる古いカーネルを示す |
Docker のソケットで permission denied |
ユーザが docker グループに入っていない |
sudo usermod -aG docker $USER の後、ログインし直す |
「コンテナ … が起動していません」/ No such container |
コンテナが動いていない | bash docker/run.sh(変換・学習・評価は bash docker/run.sh gr00t も) |
| 「…秒以内に終わりませんでした」 | Isaac Sim の最初の起動はシェーダのコンパイルで数分かかることがある | --timeout を大きくしてもう一度実行する |
GLXBadFBConfig |
OpenGL の設定が GPU と合わない(GPU が 2 つあるノート PC で起きやすい) | runtime.yaml の env: に __NV_PRIME_RENDER_OFFLOAD: "1" と __GLX_VENDOR_LIBRARY_NAME: nvidia を足す |
| メッシュのファイルを開けない | URDF が参照するメッシュがコンテナから見えない | urdf2vla show --project … robot_metadata の meshes を確かめ、フォルダを robot.package_paths に足す |
CUDA out of memory |
他のプロセスが GPU を使っている | nvidia-smi で確かめ、他の学習ジョブやコンテナを止める。学習と評価は 46 GB の GPU 1 枚に同時には収まらない |
The NVIDIA driver on your system is too old (found version 12070) |
ドライバが 580 より古い。イメージは CUDA 13 が必要 | ドライバを 580 以上に上げる(Brev のガイド) |
unresolvable CDI devices nvidia.com/gpu=all |
Docker 用の GPU の記述(CDI)がないか、古いドライバのもの | sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml(詳細) |
| checkpoint の保存中に学習が止まる | ディスクがいっぱい。checkpoint は 1 つ 24 GB | 空きを作るか train_vla --save-total-limit を下げる。train_vla は最後の checkpoint から再開する |
urdf2vla view が「追加のパッケージが必要」と言う |
画面用のパッケージが入っていない | uv pip install -e '.[view]' |
助けを求める¶
実行したコマンド、その JSON の出力、その工程の報告ファイル(build/*_report.yaml)、logs/ のログの末尾を付けて
issue を作ってください。urdf2vla diagnose がログの関係する部分を表示します。