Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,124 @@
+---
+license: apache-2.0
+library_name: lerobot
+tags:
+  - robotics
+  - imitation-learning
+  - act
+  - so-arm101
+  - lerobot
+datasets:
+  - himorishige/so101_candy_basket
+pipeline_tag: robotics
+---
+
+# ACT Policy: SO-ARM101 Candy Basket Delivery
+
+## モデル概要
+
+SO-ARM101 ロボットアームが飴ちゃん入りカゴを掴んでユーザーの元へ運ぶ動作を、模倣学習で獲得したモデルです。エンジニアの疲労を検知する空間AIシステムの一部として、疲労度が閾値を超えた際に自動で飴ちゃんを配達します。
+
+## ベースモデル
+
+- **アルゴリズム**: ACT (Action Chunking with Transformers)
+- **Vision Backbone**: ResNet18 (ImageNet pretrained)
+- **パラメータ数**: 52M (51,597,190)
+- **フレームワーク**: [LeRobot](https://github.com/huggingface/lerobot) v0.4.4
+
+## 学習方法
+
+- **手法**: 模倣学習（Imitation Learning）— テレオペレーションで収集した人間のデモンストレーションを教師データとして学習
+- **ファインチューニング**: なし（スクラッチから学習）
+- **VAE**: 有効（use_vae=True, kl_weight=10.0）
+
+### 学習パラメータ
+
+| パラメータ | 値 |
+|-----------|-----|
+| ステップ数 | 100,000 |
+| バッチサイズ | 16 |
+| 学習率 | 1e-05 |
+| オプティマイザ | AdamW (weight_decay=0.0001) |
+| chunk_size | 100 |
+| n_action_steps | 100 |
+| latent_dim | 32 |
+| dim_model | 512 |
+| n_encoder_layers | 4 |
+| n_decoder_layers | 1 |
+| n_heads | 8 |
+| vision_backbone | resnet18 |
+| 最終 loss | 0.031 |
+
+## 使用データ
+
+- **データセット**: [himorishige/so101_candy_basket](https://huggingface.co/datasets/himorishige/so101_candy_basket)
+- **エピソード数**: 50
+- **フレーム数**: 29,186
+- **収集方法**: 人間によるテレオペレーション（リーダー・フォロワー構成）
+- **カメラ**: 2台（俯瞰 + グリッパー）、640×480、30fps
+
+## 想定ユースケース
+
+- SO-ARM101 ロボットアームによるオブジェクト運搬タスク
+- 疲労検知システムと連携した飴ちゃん自動配達デモ
+- 模倣学習（ACT）の実験・研究
+
+## 非推奨ユースケース
+
+- 安全が求められる産業用途での直接利用（本モデルはハッカソンデモ用）
+- SO-ARM101 以外のロボットハードウェアでの利用（キャリブレーションが異なる）
+
+## 性能・評価
+
+| 指標 | 値 |
+|------|-----|
+| 最終 training loss | 0.031 |
+| 推論FPS（CUDA） | 30Hz |
+
+推論FPSは学習時FPS（30Hz）と一致させることが成功率に直結します。
+
+## 推論方法
+
+### 必要環境
+
+- Python >= 3.12
+- CUDA 対応 GPU
+- SO-ARM101 ロボットアーム（フォロワー）
+- USB カメラ 2台（俯瞰 + グリッパー）
+
+### インストール
+
+```bash
+pip install "lerobot[feetech]>=0.4.4"
+```
+
+### 実行
+
+```bash
+lerobot-record \
+  --robot.type=so101_follower \
+  --robot.port=/dev/ttyACM0 \
+  --robot.cameras='{ "front": {"type": "opencv", "index_or_path": 2, "width": 640, "height": 480, "fps": 30}, "wrist": {"type": "opencv", "index_or_path": 0, "width": 640, "height": 480, "fps": 30} }' \
+  --policy.path=himorishige/act_so101_candy_basket \
+  --dataset.repo_id=himorishige/eval_so101_candy_basket \
+  --dataset.fps=30 \
+  --dataset.num_episodes=1 \
+  --dataset.push_to_hub=false \
+  --dataset.single_task="Pick up candy basket and deliver it"
+```
+
+## 制約・限界
+
+- 学習データは特定の机配置・照明条件で収集されたため、大きく異なる環境では性能が低下する可能性があります
+- カゴの形状・サイズが学習時と異なると掴み動作が失敗する可能性があります
+- 推論FPSが学習時FPS（30Hz）を下回ると成功率が著しく低下します
+
+## ライセンス
+
+Apache-2.0
+
+## 引用情報
+
+本モデルは関西電力KOI×VOLTMIND 生成AIハッカソン（2026年3月）にて Team NANIWA-Factory が開発しました。
+
+- GitHub: https://github.com/SeiyaCM/kanden-ai-hackathon