diff --git a/docs/source/zh/_toctree.yml b/docs/source/zh/_toctree.yml new file mode 100644 index 0000000000..cbd9e85cfe --- /dev/null +++ b/docs/source/zh/_toctree.yml @@ -0,0 +1,6 @@ +- sections: + - local: contributing + title: 為 LeRobot 做出貢獻 + - local: backwardcomp + title: 向下相容性 + title: "關於" diff --git a/docs/source/zh/backwardcomp.mdx b/docs/source/zh/backwardcomp.mdx new file mode 100644 index 0000000000..994c5db90e --- /dev/null +++ b/docs/source/zh/backwardcomp.mdx @@ -0,0 +1,151 @@ +# 向下相容性 + +## 策略正規化遷移(PR #1452) + +**重大變更**:LeRobot 策略的權重中不再內建正規化層。正規化現在由外部的 PolicyProcessorPipeline 元件負責處理。 + +### 有什麼改變? + +| 項目 | PR #1452 之前 | PR #1452 之後 | +| ------------------ | --------------------------------------- | ------------------------------------------------------------ | +| **正規化的位置** | 嵌入於模型權重中 (`normalize_inputs.*`) | 外部的 `PolicyProcessorPipeline` 元件 | +| **模型狀態的字典** | 包含正規化的統計資料 | **僅含乾淨的權重** — 不含正規化參數 | +| **使用方式** | `policy(batch)` 處理全部 | `preprocessor(batch)` → `policy(...)` → `postprocessor(...)` | + +### 對現有模型的影響 + +- 在 PR #1452 **之前**訓練的模型,其正規化已嵌入於權重中。 +- 這些模型需要進行遷移,才能與新的 `PolicyProcessorPipeline` 系統相容。 +- 此遷移會擷取正規化統計數據,並建立獨立的處理器管線。 + +### 遷移舊模型 + +使用遷移腳本將內嵌正規化的模型進行轉換: + +```shell +python src/lerobot/processor/migrate_policy_normalization.py \ + --pretrained-path lerobot/act_aloha_sim_transfer_cube_human \ + --push-to-hub \ + --branch migrated +``` + +此腳本將會: + +1. **提取**模型權重中的正規化統計數據 +2. **建立**外部預處理器與後處理器的管線 +3. **移除**模型權重中的正規化層 +4. **儲存**乾淨模型 + 處理器管線 +5. **推送**至 Hub 並自動建立 PR + +### 使用已遷移的模型 + +```python +# 新的使用方式(遷移後) +from lerobot.policies.factory import make_policy, make_pre_post_processors + +# 分別載入模型與處理器 +policy = make_policy(config, ds_meta=dataset.meta) +preprocessor, postprocessor = make_pre_post_processors( + policy_cfg=config, + dataset_stats=dataset.meta.stats +) + +# 透過管線處理資料 +processed_batch = preprocessor(raw_batch) +action = policy.select_action(processed_batch) +final_action = postprocessor(action) +``` + +## 硬體 API 重新設計 + +PR [#777](https://github.com/huggingface/lerobot/pull/777) 改善了 LeRobot 的校正功能,但**不向下相容**。以下概述了變更內容,以及如何繼續使用此 PR 之前所建立的資料集。 + +### 有什麼改變? + +| 項目 | PR #777 之前 | PR #777 之後 | +| ------------------------- | ----------------------------------- | ------------------------------------------------- | +| **關節範圍** | 角度 `-180...180°` | **正規化範圍** 關節:`–100...100` 夾爪:`0...100` | +| **零位(SO100 / SO101)** | 手臂完全水平伸展 | **位於各關節範圍的中點** | +| **邊界處理** | 以軟體防護機制偵測 ±180° 的跨越情形 | 因零位位於範圍中點,無需跨越邏輯 | + +--- + +### 對現有資料集的影響 + +- PR #777 **之前**所錄製的軌跡,若直接載入將無法正確重播: + - 關節角度產生偏移且正規化不正確。 +- 任何直接以舊資料進行微調或訓練的模型需對其輸入與輸出行轉換。 + +### 使用舊版校正系統建立的資料集 + +我們在此提供一個遷移範例腳本,用於重播以先前校正方式錄製的片段: `examples/backward_compatibility/replay.py`. +以下將帶您了解範例腳本中所進行的修改,以使先前校正的資料集能夠正常運作。 + +```diff ++ key = f"{name.removeprefix('main_')}.pos" + action[key] = action_array[i].item() ++ action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90) ++ action["elbow_flex.pos"] -= 90 +``` + +逐一說明如下。 +新版程式碼使用 `.pos` 後綴表示位置觀測值,並已移除 `main_` 前綴: + + +```python +key = f"{name.removeprefix('main_')}.pos" +``` + + +對於 `"shoulder_lift"`(id = 2),與舊版校正/程式碼相比,零位偏移了 -90 度,且方向相反。 + + +```python +action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90) +``` + + +對於 `"elbow_flex"`(id = 3),與舊版校正/程式碼相比,零位偏移了 -90 度。 + + +```python +action["elbow_flex.pos"] -= 90 +``` + + +若要使用角度正規化,請將 `--robot.use_degrees` 選項設為 `true`。 + +```diff +python examples/backward_compatibility/replay.py \ + --robot.type=so101_follower \ + --robot.port=/dev/tty.usbmodem5A460814411 \ + --robot.id=blue \ ++ --robot.use_degrees=true \ + --dataset.repo_id=my_dataset_id \ + --dataset.episode=0 +``` + +### 使用舊版校正系統訓練的政策 + +政策輸出的動作格式與資料集相同(`torch.Tensors`),因此應套用相同的轉換。 + +若要找出這些轉換,建議先依照上方說明,嘗試重播政策所訓練資料集中的某個片段。 +接著,在推論腳本中加入相同的轉換(以下以 `record.py` 腳本為例): + +```diff +action_values = predict_action( + observation_frame, + policy, + get_safe_torch_device(policy.config.device), + policy.config.use_amp, + task=single_task, + robot_type=robot.robot_type, + ) + action = {key: action_values[i].item() for i, key in enumerate(robot.action_features)} + ++ action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90) ++ action["elbow_flex.pos"] -= 90 + robot.send_action(action) +``` + +若有任何問題或在遷移過程中遇到困難,歡迎至 [Discord](https://discord.gg/s3KuuzsPFb) 上提問。 diff --git a/docs/source/zh/contributing.md b/docs/source/zh/contributing.md new file mode 100644 index 0000000000..10cbd461c8 --- /dev/null +++ b/docs/source/zh/contributing.md @@ -0,0 +1,83 @@ +# 如何為 🤗 LeRobot 做出貢獻 + +歡迎所有人貢獻,我們重視每個人的貢獻。撰寫程式碼並非協助社群的唯一方式。回答問題、協助他人、積極聯繫,以及改善文件說明,都是極具價值的貢獻。 + +無論您選擇以何種方式貢獻,請遵守我們的[行為準則](https://github.com/huggingface/lerobot/blob/main/CODE_OF_CONDUCT.md)與 [AI 政策](https://github.com/huggingface/lerobot/blob/main/AI_POLICY.md)。 + +## 貢獻方式 + +您可以透過多種方式做出貢獻: + +- **修復問題:** 解決錯誤或改善現有的程式碼。 +- **新功能:** 開發新功能。 +- **擴充:** 實作新的模型/策略、機器人或模擬環境,並將資料集上傳至 Hugging Face Hub。 +- **文件:** 改善範例、指南與文件字串。 +- **意見回饋:** 提交與錯誤或所需新功能相關的工單。 + +若您不確定從何開始,歡迎加入我們的 [Discord Channel](https://discord.gg/q8Dzzpym3f) 頻道。 + +## 開發環境設定 + +若要貢獻程式碼,您需要建立一個開發環境。 + +### 1. Fork 與 Clone + +在 GitHub 上 fork 儲存庫,然後 clone 您的 fork: + +```bash +git clone https://github.com//lerobot.git +cd lerobot +git remote add upstream https://github.com/huggingface/lerobot.git +``` + +### 2. 環境安裝 + +請參閱我們的[安裝指南](https://huggingface.co/docs/lerobot/installation),進行環境設定並以原始碼安裝。 + +## 執行測試 & 品質檢查 + +### 程式碼風格(Pre-commit) + +安裝 `pre-commit` hooks,以在提交前自動執行檢查: + +```bash +pre-commit install +``` + +若要對所有檔案手動執行檢查: + +```bash +pre-commit run --all-files +``` + +### 執行測試 + +我們使用 `pytest`。首先,請安裝 **git-lfs** 以確保您擁有測試所需的構件: + +```bash +git lfs install +git lfs pull +``` + +執行完整測試套件(可能需要安裝額外套件): + +```bash +pytest -sv ./tests +``` + +或在開發期間執行特定測試檔案: + +```bash +pytest -sv tests/test_specific_feature.py +``` + +## 提交 Issues & Pull Requests + +Use the templates for required fields and examples. + +- **Issues:** 請遵循 [工單模板](https://github.com/huggingface/lerobot/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml). +- **Pull requests:** 以 `upstream/main` 進行 Rebase,使用具描述性的分支名稱(請勿直接在 `main` 上工作),在本地端執行 `pre-commit` 與測試,並遵循 [PR 模板](https://github.com/huggingface/lerobot/blob/main/.github/PULL_REQUEST_TEMPLATE.md。 + +LeRobot 團隊的成員將審查您的貢獻。 + +感謝您為 LeRobot 做出貢獻!