169 lines
3.6 KiB
Markdown
169 lines
3.6 KiB
Markdown
# 🚀 Q-Table 협상 전략 데모 시작 가이드
|
||
|
||
## 빠른 시작
|
||
|
||
### 1. 환경 설정
|
||
|
||
#### Poetry 사용 (권장)
|
||
```bash
|
||
# Poetry 설치 (미설치시)
|
||
curl -sSL https://install.python-poetry.org | python3 -
|
||
|
||
# 의존성 설치
|
||
poetry install
|
||
|
||
# 가상환경 활성화
|
||
poetry shell
|
||
```
|
||
|
||
#### pip 사용
|
||
```bash
|
||
# 가상환경 생성 (권장)
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/Mac
|
||
# venv\Scripts\activate # Windows
|
||
|
||
# 의존성 설치
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 환경 변수 설정
|
||
```bash
|
||
# .env 파일 생성
|
||
cp .env.example .env
|
||
|
||
# 필요에 따라 .env 파일 수정
|
||
nano .env
|
||
```
|
||
|
||
### 3. 시스템 실행
|
||
|
||
#### 방법 1: 전체 시스템 동시 실행
|
||
```bash
|
||
python run_both.py
|
||
```
|
||
|
||
#### 방법 2: 개별 실행
|
||
```bash
|
||
# 터미널 1 - API 서버
|
||
python run_api.py
|
||
|
||
# 터미널 2 - 프론트엔드
|
||
python run_frontend.py
|
||
```
|
||
|
||
#### 방법 3: Make 사용
|
||
```bash
|
||
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로 실행
|
||
```bash
|
||
# 이미지 빌드
|
||
docker-compose build
|
||
|
||
# 시스템 실행
|
||
docker-compose up
|
||
|
||
# 백그라운드 실행
|
||
docker-compose up -d
|
||
|
||
# 중지
|
||
docker-compose down
|
||
```
|
||
|
||
## 개발 환경 설정
|
||
|
||
### 코드 품질 도구
|
||
```bash
|
||
# 코드 포맷팅
|
||
make format
|
||
|
||
# 린팅
|
||
make lint
|
||
|
||
# 테스트
|
||
make test
|
||
```
|
||
|
||
### 개발 서버 실행
|
||
```bash
|
||
# 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 파일에서 포트 변경
|
||
|
||
### 의존성 오류
|
||
```bash
|
||
# 의존성 재설치
|
||
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
|