q_table_demo/GETTING_STARTED.md

🚀 Q-Table 협상 전략 데모 시작 가이드

빠른 시작

1. 환경 설정

Poetry 사용 (권장)

# Poetry 설치 (미설치시)
curl -sSL https://install.python-poetry.org | python3 -

# 의존성 설치
poetry install

# 가상환경 활성화
poetry shell

pip 사용

# 가상환경 생성 (권장)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 의존성 설치
pip install -r requirements.txt

2. 환경 변수 설정

# .env 파일 생성
cp .env.example .env

# 필요에 따라 .env 파일 수정
nano .env

3. 시스템 실행

방법 1: 전체 시스템 동시 실행

python run_both.py

방법 2: 개별 실행

# 터미널 1 - API 서버
python run_api.py

# 터미널 2 - 프론트엔드
python run_frontend.py

방법 3: Make 사용

make run-both

4. 접속

• 프론트엔드: http://localhost:8501
• API 문서: http://localhost:8000/docs

주요 기능 사용법

1. 콜드 스타트 확인

• 프론트엔드의 "콜드 스타트" 탭에서 초기 Q-Table 상태 확인
• 모든 Q값이 0인 상태에서 시작

2. 데이터 수집

• "데이터 수집" 탭에서 에피소드 생성
• 탐험율과 에피소드 수를 조정하여 경험 데이터 수집

3. Q-Learning 학습

• "Q-Learning" 탭에서 수집된 데이터로 Q-Table 업데이트
• 학습률, 할인율 등 하이퍼파라미터 조정 가능

4. FQI+CQL 학습

• "FQI+CQL" 탭에서 오프라인 학습 수행
• 보수적 Q-Learning으로 안전한 정책 학습

5. 정책 비교

• "학습된 정책" 탭에서 Q-Learning과 FQI+CQL 정책 비교
• 실제 협상 시나리오에서 행동 추천 받기

Docker 사용

Docker Compose로 실행

# 이미지 빌드
docker-compose build

# 시스템 실행
docker-compose up

# 백그라운드 실행
docker-compose up -d

# 중지
docker-compose down

개발 환경 설정

코드 품질 도구

# 코드 포맷팅
make format

# 린팅
make lint

# 테스트
make test

개발 서버 실행

# API 서버 (Hot Reload)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 프론트엔드 (Hot Reload)
streamlit run frontend/app.py --server.port 8501

문제 해결

포트 충돌

• 8000번 포트나 8501번 포트가 사용 중인 경우 .env 파일에서 포트 변경

의존성 오류

# 의존성 재설치
pip install --force-reinstall -r requirements.txt

# 또는 Poetry 사용시
poetry install --no-cache

API 연결 오류

• API 서버가 실행 중인지 확인
• http://localhost:8000/api/v1/health 에서 상태 확인

추가 정보

프로젝트 구조

qtable_negotiation_demo/
├── app/                 # FastAPI 백엔드
│   ├── api/            # API 엔드포인트
│   ├── core/           # 설정 및 유틸리티
│   ├── models/         # 데이터 모델
│   └── services/       # 비즈니스 로직
├── frontend/           # Streamlit 프론트엔드
├── tests/              # 테스트 코드
├── run_*.py           # 실행 스크립트
└── docker-compose.yml  # Docker 설정

핵심 개념

• 보상함수: R(s,a) = W × (A/P) + (1-W) × End
• 상태공간: (카드, 시나리오, 가격구간) 조합
• Q-Learning: 온라인 강화학습
• FQI+CQL: 오프라인 보수적 강화학습

지원 및 문의

• 이슈 발생시 API 문서 참조: http://localhost:8000/docs
• 로그 파일 확인: app.log