Skip to main content

개발 환경 세팅

1. 프로젝트 초기 가설 확립​

본격적인 강화학습 시뮬레이션 개발에 앞서, 우리 Sim-KUng 팀이 검증할 첫 번째 핵심 가설을 정의했습니다.

  • 시뮬레이션 환경: 2차선 고속도로 (다차선 환경의 기초)
  • 에이전트 투입 비율: 전체 차량 중 5% 를 PPO 기반 자율주행 에이전트로 구성
  • 에이전트 행동(Action): 적절한 차선 유지(Lane Keeping) 및 능동적인 가감속(Acceleration/Deceleration) 제어
  • 검증 가설: "도로 위에 단 5%의 자율주행 에이전트만 존재해도, 이들이 적절한 간격을 유지하는 '방파제' 역할을 수행하여 뒤로 밀려오는 유령 정체(Shockwave)를 흡수하고 도로 전체의 흐름을 유의미하게 향상시킬 수 있다."

2. Github 협업 및 Git Flow 규칙​

팀원 간의 코드 충돌을 막고 효율적으로 협업하기 위해, 우리 팀은 phantom-jam-rl 레포지토리에서 아래의 브랜치(Branch) 전략을 준수합니다.

  • main: 언제든 실행 가능한 안정적인 배포 및 실험 결과 도출용 코드.
  • develop: 다음 버전을 개발하는 중심 브랜치 (모든 팀원의 베이스캠프).
  • feature/{기능명}: 개인이 새로운 기능(예: feature/ppo-agent)을 개발할 때 develop에서 따와서 작업하고, 완료 시 Pull Request(PR)를 진행합니다.

3. 로컬 PC 개발 환경 100% 동기화 가이드​

운영체제가 달라도 동일한 강화학습 실험 결과를 얻기 위해, 초기 세팅된 레포지토리를 바탕으로 팀원들의 로컬 환경을 동기화했습니다.

3-1. 핵심 설치 패키지 목록​

시뮬레이션과 에이전트 학습에 필요한 라이브러리 구성은 다음과 같습니다.

  • numpy, gymnasium: 강화학습 수치 계산 및 표준 환경 API
  • stable-baselines3: PPO 알고리즘이 구현된 안정적인 강화학습 라이브러리
  • highway-env: 자율주행 시뮬레이션 환경
  • black: 코드 스타일을 통일시켜 주는 파이썬 포맷터 (충돌 방지용)
  • pygame, moviepy: 시뮬레이션 렌더링 및 결과 영상 녹화용

3-2. 팀원 환경 셋업 순서 (클론 및 설치)​

[NOTE]

시작하기 전, 팀원들은 python version을 3.10.11로 맞춰 주시는 걸 추천드립니다!
ML-Agents 관련 Numpy 호환성 에러로 인해 이보다 더 상위 버전에서는 작동하지 않을 가능성이 높습니다.

팀원들은 터미널에서 아래 명령어를 순서대로 실행하여 환경을 1분 만에 동기화할 수 있습니다. requirements.txt와 .gitignore를 미리 세팅해 두어 버전 충돌 원인을 원천 차단했습니다.

# 1. 레포지토리 클론 및 이동
git clone https://github.com/Sim-KUng/phantom-jam-rl.git
cd phantom-jam-rl

# 2. 가상환경 생성 및 실행 (Mac/Linux는 python3, source venv/bin/activate 사용)
# 여기서부터는 git bash가 아닌 powershell/cmd 에서 하시는 걸 추천드립니다
python -m venv venv
venv\Scripts\activate
# 이후 경로 앞에 (venv)가 떴는지 확인 필수!

# 3. 패키지 버전 100% 동일하게 설치
pip install --upgrade pip
pip install -r requirements.txt
# 위 명령어는 제가 requirements.txt에 미리 라이브러리를 정리해둬서 가능한 명령어 입니다..!

3-3. 작업 재개 시 가상환경 다시 켜기 (필수)​

터미널을 껐다 켜거나 새로운 창을 열면 가상환경이 해제됩니다. 코드를 실행하거나 패키지를 설치하기 전에는 반드시 아래 명령어를 입력하여 터미널 입력창 맨 앞에 (venv)가 표시되는지 확인해야 합니다.

# Windows (명령 프롬프트/PowerShell)
venv\Scripts\activate

# Windows (Git Bash) 또는 Mac/Linux
source venv/Scripts/activate

3-4. 환경 테스트 실행​

가상환경이 켜진 상태((venv))에서, 터미널에 아래 명령어를 입력하여 제공된 테스트 스크립트를 실행합니다.

python test_env.py