DeepLabyrinth 🧠🤖

DeepLabyrinth là một môi trường mô phỏng và huấn luyện Reinforcement Learning (Học tăng cường) dựa trên thuật toán giải quyết mê cung. Dự án tập trung vào việc tạo ra một tác tử (agent) thông minh có khả năng định vị, khám phá và tìm đường đi tối ưu trong các môi trường mê cung quy mô lớn và phức tạp.

🌟 Tính năng nổi bật

• Kiến trúc mô hình nâng cao: Tích hợp bộ trích xuất đặc trưng ResNet kết hợp với CoordConv và hàm kích hoạt SiLU, giúp tăng cường nhận thức không gian cho tác tử.
• Tích hợp Attention: Sử dụng Goal-Conditioned Cross-Attention để giúp mô hình tập trung vào các đặc trưng không gian liên quan đến mục tiêu.
• Bộ nhớ dài hạn (LSTM): Sử dụng mạng LSTM 2 lớp (512 units) giúp lưu giữ chuỗi hành động và vượt qua các mê cung đòi hỏi tầm nhìn dài hạn.
• Random Network Distillation (RND): Tích hợp RND để giải quyết bài toán phần thưởng thưa thớt (sparse reward) bằng cách khuyến khích tác tử khám phá những khu vực mới trong mê cung.
• Giao diện giám sát đồ họa (UI): Hệ thống Dashboard thời gian thực, bảng điều khiển và hiển thị mô phỏng được xây dựng bằng Dear PyGui giúp dễ dàng theo dõi hiệu suất huấn luyện và các số liệu khám phá của tác tử.
• Tài liệu dự án với MkDocs: Hệ thống tài liệu nội bộ phong phú tự động hóa bằng cấu trúc mkdocs.
• Quản lý siêu tham số tối ưu: Sử dụng optuna để tối ưu cấu hình huấn luyện (Hyperparameter Optimization - HPO).

📂 Cấu trúc thư mục

DeepLabyrinth/
│
├── docs/                   # Tài liệu dự án dành cho MkDocs
├── logs/                   # Chứa lịch sử huấn luyện (Tensorboard, logs hệ thống)
├── src/                    # Mã nguồn chính của dự án
│   ├── core/               # Các module cốt lõi
│   ├── env/                # Môi trường Gym(nasium) mô phỏng mê cung
│   ├── rl/                 # Mô hình Học tăng cường (PPO, RND, LSTM, Feature Extractors)
│   ├── ui/                 # Giao diện giám sát Dear PyGui (States, Windows, Theme)
│   └── utils/              # Các công cụ hỗ trợ và tiện ích
│
├── tests/                  # Unit tests cho các module dự án
├── config.yaml             # Tệp cấu hình tổng thể (Env, Agent, Training, Reward)
├── main.py                 # Entry point khởi chạy giao diện ứng dụng chính
├── mkdocs.yml              # Tệp cấu hình giao diện tài liệu MkDocs
└── requirements_rl.txt     # Danh sách các thư viện Python phụ thuộc

🚀 Cài đặt và thiết lập

1. Yêu cầu hệ thống:

   • Python >= 3.9
   • Hệ điều hành: Windows, Linux hoặc macOS. (Dự án đã được tối ưu hiển thị DPI trên Windows).

2. Cài đặt môi trường ảo (Khuyến nghị):

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # Linux/macOS:
   source .venv/bin/activate

3. Cài đặt các gói phụ thuộc: Dự án sử dụng file requirements_rl.txt. Nếu bạn có GPU NVIDIA, hãy cài đặt bản PyTorch hỗ trợ CUDA để tăng tốc độ huấn luyện gấp 10-20 lần.

   Dành cho Python 3.13 + GPU NVIDIA:

   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu132 --force-reinstall
   pip install -r requirements_rl.txt

   Dành cho CPU hoặc Python cũ hơn:

   pip install -r requirements_rl.txt

⚙️ Cấu hình hệ thống (config.yaml)

Dự án cung cấp bộ tham số tùy chỉnh mạnh mẽ thông qua config.yaml, bao gồm:

• Tác tử (agent): Kích thước tầm nhìn, cấu trúc lưới...
• Môi trường (env): Kích thước mê cung (chiều rộng/chiều cao), số bước đi tối đa, thuật toán sinh mê cung.
• Huấn luyện (training): Tốc độ học (learning rate), quy mô batch, thuật toán PPO, LSTM, v.v. (Đã được tối ưu từ các thử nghiệm Optuna).
• Phần thưởng (reward): Điểm khi tới đích, phạt từng bước đi, thưởng khi khám phá, trọng số RND intrinsic.

🏃 Thao tác chạy

Để khởi chạy giao diện quản lý và mô phỏng của hệ thống (Main Menu):

python main.py

Giao diện Dear PyGui sẽ hiển thị để bạn thực hiện Huấn luyện mô hình, Quan sát (Replay), Đánh giá hiệu suất, hoặc tinh chỉnh cấu hình mà không cần phải can thiệp trực tiếp vào mã nguồn.

🧪 Tối ưu hóa siêu tham số (Optuna)

DeepLabyrinth tích hợp Optuna để tự động tìm kiếm bộ tham số tối ưu (Hyperparameter Tuning). Quá trình này giúp cải thiện đáng kể khả năng hội tụ và hiệu suất cuối cùng của tác tử.

Cách chạy tuning:

# Chạy tuning với 100 lượt thử nghiệm, sử dụng 3 luồng song song
python -m src.rl.tune --trials 100 --jobs 3

Giải thích tham số:

• --trials (Tổng số lượt thử): Đây là tổng số bộ tham số mà AI sẽ thử nghiệm. Ví dụ: --trials 100 nghĩa là AI sẽ thử 100 cách thiết lập khác nhau để tìm ra bộ tốt nhất. Càng nhiều trials, kết quả càng chính xác nhưng thời gian chạy càng lâu.
• --jobs (Số lượng chạy song song): Cho phép chạy nhiều lượt thử nghiệm cùng một lúc để tận dụng CPU đa nhân.
  • Khuyến nghị: Nên để bằng Số nhân thực / 2. Ví dụ CPU 8 nhân thì nên để --jobs 3 hoặc 4 để máy vẫn hoạt động mượt mà.

Cơ chế hoạt động:

• Đa độ khó (Multi-scale): Đánh giá trên nhiều kích thước mê cung (8x8, 15x15, 20x15) để đảm bảo tính tổng quát.
• Lưu trữ: Kết quả được lưu vào optuna_study.db (SQLite). Có thể dừng và resume bất cứ lúc nào.
• Kết quả: Bộ tham số tốt nhất sẽ xuất ra tại logs/optuna/best_hyperparams.yaml.

📊 Xem kết quả trực quan (Optuna Dashboard)

Để phân tích chi tiết quá trình tuning, xem biểu đồ hội tụ và tầm quan trọng của các tham số qua giao diện Web:

1. Cài đặt dashboard:

   pip install optuna-dashboard

2. Chạy dashboard:

   optuna-dashboard sqlite:///optuna_study.db

3. Truy cập địa chỉ http://127.0.0.1:8080 trên trình duyệt để bắt đầu phân tích.

---

🏋️ Huấn luyện và Đánh giá

1. Huấn luyện (Training)

Có thể chạy từ giao diện hoặc script:

python -m src.rl.train

• Curriculum Learning: Tự động tăng độ khó từ 3x3 lên các cấp độ cao hơn dựa trên hiệu suất.
• Random Network Distillation (RND): Khuyến khích agent khám phá các khu vực lạ thông qua phần thưởng nội sinh (intrinsic rewards).

2. Đánh giá (Evaluation)

python -m src.rl.evaluate

Kiểm tra Success Rate, Efficiency Ratio (so với đường đi ngắn nhất BFS), và Exploration Coverage.

3. So sánh (Benchmarking)

Mở mục Benchmark trong UI để so sánh trực quan các agent:

• Chạy song song nhiều model trên cùng một seed mê cung.
• Hiển thị Dashboard so sánh realtime và xem lại "cuốn băng" hành động.

---

📊 Giám sát và Log

• Tensorboard: Xem chi tiết Loss, Reward, Entropy:

  tensorboard --logdir logs/tb_logs

• Dashboard Dashboard: Theo dõi trực quan Vision, Policy Probabilities, và Hardware Stats (CPU/GPU) ngay khi đang train.

📚 Tài liệu chi tiết (MkDocs)

Để xem tài liệu API và luồng logic chi tiết:

# Cài đặt mkdocs-material nếu chưa có
pip install mkdocs-material

# Chạy server tài liệu
mkdocs serve

🛠️ Cập nhật & Tối ưu gần đây

Dự án được duy trì liên tục với các cải tiến:

• Tối ưu ResNet/Attention & CoordConv.
• Hệ thống Reward V4: Loại bỏ Hard Clipping và tối ưu Distance Shaping (PBRS) giúp AI thoát khỏi bẫy cục bộ.
• Hỗ trợ GPU Acceleration (CUDA 13.2) cho Python 3.13.
• Hệ thống chống rò rỉ bộ nhớ (memory leak protection).
• Dashboard UI hỗ trợ native scrolling và layout thích ứng.