게임 엔진에서 동작하는 강화학습 Toolkit - Unity ML Agent 테스트

소개

macOS 환경에서 Unity ML-Agents를 uv(Python 패키지 매니저)로 세팅하고, 강화학습 예제(3DBall)를 테스트해 본 사례입니다.

ML-Agents는 Unity 게임 환경에서 강화학습 에이전트를 훈련시킬 수 있는 오픈소스 툴킷 입니다. 공식 문서가 Conda 기준인데 uv 환경으로 변경해서 테스트를 진행하였습니다.

ALT

블루 스크린이 표시된 컴퓨터 화면의 스크린샷

전체 흐름

Python이 두뇌(신경망) 역할을, Unity가 몸(환경) 역할을 맡아 소켓으로 통신하며 학습하고, 완성된 모델(.onnx)을 Unity에 심으면 Python 없이도 AI가 독립 동작합니다.

ALT

다양한 유형의 무기를 사용하는 게임의 스크린샷

Unity ↔ Python 통신 구조

학습 중에는 Unity(환경)와 Python(신경망)이 소켓으로 관찰 → 행동 → 보상을 반복 교환합니다.

환경 정보

• macOS · Unity 6000.3.11f1 · Python 3.10.12

• ML-Agents Release 23 / v4.0.0 (2025-08-28 릴리즈)

• torch 2.2.1 · grpcio 1.78.0 · uv 패키지 매니저

진행 방법

1. 폴더 구조 설계

Python 학습 환경과 Unity 프로젝트를 분리하는 구조로 진행했습니다. mlagents-learn은 소켓 통신으로 Unity Editor와 연결되므로 두 폴더의 물리적 위치는 상관없습니다.

~/projects/
├── mlagents-trainer/          # Python 학습 환경 (uv 프로젝트)
│   ├── .venv/
│   ├── pyproject.toml
│   ├── config/                # ml-agents 저장소에서 복사한 설정
│   └── results/               # 학습 결과 저장
│
└── ml-agents/                 # ML-Agents 저장소 클론
    ├── Project/               # Unity Hub에서 이 폴더를 열기
    └── config/                # 원본 설정 파일

2. Python 환경 세팅 (uv)

uv로 프로젝트를 초기화하고, 의존성 충돌을 해결한 pyproject.toml을 작성했습니다.

mkdir ~/projects/mlagents-trainer && cd ~/projects/mlagents-trainer
uv init --python 3.10.12

핵심은 pyproject.toml 설정입니다. 여러 차례 시행착오 끝에 완성한 버전:

[project]
name = "mlagents-trainer"
version = "0.1.0"
description = "Unity ML-Agents training environment"
readme = "README.md"
requires-python = ">=3.10.1,<=3.10.12"
dependencies = [
  "mlagents==1.1.0",
  "setuptools<60",
  "torch>=2.2.1,<2.3",
]

[tool.uv]
override-dependencies = [
  "grpcio==1.78.0",
]

각 설정의 이유:

• setuptools<60 — 최신 버전에서 pkg_resources 분리로 런타임 오류 발생

• torch>=2.2.1,<2.3 — 최신 torch(2.10+)는 onnxscript 의존성 문제로 .onnx 저장 실패

• grpcio==1.78.0 override — mlagents가 요구하는 grpcio 1.48.2는 macOS에서 소스 빌드 불가. wheel이 제공되는 버전으로 강제 고정

설치 및 확인:

uv sync
source .venv/bin/activate
mlagents-learn --help   # 파라미터 목록 출력되면 설치 완료

3. Unity 프로젝트 설정

ML-Agents 저장소를 클론하고 Unity Hub에서 프로젝트를 열었습니다.

cd ~/projects
git clone --branch release_23 https://github.com/Unity-Technologies/ml-agents.git

Unity Hub → Open → ml-agents/Project 폴더 선택 → Unity 6000.0 이상 버전으로 열기.

config 폴더는 별도로 복사하여 원본을 건드리지 않고 독립적으로 관리:

cp -r ~/projects/ml-agents/config ~/projects/mlagents-trainer/

4. 3DBall 학습 실행

사전 학습 모델로 동작을 먼저 확인한 뒤, 신규 학습을 진행했습니다.

cd ~/projects/mlagents-trainer
source .venv/bin/activate
mlagents-learn config/ppo/3DBall.yaml --run-id=first3DBallRun

터미널에 "Start training by pressing the Play button in the Unity Editor" 메시지가 뜨면 Unity Editor에서 Play 클릭. 정상 학습 시 Mean Reward가 지속 상승합니다:

Step: 12000.  Mean Reward: 1.183
Step: 60000.  Mean Reward: 6.012
Step: 84000.  Mean Reward: 63.533
Step: 120000. Mean Reward: 100.000  ← 학습 완료

TensorBoard로 실시간 모니터링도 가능합니다:

tensorboard --logdir results
# localhost:6006 접속

5. 학습 모델 적용

학습 완료 후 .onnx 파일을 Unity 프로젝트로 복사하고, Inspector에서 모델 슬롯에 연결하면 끝입니다.

cp ~/projects/mlagents-trainer/results/first3DBallRun/3DBall.onnx \
   ~/projects/ml-agents/Project/Assets/ML-Agents/Examples/3DBall/TFModels/MyBall.onnx

Unity Editor → Agent의 Behavior Parameters → Model 슬롯에 MyBall.onnx 드래그 → Play로 확인.

결과와 배운 점

배운 점

• Unity ML-Agents라는 툴킷을 알게 된 것이 가장 큰 배움이었습니다. 좀 더 연구해서 어떤 식으로 활용할 수 있는지 파악해 볼 예정입니다.

시행착오

꿀팁

• Ctrl+C로 학습 종료 시 Exported ... .onnx 메시지가 반드시 나와야 모델이 저장된 것입니다. 메시지 없으면 저장 실패.

• 학습이 중단됐다면 --resume 플래그로 이어서 할 수 있습니다.

• TensorFlow installation not found 경고는 무시해도 됩니다 (PyTorch 기반이라 정상).

• 터미널 새 창마다 source .venv/bin/activate 재실행이 필요합니다.

앞으로의 계획

다른 예제들도 실행해 보고 좀 더 파악해 볼 예정입니다. 이후에 어떤 식으로 활용할지 좀 더 고민해 보겠습니다.

도움 받은 글

• Unity ML-Agents Release 23 공식 릴리즈

• ML-Agents Overview | ML Agents | 4.0.2