exAichatbot_agent/chatbotApi-chatbot2.0-agent/RAG_API_IMPLEMENTATION.md

# RAG API 구현 완료 문서

## ✅ 수정 완료된 파일

### 1️⃣ **RagConfig.java** - Docker 스펙에 맞게 수정
```java
- host: localhost (Docker 컨테이너)
- port: 28012 (Docker 외부 포트)
- askEndpoint: /ask
- healthEndpoint: /health (추가)
```

### 2️⃣ **RagServerRequest.java** - API 스펙 적용
```java
{
  "query": "사용자 질문"  // Docker API 필드명에 맞춤
}
```

### 3️⃣ **RagServerResponse.java** - 실제 응답 구조
```java
{
  "answer": "LLM 답변",
  "matched_questions": ["질문1", "질문2", "질문3"],
  "scores": [0.95, 0.89, 0.82],
  "num_references": 5
}
```

### 4️⃣ **RagService.java** - 변환 로직 추가
- question → query 자동 변환
- 헬스체크 기능 추가
- 상세 로깅 추가

### 5️⃣ **RagApiController.java** - 헬스체크 엔드포인트 추가
- POST /api/v1/rag-only (질문 처리)
- GET /api/v1/rag-only/health (헬스체크)

### 6️⃣ **application.yml** - Docker 설정
```yaml
rag:
  server:
    host: localhost
    port: 28012
    ask-endpoint: /ask
    health-endpoint: /health
```

---

## 🔄 API 처리 흐름

```
챗봇 웹
  ↓ POST /api/v1/rag-only
  ↓ {
      "question": "회원가입은 어떻게 하나요?",
      "botId": "bot-001"
    }
  ↓
[Spring Boot API - RagApiController]
  ↓
[RagService]
  - 입력 검증
  - question → query 변환
  ↓ POST http://localhost:28012/ask
  ↓ {
      "query": "회원가입은 어떻게 하나요?"
    }
  ↓
[Docker 컨테이너 - RAG 서버]
  - LLM 처리
  - 벡터 검색
  - 답변 생성
  ↓ 응답
  ↓ {
      "answer": "회원가입은 다음과 같이...",
      "matched_questions": ["회원가입 방법", "가입 절차", "회원 등록"],
      "scores": [0.95, 0.89, 0.82],
      "num_references": 5
    }
  ↓
[RagService]
  - 응답 가공
  ↓
[RagApiController]
  ↓ 최종 응답
  ↓ {
      "status": true,
      "statusMsg": "정상응답",
      "answer": "회원가입은 다음과 같이...",
      "matchedQuestions": ["회원가입 방법", "가입 절차", "회원 등록"],
      "scores": [0.95, 0.89, 0.82],
      "numReferences": 5
    }
  ↓
챗봇 웹
```

---

## 🧪 테스트 방법

### 1. Docker 컨테이너 직접 테스트

```bash
# 질문 테스트
curl -X POST http://localhost:28012/ask \
  -H "Content-Type: application/json" \
  -d '{"query":"회원가입은 어떻게 하나요?"}'

# 헬스체크
curl http://localhost:28012/health
```

**예상 응답:**
```json
{
  "answer": "회원가입은...",
  "matched_questions": ["회원가입 방법", "가입 절차"],
  "scores": [0.95, 0.89],
  "num_references": 5
}
```

### 2. Spring Boot API 테스트

```bash
# 질문 API
curl -X POST http://localhost:8086/api/v1/rag-only \
  -H "Content-Type: application/json" \
  -d '{
    "question": "회원가입은 어떻게 하나요?",
    "botId": "bot-001"
  }'

# 헬스체크 API
curl http://localhost:8086/api/v1/rag-only/health
```

**예상 응답 (성공):**
```json
{
  "status": true,
  "statusMsg": "정상응답",
  "answer": "회원가입은 다음과 같이 진행됩니다...",
  "matchedQuestions": ["회원가입 방법", "가입 절차", "회원 등록"],
  "scores": [0.95, 0.89, 0.82],
  "numReferences": 5
}
```

**예상 응답 (실패):**
```json
{
  "status": false,
  "statusMsg": "RAG 서버 통신 실패"
}
```

### 3. Postman으로 테스트

**질문 API:**
- Method: POST
- URL: `http://localhost:8086/api/v1/rag-only`
- Headers: `Content-Type: application/json`
- Body (raw JSON):
```json
{
  "question": "배송은 얼마나 걸리나요?",
  "botId": "bot-001"
}
```

**헬스체크 API:**
- Method: GET
- URL: `http://localhost:8086/api/v1/rag-only/health`

---

## 📋 환경별 설정

### 로컬 개발 (application-local.yml)
```yaml
rag:
  server:
    host: localhost
    port: 28012
```

### 개발 서버 (application-dev.yml)
```yaml
rag:
  server:
    host: 172.16.163.62  # 개발 서버 IP
    port: 28012
```

### 운영 서버 (application-prod.yml)
```yaml
rag:
  server:
    host: ${RAG_SERVER_HOST:localhost}
    port: ${RAG_SERVER_PORT:28012}
```

---

## 🔍 로그 확인

### 질문 처리 시
```
INFO  - RAG 질문 처리 시작 - 질문: 회원가입은 어떻게 하나요?, 봇ID: bot-001
INFO  - RAG 서버 요청 시작 - URL: http://localhost:28012/ask, 질문: 회원가입은 어떻게 하나요?
INFO  - RAG 서버 응답 성공 - Status: 200 OK
INFO  - RAG 질문 처리 완료 - 참조: 5개, 유사 질문: 3개
```

### 헬스체크 시
```
INFO  - RAG 서버 헬스체크 시작
INFO  - 헬스체크 URL: http://localhost:28012/health
INFO  - RAG 서버 상태: ok, 벡터 개수: 1000
```

### 에러 시
```
ERROR - RAG 서버 통신 실패 - Connection refused
```

---

## ⚠️ 주의사항

1. **Docker 컨테이너 실행 확인**
   ```bash
   docker ps | grep 28012
   ```

2. **포트 접근 가능 확인**
   ```bash
   telnet localhost 28012
   # 또는
   nc -zv localhost 28012
   ```

3. **방화벽 설정 확인**
   - 28012 포트가 열려있는지 확인
   - 개발 서버에서는 172.16.163.62:28012 접근 가능한지 확인

4. **botId는 선택사항**
   - 현재 Docker API에는 전달되지 않음
   - 로깅/추적 목적으로만 사용

---

## 📌 다음 단계 (선택사항)

1. **응답 캐싱**
   - 동일한 질문에 대한 캐시 처리
   - Redis 또는 로컬 캐시 활용

2. **재시도 로직**
   - RAG 서버 통신 실패 시 재시도
   - Exponential Backoff 적용

3. **모니터링**
   - 응답 시간 측정
   - 에러율 추적
   - Prometheus/Grafana 연동

4. **보안 강화**
   - API 키 인증
   - Rate Limiting

---

## 🎯 완료!

모든 파일이 Docker RAG 서버 API 스펙에 맞춰 수정되었습니다.

테스트 후 문제가 있으면 알려주세요! 😊