實驗管理

研究的核心是「比較不同設定下的結果」。沒有好的實驗管理，很容易發生「這個好結果是哪次跑的？用什麼參數？」的情況。

---

核心原則

提交程式碼後再跑實驗

每次正式實驗前，先 git commit 你的程式碼。這讓你能用 Git Hash 精確定位「這個結果是哪版程式碼產生的」。

# 確認目前的 commit hash
git log --oneline -1
# 例如：a1b2c3d feat: Add attention to policy

---

1. 用設定檔管理超參數

不要在程式碼裡硬編碼超參數，改用 configs/ 目錄的 YAML 檔：

# configs/ppo_humanoid.yaml
seed: 42
env:
  name: "HumanoidStand-v1"
  max_steps: 1000

agent:
  lr: 3e-4
  gamma: 0.99
  clip_ratio: 0.2
  batch_size: 64

logging:
  save_dir: "data/checkpoints"
  log_interval: 100

每次實驗換參數時，複製一份設定檔修改，而非直接改程式碼：

cp configs/ppo_humanoid.yaml configs/ppo_humanoid_lr1e4.yaml
# 修改 lr: 1e-4

---

2. Checkpoint 命名規範

儲存模型權重時，用能識別實驗身份的名稱：

[專案名]_[日期]_[關鍵指標].[副檔名]

實際範例：

humanoid_20240501_reward312.pt
humanoid_20240503_reward298.pt

在程式碼中自動生成：

import time
from pathlib import Path


def save_checkpoint(
    model: torch.nn.Module,
    reward: float,
    save_dir: str,
    project_name: str,
) -> Path:
    """Save model checkpoint with timestamped filename."""
    save_dir = Path(save_dir)
    save_dir.mkdir(parents=True, exist_ok=True)

    date_str = time.strftime("%Y%m%d")
    filename = f"{project_name}_{date_str}_reward{reward:.0f}.pt"
    path = save_dir / filename

    torch.save(model.state_dict(), path)
    return path

---

3. 在訓練時記錄關鍵資訊

每次實驗結束後，你應該能回答這些問題：

問題	記錄方式
用了哪個 commit 的程式碼？	logger 印出 git rev-parse HEAD
用了什麼超參數？	logger 印出完整 config
最好的結果在第幾個 epoch？	追蹤 best_reward
Checkpoint 存在哪裡？	logger 印出完整路徑

import subprocess
from your_project.utils.logger import get_logger

logger = get_logger(__name__)


def log_experiment_info(config: dict) -> None:
    """Log experiment metadata at the start of training."""
    git_hash = subprocess.check_output(
        ["git", "rev-parse", "--short", "HEAD"]
    ).decode().strip()

    logger.info("=" * 50)
    logger.info("Git commit: %s", git_hash)
    logger.info("Config: %s", config)
    logger.info("=" * 50)

---

4. 整理實驗結果

建議在專案的 docs/experiment_log.md 中維護一個實驗結果表，不要直接寫在 README.md，保持 README 簡潔：

# 實驗記錄

| 日期 | Commit | 設定檔 | 最高 Reward | 備註 |
|---|---|---|---|---|
| 2024-05-01 | `a1b2c3d` | ppo_humanoid.yaml | 312 | baseline |
| 2024-05-03 | `e4f5g6h` | ppo_humanoid_lr1e4.yaml | 298 | lr 太小 |
| 2024-05-05 | `i7j8k9l` | ppo_attention.yaml | 341 | attention ✅ |

在 README.md 中只需加一行連結即可：

實驗記錄請見 [docs/experiment_log.md](docs/experiment_log.md)。

---

5. 實驗量大時：考慮自動追蹤工具

手動維護 Markdown 表格在實驗量少時夠用，但當你一天要跑 10+ 次實驗時，容易漏記。以下工具可以自動記錄每次訓練的超參數、指標與程式碼版本：

工具	適合情況	入門難度
Weights & Biases (W&B)	需要視覺化儀表板、遠端監控訓練曲線	★★☆
MLflow	偏好本地部署、不想依賴外部服務	★★☆

W&B 的最小接入範例（只需三行）：

import wandb

wandb.init(project="humanoid_rl", config=cfg)
# 在訓練迴圈中
wandb.log({"epoch": epoch, "reward": reward, "loss": loss})

Note

實驗量不大時，手動 Markdown 表格完全夠用。只在你覺得「每次都要手動填表很麻煩」的時候才引入這類工具。

---

6. 伺服器執行時的注意事項

在伺服器上執行長時間訓練時，建議使用 tmux 管理 session，讓訓練在登出後繼續執行。

# 建立一個新的 session（取個好記的名字）
tmux new -s train

# 在 session 中啟動訓練
python -m your_project.training.train --config configs/ppo_humanoid.yaml

# 需要離開時：按下 Ctrl+B，放開，再按 D
# 程式會繼續在背景跑

# 之後重新連回 session
tmux attach -t train

# 列出目前所有 session
tmux ls

還沒安裝 tmux？

伺服器通常沒有 sudo 權限，請參考 → tmux 無 sudo 安裝教學

---

下一步 → 研究可重現性