# 게임 엔진에서 동작하는 강화학습 Toolkit - Unity ML Agent 테스트 - 작성자: [소심한 화가](https://community.clauders.ai/member/imported-member-USHHYABaje) - 공간: [Claude Code MVP 공장](https://community.clauders.ai/cto) - 게시: 2026-03-18 - 연재: [Claude Code MVP 공장 시즌 7](https://community.clauders.ai/series/cto-season-7) 1/7편 - 태그: #CTO - 주소: https://community.clauders.ai/cto/post/%EA%B2%8C%EC%9E%84-%EC%97%94%EC%A7%84%EC%97%90%EC%84%9C-%EB%8F%99%EC%9E%91%ED%95%98%EB%8A%94-%EA%B0%95%ED%99%94%ED%95%99%EC%8A%B5-toolkit-unity-ml-agent-%ED%85%8C%EC%8A%A4%ED%8A%B8-ab392e55-d415-83c1-80fd-bb234522dbd0 --- ### 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` 재실행이 필요합니다. ### 앞으로의 계획 다른 예제들도 실행해 보고 좀 더 파악해 볼 예정입니다. 이후에 어떤 식으로 활용할지 좀 더 고민해 보겠습니다. ## 도움 받은 글 - [Unity ML-Agents Release 23 공식 릴리즈](https://github.com/Unity-Technologies/ml-agents/releases) - [ML-Agents Overview | ML Agents | 4.0.2](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/index.html)