rl-atari/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概览

西交利物浦大学（XJTLU）课程作业仓库，包含三个独立子项目：

子目录	课程	任务	算法
CW1_id_name/	DTS307TC RL	CarRacing-v3 自动驾驶	PPO（从零实现）
强化学习个人项目报告（Atari 游戏方向）/	DTS307TC RL	Space Invaders 游戏	DQN / Double DQN / Dueling
强化学习个人课程作业报告/	DTS304TC ML	健康保险保费风险预测	XGBoost + Optuna 调参

Python 环境

• 默认环境: D:\ProgramData\anaconda3\envs\my_env
• 包管理器: uv（位置: D:\settings\uv）
• GPU: RTX 4060 Laptop, CUDA 12.1, PyTorch 2.4.0+cu121
• 安装依赖时必须指定 Python 路径，避免库装到用户目录

常用命令

CW1 - PPO CarRacing

# 安装依赖（注意 box2d 编译问题，Windows 下可能需要先装 swig）
pip install -r CW1_id_name/requirements.txt

# 向量化训练（推荐）
python CW1_id_name/train_vec.py --n-envs 4 --total-steps 500000 --run-name vec_main --anneal-lr --anneal-ent --reward-clip 1.0

# 评估
python CW1_id_name/evaluate.py --ckpt CW1_id_name/models/vec_main_v3/final.pt
python CW1_id_name/evaluate.py --ckpt CW1_id_name/models/vec_main_v3/final.pt --video  # 生成 demo.mp4

# TensorBoard 监控
tensorboard --logdir=CW1_id_name/runs --port=6006

Atari DQN

# 训练
python "强化学习个人项目报告（Atari 游戏方向）/train.py" --steps 2000000

# 评估 checkpoint
python "强化学习个人项目报告（Atari 游戏方向）/evaluate_checkpoints.py"

# 生成训练曲线图
python "强化学习个人项目报告（Atari 游戏方向）/generate_plots.py"

保险保费预测（ML 作业）

# 使用 uv 安装依赖
cd "强化学习个人课程作业报告"
uv pip install -r pyproject.toml

# 主 notebook
jupyter notebook "强化学习个人课程作业报告/notebooks/insurance_premium_risk.ipynb"

架构说明

CW1_id_name（PPO）

核心组件在 src/ 下，不依赖 Stable-Baselines3（SB3 仅用于外部 baseline 对比）：

• networks.py — 共享 CNN 的 ActorCritic 网络
• ppo_agent.py — PPO-Clip 智能体（act / update / lr schedule）
• vec_rollout_buffer.py — 向量化 rollout 缓冲区 + GAE
• vec_env_wrappers.py — AsyncVectorEnv 工厂
• env_wrappers.py — SkipFrame / GrayScaleResize / FrameStack
• eval_utils.py — 评估、绘图、录像

重要: train_vec.py 底部必须有 if __name__ == "__main__" 保护，否则 Windows 上 AsyncVectorEnv 会无限 spawn 子进程。

Atari DQN

核心组件在 强化学习个人项目报告（Atari 游戏方向）/src/ 下：

• network.py — QNetwork 和 DuelingQNetwork
• agent.py — DQN 智能体（ε-greedy + Double DQN）
• replay_buffer.py — 经验回放 + 优先经验回放（PER）
• trainer.py — 训练循环
• evaluate.py — 模型评估

保险保费预测

• 主逻辑在 notebooks/insurance_premium_risk.ipynb
• src/ 下有 notebook_runner 和 runtime_paths 辅助模块
• 输出在 outputs/（figures / tables / predictions）

注意事项

• .gitignore 排除了 *.pt / *.pth 模型文件，但当前 git 中仍有已追踪的模型
• 训练日志（TensorBoard events）在 runs/ 目录下
• 代码注释使用中文