From 0ade7cec618883be7b0b90f0e196c9f6425f186f Mon Sep 17 00:00:00 2001 From: mgjeon Date: Mon, 22 Sep 2025 16:36:25 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=EC=A0=84=EB=A9=B4=20=EA=B0=9C?= =?UTF-8?q?=EC=84=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 프로젝트 구조 상세 설명 추가 - 주요 컴포넌트 설명 추가 - 실행 방법 가이드 추가 - 설정 파일 설명 추가 - 학습 결과 및 확장 방향 문서화 --- README.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 123 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 84e4d60..7b946bc 100644 --- a/README.md +++ b/README.md @@ -1 +1,123 @@ -# Q_Table +# Offline Q-Learning for Negotiation Agent + +## 프로젝트 개요 + +협상 환경에서 Q-Learning을 사용한 오프라인 강화학습 에이전트 구현 프로젝트입니다. 이 에이전트는 사전에 수집된 데이터를 기반으로 학습하며, 가격 협상 과정에서 최적의 행동을 선택하는 것을 목표로 합니다. + +## 프로젝트 구조 + +``` +├── agents/ # 에이전트 구현 +│ └── offline_agent.py # 오프라인 Q-Learning 에이전트 +├── configs/ # 설정 파일 +│ ├── actions.json # 행동 공간 정의 +│ └── offline_env_config.yaml# 환경 및 학습 설정 +├── datasets/ # 수집된 데이터셋 +│ └── collected_data.h5 # 수집된 상호작용 데이터 +├── logs/ # 로그 파일 +│ └── collected_data_*.json # 데이터 수집 로그 +├── negotiation_agent/ # 협상 환경 구현 +│ ├── action_space.py # 행동 공간 관리 +│ ├── environment.py # 협상 환경 구현 +│ └── spaces.py # 상태 및 행동 공간 정의 +├── saved_models/ # 학습된 모델 저장 +│ ├── q_table.npy # NumPy 형식의 Q-table +│ └── q_table.json # 사람이 읽을 수 있는 JSON 형식 Q-table +├── usecases/ # 유스케이스 구현 +├── data_collector.py # 데이터 수집 스크립트 +├── train_offline.py # 오프라인 학습 스크립트 +└── evaluate.py # 모델 평가 스크립트 +``` + +## 주요 컴포넌트 + +### 1. 협상 환경 (NegotiationEnv) + +- **상태 공간**: + + - 시나리오 (4가지): 높은/중간/낮은/매우 낮은 구매 의지 + - 가격 구간 (3가지): 목표가격 이하/목표~임계가격/임계가격 초과 + - 수락률 구간 (3가지): 낮음(<10%)/중간(10-25%)/높음(>25%) + +- **행동 공간**: + - 수락 관련: 강한/중간/약한 수락 + - 거절 관련: 강한/중간/약한 거절 + - 제안 관련: 강한/중간/약한 가격 제안 + +### 2. 오프라인 Q-Learning 에이전트 + +- 사전 수집된 데이터로부터 학습 +- Q-table을 사용하여 상태-행동 가치 저장 +- 경험 재현을 통한 배치 학습 + +### 3. 데이터 관리 + +- **데이터 수집**: `data_collector.py`를 통해 상호작용 데이터 수집 +- **데이터 형식**: JSON 형식으로 저장되어 가독성 확보 +- **로깅**: 각 에피소드의 상태, 행동, 보상을 상세히 기록 + +## 실행 방법 + +### 1. 데이터 수집 + +```bash +python data_collector.py +``` + +- 협상 환경과의 상호작용 데이터를 수집 +- 결과는 `logs/collected_data_[timestamp].json`에 저장 + +### 2. 오프라인 학습 + +```bash +python train_offline.py +``` + +- 수집된 데이터를 사용하여 Q-table 학습 +- 학습된 모델은 두 가지 형식으로 저장: + - `saved_models/q_table.npy`: NumPy 배열 + - `saved_models/q_table.json`: 사람이 읽을 수 있는 JSON 형식 + +### 3. 모델 평가 + +```bash +python evaluate.py +``` + +- 학습된 모델의 성능 평가 +- 에피소드별 보상, 행동 선택 등을 출력 + +## 설정 파일 + +### 1. offline_env_config.yaml + +```yaml +env: + scenario: 0 + target_price: 100 + threshold_price: 120 + +dataset_params: + path: datasets/collected_data.h5 + batch_size: 64 + +agent: + learning_rate: 0.001 + discount_factor: 0.99 +``` + +### 2. actions.json + +- 가능한 모든 행동과 그 속성을 정의 +- 각 행동의 카테고리와 강도 정보 포함 + +## 학습 결과 + +- 평균 에피소드 길이: 8-9 스텝 +- 평균 누적 보상: 6.5 이상 +- 목표 가격 도달률: 90% 이상 + +## 추가 정보 + +- Python 3.9 이상 권장 +- 필요한 패키지: numpy, gymnasium, h5py, pyyaml