# إعادة تسمية الكاميرات الخالية

عند تدريبك أو تقييمك أو تسجيلك باستخدام سياسة روبوتية، يوفر **مجموعة البيانات** أو **البيئة** لديك الملاحظات تحت مجموعة واحدة من المفاتيح (مثل `observation.images.front`، `observation.images.eagle`)، بينما تتوقع **السياسة** لديك مجموعة أخرى (مثل `observation.images.image`، `observation.images.image2`). يعمل **خريطة إعادة التسمية** على سد هذه الفجوة دون تغيير السياسة أو مصدر البيانات.

> **النطاق:** يعيد خريطة إعادة التسمية تسمية مفاتيح **observation** (الصور والحالة) فقط. لا تتأثر مفاتيح الإجراء.

## لماذا لا تتطابق مفاتيح الملاحظات دائمًا

تحتوي السياسات على مجموعة ثابتة من **أسماء ميزات الإدخال** مدمجة في إعدادها المسبق التدريب. على سبيل المثال:

- يتوقع [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero) `observation.images.base_0_rgb` و`observation.images.left_wrist_0_rgb`.
- يتوقع [xvla-base](https://huggingface.co/lerobot/xvla-base) `observation.images.image` و`observation.images.image2` و`observation.images.image3`.

قد يستخدم مجموعة بياناتك أسماء مختلفة تمامًا (مثل `observation.images.front`، `observation.images.eagle`، `observation.images.glove`)، وقد يستخدم بيئة التقييم لديك مجموعة أخرى من الأسماء. وبدلًا من تعديل إعدادات السياسة أو إعادة تسمية الأعمدة في مجموعة البيانات، تمرر **خريطة إعادة تسمية**: وهي قاموس JSON يربط المفاتيح المصدرية بالمفاتيح التي تتوقعها السياسة. وتتم إعادة التسمية داخل خط أنابيب المعالج المسبق، بحيث ترى السياسة دائمًا المفاتيح المتوقعة.

## استخدام خريطة إعادة التسمية

مرّر الترميز كسلسلة JSON في سطر الأوامر. القاعدة هي دائماً:

```
--rename_map='{"source_key": "policy_key", ...}'
```

حيث **source_key** هو ما يوفّره مجموعة البيانات أو البيئة، و**policy_key** هو ما يتوقعه السياسة.

تُعاد تسمية المفاتيح المدرجة فقط؛ بينما تبقى كل العناصر الأخرى دون تغيير. لا يهم ترتيب الإدخالات.

السياسات المدعومة: **PI0**، **PI05**، **PI0Fast**، **SmolVLA**، و**XVLA**.

### التدريب

لنفترض أنك قمت بضبط [lerobot/xvla-base](https://huggingface.co/lerobot/xvla-base) على مجموعة بيانات تحتوي على صور تحت `observation.images.front` و`observation.images.eagle` و`observation.images.glove`. يتوقع XVLA وجود `observation.images.image` و`observation.images.image2` و`observation.images.image3`:

```bash
lerobot-train \
  --dataset.repo_id=YOUR_DATASET \
  --output_dir=./outputs/xvla_training \
  --job_name=xvla_training \
  --policy.path="lerobot/xvla-base" \
  --policy.repo_id="HF_USER/xvla-your-robot" \
  --policy.dtype=bfloat16 \
  --policy.action_mode=auto \
  --steps=20000 \
  --policy.device=cuda \
  --policy.freeze_vision_encoder=false \
  --policy.freeze_language_encoder=false \
  --policy.train_policy_transformer=true \
  --policy.train_soft_prompts=true \
  --rename_map='{"observation.images.front": "observation.images.image", "observation.images.eagle": "observation.images.image2", "observation.images.glove": "observation.images.image3"}'
```

### التقييم

سياسة تتوقع `observation.images.base_0_rgb` و`observation.images.left_wrist_0_rgb` (مثل [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero))، لكن بيئة LIBERO تُرجع `observation.images.image` و`observation.images.image2`:

```bash
lerobot-eval \
  --policy.path=lerobot/pi0fast-libero \
  --env.type=libero \
  ... \
  --rename_map='{"observation.images.image": "observation.images.base_0_rgb", "observation.images.image2": "observation.images.left_wrist_0_rgb"}'
```

## بديل: تحرير إعدادات السياسة مباشرة

إذا كنت تستخدم دائمًا مجموعة بيانات أو بيئة واحدة، يمكنك **تعديل ملف `config.json` الخاص بالسياسة** بحيث تتطابق مفاتيح الملاحظات مع مصدر بياناتك. في هذه الحالة، لن تكون بحاجة إلى خريطة إعادة تسمية.

المفاضلة: تعديل إعدادات السياسة يربطها بمصدر بيانات واحد. أما خريطة إعادة التسمية فتُبقي سياسة واحدة قابلة للاستخدام عبر مجموعات بيانات وبيئات متعددة.

## كاميرات فارغة: عدد أقل من الزوايا مما تتوقعه السياسة

بعض السياسات مصممة لعدد ثابت من مدخلات الصور. إذا كان لديك عدد أقل من الكاميرات في مجموعة البيانات، يمكنك تعيين **`empty_cameras`** في إعدادات السياسة بدلاً من تعديل بنية النموذج.

### كيف يعمل

إعداد `empty_cameras=N` يضيف N ميزات صور وهمية إلى إعدادات السياسة، وتُسمّى:

```
observation.images.empty_camera_0
observation.images.empty_camera_1
...
```

عند التشغيل، لا توجد بيانات مقابلة لهذه المفاتيح في الدفعة. تقوم السياسة بملئها بمصفوفات وهمية مقنّعة (مُعبّأة بـ`-1` لمشفّرات الرؤية القائمة على SigLIP، مع قناع انتباه صفري)، بحيث تُهمل فتحات الصور الإضافية فعلياً أثناء التدريب والاستدلال.

### مثال

يتميز XVLA-base بثلاثة مدخلات بصرية، والقيمة الافتراضية لـ`empty_cameras=0`. يحتوي مجموعة بياناتك على كاميرتين فقط:

1. اضبط `--policy.empty_cameras=1`.
2. تضيف الإعدادات مفتاحًا ثالثًا: `observation.images.empty_camera_0`.
3. استخدم خريطة إعادة التسمية لكاميرتك الحقيقيتين كما هو معتاد.
4. الموضع الثالث مُقنَّع — لا حاجة إلى صور مزيفة في مجموعة البيانات الخاصة بك.

## مرجع سريع

| الهدف                                    | ما يجب فعله                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------- |
| مفاتيح مجموعة البيانات ≠ مفاتيح السياسة              | `--rename_map='{"dataset_key": "policy_key", ...}'`                         |
| مفاتيح Env ≠ مفاتيح السياسة (التقييم)           | `--rename_map='{"env_key": "policy_key", ...}'`                             |
| التنفيذ بمفاتيح مختلفة (الاستدلال) | `--rename_map='{"source_key": "policy_key", ...}'`.                         |
| عدد أقل من الكاميرات مما تتوقعه السياسة       | `--policy.empty_cameras=N` (مدعوم بواسطة PI0 وPI05 وPI0Fast وSmolVLA وXVLA) |
| تجنّب تمرير خريطة إعادة تسمية              | قم بتعديل `config.json` الخاص بسياسة العمل بحيث تتطابق مفاتيحه مع مصدر بياناتك          |