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

소심한 화가 · Claude Code MVP 공장 · · 좋아요 0 · 답글 0

연재 Claude Code MVP 공장 시즌 7 1/7편

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

시행착오

오류

원인

해결

grpcio==1.48.2 빌드 실패

macOS + Python 3.10에서 wheel 미제공

override-dependencies로 grpcio==1.78.0 강제

ModuleNotFoundError: pkg_resources

setuptools 60+ 버전 변경

setuptools<60 고정

.onnx 저장 시 onnxscript 오류

torch 2.10+의 의존성 충돌

torch>=2.2.1,<2.3 고정

Config file could not be found

하위 폴더에서 실행

반드시 프로젝트 루트에서 실행

꿀팁

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

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

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

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

앞으로의 계획

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

도움 받은 글

태그: #CTO