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

RAG API 구현 완료 문서

✅ 수정 완료된 파일

1️⃣ RagConfig.java - Docker 스펙에 맞게 수정

- host: localhost (Docker 컨테이너)
- port: 28012 (Docker 외부 포트)
- askEndpoint: /ask
- healthEndpoint: /health (추가)

2️⃣ RagServerRequest.java - API 스펙 적용

{
  "query": "사용자 질문"  // Docker API 필드명에 맞춤
}

3️⃣ RagServerResponse.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 설정

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 컨테이너 직접 테스트

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

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

예상 응답:

{
  "answer": "회원가입은...",
  "matched_questions": ["회원가입 방법", "가입 절차"],
  "scores": [0.95, 0.89],
  "num_references": 5
}

2. Spring Boot API 테스트

# 질문 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

예상 응답 (성공):

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

예상 응답 (실패):

{
  "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):

{
  "question": "배송은 얼마나 걸리나요?",
  "botId": "bot-001"
}

헬스체크 API:

• Method: GET
• URL: http://localhost:8086/api/v1/rag-only/health

---

📋 환경별 설정

로컬 개발 (application-local.yml)

rag:
  server:
    host: localhost
    port: 28012

개발 서버 (application-dev.yml)

rag:
  server:
    host: 172.16.163.62  # 개발 서버 IP
    port: 28012

운영 서버 (application-prod.yml)

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 컨테이너 실행 확인

   docker ps | grep 28012
   

2. 포트 접근 가능 확인

   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 스펙에 맞춰 수정되었습니다.

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