프로그래밍

Unity ML-Agents 파이썬 환경 설정 안내서

ngcbbs 2025. 4. 27. 13:41

Unity ML-Agents 파이썬 환경 설정 안내서

아래는 Unity ML-Agents를 위한 파이썬 환경 설치 및 설정 절차를 최신 공식 문서와 실사용 예시를 바탕으로 정리한 가이드입니다.

1. Python 및 가상환경 준비

  • 권장 Python 버전: 3.10.12 (ML-Agents 최신 버전 기준)^1
  • 가상환경 생성 (Anaconda 권장):
conda create -n mlagents python=3.10.12
conda activate mlagents

또는

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

2. 필수 패키지 설치

pip install torch torchvision torchaudio

CPU만 사용할 경우:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
  • Numpy 등 의존성 패키지 설치
pip install numpy

3. ML-Agents Python 패키지 설치

  • PyPI에서 바로 설치 (권장)
pip install mlagents

또는 특정 버전 설치:

pip install mlagents==0.30.0  # 원하는 버전 명시
  • GitHub에서 직접 설치 (예제/개발용)
git clone --branch release_22 https://github.com/Unity-Technologies/ml-agents.git
cd ml-agents
pip install -e ./ml-agents-envs
pip install -e ./ml-agents
- 최신 개발 버전이 필요하다면 `--branch release_22`를 생략[^1][^6][^7]

4. 설치 확인

  • 아래 명령어로 정상 설치 여부를 확인합니다.
mlagents-learn --help

유니티 로고와 함께 도움말이 출력되면 성공입니다^4^7.

5. Unity와 연동 및 학습 실행

  1. Unity에서 ML-Agents 패키지 설치
    • Unity Package Manager에서 com.unity.ml-agents 패키지를 설치
  2. 예제 씬 실행
    • 예: Assets/ML-Agents/Examples/3DBall/Scenes/3DBall 씬 열기
  3. 학습 시작
    • 터미널에서:
mlagents-learn config/ppo/3DBall.yaml --run-id=first3DBallRun
- Unity 에디터에서 Play 버튼 클릭
- 학습이 진행되며, 결과는 `results/<run-id>/` 폴더에 저장

6. 추가 참고사항

  • 패키지 버전 호환: Unity 패키지와 Python mlagents 패키지 버전이 호환되는지 반드시 확인하세요^5.
  • 의존성 문제: numpy, protobuf, grpcio 등 의존성 패키지 버전 오류가 발생할 수 있으니 공식 문서 및 에러 메시지 참고^6.
  • Mac(M1/M2) 환경: PyTorch, hdf5 등 일부 패키지 설치에 추가 옵션 필요할 수 있음^6.

요약 명령어 모음

# (1) 가상환경 생성 및 활성화
conda create -n mlagents python=3.10.12
conda activate mlagents

# (2) PyTorch 및 ML-Agents 설치
pip install torch torchvision torchaudio
pip install mlagents

# (3) 설치 확인
mlagents-learn --help

이 가이드대로 따라하면 최신 Unity ML-Agents 파이썬 환경을 무리 없이 구축할 수 있습니다.
자세한 내용과 버전별 상세 설정은 공식 설치 문서와 각종 튜토리얼 블로그를 참고하세요.

⁂