Chuyển đến nội dung chính
Hướng dẫn AI

Điều khiển Super Mario Bros. bằng TypeSafe Jev và dữ liệu giám sát trình giả lập có cấu trúc

Tìm hiểu cách TypeSafe Mario chuyển dữ liệu giám sát trình giả lập và RAM thành JSON có cấu trúc cho Jev, sau đó biến lựa chọn của mô hình thành lệnh điều khiển NES. Hướng dẫn này bao gồm các yêu cầu, cài đặt, kiểm tra trạng thái, chơi game, chế độ hiển thị, tệp kết quả chạy, phán đoán của mô hình và kiểm tra phát triển.

Thời gian đọc khoảng 19 phút
Điều khiển Super Mario Bros. bằng TypeSafe Jev và dữ liệu trình giả lập có cấu trúc

TypeSafe Mario Hoạt Động Như Thế Nào

TypeSafe Mario là một bộ điều khiển thử nghiệm, cho phép mô hình Jev của TypeSafe lựa chọn các đầu vào điều khiển cho Super Mario Bros. bản gốc. Thay vì nhận ảnh chụp màn hình, mô hình nhận JSON nhỏ gọn, tập trung vào các đối tượng, được tạo từ dữ liệu telemetry của trình giả lập và RAM.

Vòng lặp điều khiển tuân theo kiến trúc sau:

Trình giả lập NES -> bộ phân tích telemetry/RAM -> JSON có cấu trúc -> Jev Choice -> đầu vào điều khiển

Sau khi Jev chọn một hành động hợp lệ, trình giả lập tiến thêm vài khung hình và tạo ra trạng thái mới. Quy trình này lặp lại trong suốt mỗi episode. Lưới ô thô cục bộ vẫn có trong nhật ký gỡ lỗi và bảng điều khiển, nhưng không được lặp lại trong đầu vào dành cho mô hình.

Các hành động điều khiển khả dụng

Không gian hành động ban đầu được giới hạn có chủ đích ở bảy macro điều khiển:

  • noop
  • right
  • right_jump
  • right_run
  • right_run_jump
  • jump
  • left

Tính Năng Chính

  • Đầu vào có cấu trúc cho mô hình: Bộ phân tích gửi cho TypeSafe các đối tượng JSON có ý nghĩa thay vì văn bản dạng phẳng hoặc ảnh chụp màn hình.
  • Nhiều phán đoán: Mỗi yêu cầu đánh giá lựa chọn điều khiển, mức hữu ích của cú nhảy về phía trước và mối nguy hiểm tức thời.
  • Đo thời gian phản ứng: Trạng thái bao gồm thời lượng hành động và độ trễ từ quan sát đến hành động.
  • Bảng điều khiển trực tiếp: Màn hình mặc định kết hợp gameplay với xác suất hành động, độ tin cậy, độ trễ, mối nguy hiểm, phần thưởng và trạng thái đã phân tích.
  • Bản ghi lần chạy chi tiết: Mọi quyết định được lưu dưới dạng bản ghi JSON Lines để phân tích hoặc trực quan hóa sau này.
  • Khả năng quan sát khi gỡ lỗi: Văn bản trạng thái dễ đọc và lưới ô cục bộ vẫn có sẵn để kiểm tra.

Yêu Cầu và Thiết Lập Hợp Pháp

Trước khi cài đặt dự án, hãy đảm bảo môi trường của bạn đáp ứng các yêu cầu sau:

  • Python 3.13 hoặc mới hơn
  • Khóa API TypeSafe được lưu trong TYPESAFE_API_KEY
  • Thiết lập cục bộ hợp pháp cho Super Mario Bros.

Kho lưu trữ không chứa ROM Nintendo hay dữ liệu trò chơi có bản quyền khác. Bạn chịu trách nhiệm tự الحصول và sử dụng trình giả lập cùng các tệp trò chơi một cách hợp pháp.

Cài Đặt

README cung cấp các lệnh PowerShell để tạo môi trường ảo, cài đặt các phần phụ thuộc của Mario và phần phát triển, cũng như cấu hình khóa API.

  1. Tạo môi trường ảo Python 3.13.
  2. Cài đặt dự án ở chế độ editable cùng các phần bổ sung bắt buộc.
  3. Thiết lập khóa API TypeSafe cho phiên PowerShell hiện tại.
py -3.13 -m venv .venv
.venv\Scripts\python -m pip install -e ".[mario,dev]"
$env:TYPESAFE_API_KEY = "your-key"

Thay your-key bằng khóa API TypeSafe thực tế của bạn. Vì lệnh này thiết lập một biến môi trường PowerShell, hãy chạy các lệnh tiếp theo từ cùng môi trường đã cấu hình, trừ khi bạn lưu biến này lâu dài theo cách riêng.

Kiểm Tra Đầu Vào Của Mô Hình Trước

Trước khi khởi chạy trò chơi, hãy dùng state-demo để kiểm tra chính xác JSON và văn bản mà dự án sẽ gửi cho TypeSafe:

.venv\Scripts\typesafe-mario state-demo

Lệnh này không khởi chạy trò chơi và không gọi API. Đây là cách an toàn nhất để hiểu schema dành cho mô hình và xác minh cách các quan sát từ trình giả lập được biểu diễn.

Tìm hiểu trạng thái có cấu trúc

Đối tượng chuẩn nhóm các quan sát theo mục đích:

  • player: Vị trí, vận tốc, trạng thái chạm đất, giai đoạn nhảy và vật phẩm tăng sức mạnh.
  • trajectory: Thời gian trên không, khoảng cách kể từ lúc cất cánh và việc Mario có đang cam kết vượt qua khoảng trống hay không.
  • hazard: Tối đa ba kẻ địch, vị trí dự kiến của chúng, thời điểm dự kiến va chạm và hạn chót cất cánh.
  • terrain: Hình học của chướng ngại vật và khoảng trống, độ tin cậy của quan sát và bản xem trước lần chạm đất gần nhất.
  • reaction_timing: Thời lượng hành động điều khiển và độ trễ đo được từ quan sát đến hành động.
  • recent_control: Hành động trước đó, thời lượng, tiến độ đạt được và kết quả quan sát được.
  • episode: Số mạng, đồng hồ, tiến độ, số lần bị kẹt, trạng thái chết và mức hoàn thành màn chơi.

JSON có cấu trúc là trạng thái chuẩn của mô hình. Bản kết xuất văn bản đầy đủ hơn chỉ tồn tại để gỡ lỗi và phục vụ giao diện người dùng. Một ảnh chụp nhanh gỡ lỗi có thể bao gồm tọa độ và chuyển động của Mario, tiến độ episode, các kẻ địch gần đó và lưới ô cục bộ dựa trên ký tự.

Chạy World 1-1

Khởi động môi trường World 1-1 và để Jev chọn một hành động sau mỗi tám bước của trình giả lập:

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8

Tùy chọn --env chọn môi trường, còn --frames-per-decision 8 xác định số bước của trình giả lập diễn ra giữa các lần mô hình đưa ra quyết định. Với màn hình mặc định, dự án mở một cửa sổ có thể ghi lại, chứa cả trò chơi trực tiếp và telemetry của mô hình.

Sử dụng bảng điều khiển

Bảng điều khiển hiển thị những thông tin cần thiết để theo dõi hành vi của Jev:

  • Hành động điều khiển được chọn
  • Phân phối xác suất Choice đầy đủ
  • Độ tin cậy của mô hình
  • Độ trễ yêu cầu Jev
  • Xác suất nhảy về phía trước
  • Điểm mối nguy hiểm tức thời
  • Phần thưởng
  • Trạng thái trò chơi đã phân tích

Nhấn R hoặc nhấp vào Restart để bắt đầu một lượt chơi mới. Bảng điều khiển vẫn mở sau khi Mario chết hoặc hoàn thành màn chơi. Nhấn Esc hoặc Q để thoát.

Chọn chế độ hiển thị

Bảng điều khiển kết hợp mặc định hữu ích khi theo dõi hoặc ghi lại một lượt chơi. Hai chế độ bổ sung hỗ trợ các nhu cầu sử dụng chuyên biệt hơn.

Chỉ hiển thị trình giả lập

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display game

Chế độ hiển thị game chỉ hiển thị cửa sổ trình giả lập.

Chạy mà không hiển thị

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display none

Chế độ hiển thị none chạy không cần giao diện và dành cho việc thực thi theo kiểu kiểm thử chuẩn.

Tìm hiểu ba phán đoán TypeSafe

Mỗi yêu cầu đánh giá ba phán đoán độc lập trên cùng một trạng thái có cấu trúc:

  • Choice: Chọn macro điều khiển hợp lệ tiếp theo.
  • Noul: Ước tính liệu một cú nhảy về phía trước có hữu ích tại thời điểm hiện tại hay không.
  • Score: Đo mức độ nguy hiểm tức thời cho phần trực quan hóa trực tiếp.

Ba phán đoán này có vai trò riêng biệt. Kết quả Choice điều khiển Mario, còn ước tính cú nhảy và điểm nguy hiểm cung cấp thêm thông tin diễn giải và trực quan hóa.

Các phép tính thời gian chính xác vẫn nằm trong mã nguồn. Ví dụ, trình phân tích kết hợp độ trễ phản hồi, chuyển động của kẻ địch, nhịp hành động và thời gian dọn khoảng trống khi nhảy thành một dữ kiện có kiểu jump_must_start_this_decision. Jev diễn giải dữ kiện đó và vẫn chịu trách nhiệm chọn hành động điều khiển; bộ khung không áp dụng ghi đè hành động khôi phục theo kịch bản.

Kiểm tra các quyết định đã ghi

Mỗi quyết định được ghi vào một tệp JSON Lines có dấu thời gian:

artifacts/run-<timestamp>.jsonl

Các bản ghi bao gồm:

  • Độ trễ của Jev
  • Xác suất hành động
  • Độ tin cậy
  • Trạng thái mô hình chuẩn
  • Trạng thái gỡ lỗi thô
  • Kết quả trò chơi

Các bản ghi này cung cấp dữ liệu cần thiết để kiểm tra một lượt chơi sau khi thực thi. Chúng cũng có thể được dùng làm đầu vào cho lớp phủ trực tiếp hoặc video mạng xã hội đã dựng.

Mẹo sử dụng nâng cao

Xác thực quan sát trước khi chơi

Chạy state-demo trước một phiên chơi trực tiếp khi bạn muốn xem lại biểu diễn hướng đến mô hình mà không khởi động trình giả lập hoặc sử dụng một lệnh gọi API. Đặc biệt chú ý đến sự phân tách giữa trạng thái có cấu trúc chuẩn và văn bản gỡ lỗi hướng đến con người.

Diễn giải dữ kiện thời gian cùng nhịp hành động

Bộ điều khiển hoạt động theo các khoảng nhiều khung hình, vì vậy thời gian phản ứng là một phần của trạng thái thay vì một giả định bên ngoài. Khi xem lại một quyết định, hãy so sánh hành động được chọn với độ trễ phản hồi, thời lượng hành động, thời điểm dự kiến va chạm với kẻ địch và mọi hạn chót cất cánh do trình phân tích báo cáo.

Sử dụng chế độ hiển thị phù hợp với tác vụ

  • Dùng bảng điều khiển mặc định khi kiểm tra đồng thời các tín hiệu suy luận của mô hình và diễn biến trò chơi.
  • Dùng --display game khi chỉ cần đầu ra của trình giả lập.
  • Dùng --display none cho các lượt kiểm thử chuẩn không giao diện.

Phân tích toàn bộ phân phối xác suất

Đừng chỉ giới hạn phân tích ở hành động được chọn. Bảng điều khiển và các tệp JSONL bao gồm toàn bộ phân phối xác suất Choice cùng độ tin cậy, qua đó cho biết Jev có ưu tiên rõ rệt một hành động hay chọn giữa nhiều phương án có trọng số tương đương.

Chạy các kiểm tra phát triển

Kho lưu trữ bao gồm các lệnh định dạng, lint và kiểm thử dành cho cộng tác viên. Hãy chạy chúng từ môi trường ảo đã cấu hình:

.venv\Scripts\ruff format --check src tests
.venv\Scripts\ruff check src tests
.venv\Scripts\python -m pytest -q

Lệnh đầu tiên kiểm tra định dạng, lệnh thứ hai chạy các kiểm tra lint của Ruff, còn lệnh thứ ba thực thi bộ kiểm thử với đầu ra ngắn gọn.

Kết luận

TypeSafe Mario minh họa một phương án có cấu trúc thay thế cho việc điều khiển trò chơi dựa trên ảnh chụp màn hình. Công cụ chuyển dữ liệu đo từ trình giả lập và RAM thành JSON chuẩn lấy đối tượng làm trung tâm, yêu cầu Jev chọn từ một tập hợp nhỏ các hành động hợp lệ, đồng thời ghi lại mọi quyết định để kiểm tra trực tiếp hoặc phân tích sau này. Hãy bắt đầu với state-demo, chạy Thế giới 1-1 qua bảng điều khiển và sử dụng các tệp JSONL được tạo ra để hiểu mối quan hệ giữa trạng thái, thời gian, độ tin cậy và kết quả.