🤖 챗봇 v3 설계 문서 (SSE + WebSocket + vLLM)

---

✅ 전체 아키텍처 개요

[사용자 FE]
│
▼ (SSE)
[Backend API (FastAPI)]
│
▼ (WebSocket)
[AI 처리 서버]
│
▼ (SSE)
[vLLM]

---

1. 구성 요약

구간	통신 방식	설명
✅ FE ↔ BE	SSE (Server-Sent Events)	클라이언트가 AI 응답을 실시간으로 수신
✅ BE ↔ AI 모듈	WebSocket	FastAPI WebSocket 서버에서 메시지 수신 처리
✅ AI ↔ vLLM	SSE	stream_vllm_response() 함수로 청크 단위 생성

---

2. 주요 메시지 타입

🎯 CREATE_QUESTION

• 목적: 사용자의 응답 기반으로 다음 질문 + 선택지 생성

• 흐름:

  1. answer를 포함한 요청 수신
  2. vLLM SSE를 통해 질문 텍스트 청크 생성
  3. 청크별로 WebSocket → BE → SSE로 스트리밍
  4. 질문 완료 후 options 전송

• 응답 타입:

  • QUESTION_CHUNK
  • QUESTION_OPTIONS

---

🎯 RECOMMEND_REQUEST

• 목적: 사용자 메시지 히스토리를 기반으로 그룹 추천

• 흐름:

  1. 전체 대화 메시지 리스트를 전달
  2. 유사 그룹 탐색 + vLLM으로 추천 이유 생성
  3. 추천되는 그룹 ID 전송
  4. 이유 텍스트를 청크로 전송

• 응답 타입:

  • RECOMMEND_ID
  • RECOMMEND_REASON
  • RECOMMEND_DONE

---

3. 내부 구조 설명

🧩 AI WebSocket 핸들러 (BE 내부)

요소	설명
websocket_endpoint()	WebSocket 수신 루프
ping_loop()	연결 상태 주기 확인용 Ping
websocket_manager	session_id 기준 연결 관리
stream_question_chunks()	질문 생성 + 청크 스트리밍
stream_recommendation_chunks()	추천 이유 생성 + 스트리밍

---

4. 메시지 흐름 상세

CREATE_QUESTION 예시 흐름

1. 사용자 → BE (SSE 요청 시작)
2. BE → AI (WebSocket 전송: { type: "CREATE_QUESTION", payload: { answer } })
3. AI → vLLM (SSE 호출)
4. vLLM → AI: "질" → "문" → "을" → "생성" → ...
5. AI → BE: QUESTION_CHUNK 여러 번 전송
6. AI → BE: QUESTION_OPTIONS 최종 전송

---

RECOMMEND_REQUEST 예시 흐름

1. 사용자 → BE (SSE 요청 시작)
2. BE → AI (WebSocket 전송: { type: "RECOMMEND_REQUEST", payload: { messages } })
3. AI → vLLM: 사용자 히스토리 기반 추천 이유 생성
4. AI → BE:
   • RECOMMEND_ID: 추천된 그룹 ID
   • RECOMMEND_REASON: 이유 텍스트 청크
   • RECOMMEND_DONE: 완료 시그널

---

5. 세션 및 상태 관리

항목	방식
세션 ID	X-CHATBOT-KEY로 관리
WebSocket 연결	websocket_manager에서 관리
세션 타임아웃	ping_loop()으로 20초 간격 체크
클라이언트와의 연결	클라이언트는 WebSocket이 아닌 SSE 사용

---

6. 요약

• 🔄 FE는 WebSocket을 사용하지 않음
• ✅ WebSocket은 오직 BE 내부 AI 처리 루프용
• 📤 모든 응답은 BE에서 클라이언트로 SSE로 전송
• 💬 메시지 타입 분기 및 청크 스트리밍 처리를 통해 사용자 경험 강화

---