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

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. 필수 패키지 설치

• PyTorch 설치
  (GPU 사용 시 공식 PyTorch 설치 페이지 참고)

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 파이썬 환경을 무리 없이 구축할 수 있습니다.
자세한 내용과 버전별 상세 설정은 공식 설치 문서와 각종 튜토리얼 블로그를 참고하세요.

⁂