예제 소스

rl_config.py

"""
RL 설정을 한 곳에서 관리합니다.

사용 예)
  - 학습(헤드리스): python train_tetris_rl.py
  - 학습+Qt 라이브: python train_qt_live.py

필요하면 이 파일만 수정하세요.
"""

from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class EnvConfig:
    # C API 라이브러리 경로
    env_id: str = "tetris/build/libtetris_c_api.dylib"
    seed: int = 0

    # 매크로(블록당 1회 계획) 모드
    macro: bool = True

    # True: train_qt_live에서 env.step 학습은 끄고, 휴먼 플레이 전이만 리플레이 버퍼에 넣어 DQN 갱신
    # False: 기존처럼 DQN(ε 탐색 등)이 Qt 쪽에 액션 전송
    human_play_mode: bool = False

    # ── 보상/패널티 스케일 (C++ 엔진으로 전달) ───────────────────────────────
    # 한쪽으로 몰빵되는 탑쌓기를 억제하려면 아래 2개를 켜는 게 효과적
    stack_height_penalty_scale: float = 2.0   # 스택 높이 "증가분" 패널티 (권장 0.5~5.0)
    # bumpiness는 값 범위가 커서(최대 수백) 스케일을 너무 크게 주면 보상이 붕괴합니다.
    bumpiness_penalty_scale: float = 0.02     # 인접 열 높이 차이 합 패널티 (권장 0.005~0.05)
    max_height_penalty_scale: float = 0.03    # 절대 스택 높이 패널티 (권장 0.0~0.1)


@dataclass(frozen=True)
class DQNConfig:
    timesteps: int = 300_000
    learning_rate: float = 1e-4
    buffer_size: int = 100_000
    batch_size: int = 32
    train_freq: int = 4
    target_update_interval: int = 10_000
    exploration_fraction: float = 0.2
    exploration_final_eps: float = 0.02


@dataclass(frozen=True)
class LLMRewardConfig:
    enabled: bool = True
    backend: str = "qwen2_5_vl"
    # gguf backend
    model_path: str = "llms/qwen2.5-3b-instruct-q4_k_m.gguf"
    # vlm backend (local HF dir)
    vlm_model_dir: str = "llms/Qwen2.5-VL-3B-Instruct"
    alpha: float = 0.2
    call_every: int = 10
    n_ctx: int = 2048
    n_threads: int = 8
    n_gpu_layers: int = 0
    temperature: float = 0.0
    top_p: float = 0.9
    max_tokens: int = 128
    vlm_cell_px: int = 20


@dataclass(frozen=True)
class ModelIOConfig:
    model_dir: str = "model"
    # train_tetris_rl.py에서 기본 저장 파일명: <model_dir>/<fixed_model_name>.zip
    fixed_model_name: str = "live_latest"
    # 이어학습(없으면 None)
    load_model: str | None = "model/live_latest.zip"

@dataclass(frozen=True)
class QtConfig:
    host: str = "127.0.0.1"
    port: int = 5555
    connect_timeout: float = 20.0
    deterministic: bool = True

@dataclass(frozen=True)
class LiveConfig:
    # 학습 중 주기적으로 live_latest 저장
    checkpoint_freq: int = 10_000
    # 시각화 루프에서 N 스텝마다 모델 리로드 확인
    reload_every: int = 100

@dataclass(frozen=True)
class RLConfig:
    env: EnvConfig = EnvConfig()
    dqn: DQNConfig = DQNConfig()
    llm_reward: LLMRewardConfig = LLMRewardConfig()
    io: ModelIOConfig = ModelIOConfig()
    qt: QtConfig = QtConfig()
    live: LiveConfig = LiveConfig()

# 스크립트들이 기본으로 사용하는 설정 인스턴스
CONFIG = RLConfig()