던전톡 Python AI 서버와 Spring Boot 백엔드를 연동하는 프로젝트입니다.
아키텍처:
사용자 → Spring Boot (8080) → Python FastAPI (8000) → AI 응답
↓
세션 관리
역할 분담:
- Spring Boot: 사용자 인증, 세션 관리, 비즈니스 로직, REST API 제공
- Python FastAPI: AI/RAG 처리, 문서 검색, 응답 생성
- Java 21
- Gradle 8.0+
- Python FastAPI 서버 (포트 8000에서 실행)
# Spring Boot 서버 시작
./gradlew bootRun
# 서버는 http://localhost:8080 에서 실행됩니다Python AI 서버가 포트 8000에서 실행 중이어야 합니다.
# Python 서버 실행 (별도 터미널)
python main.pyPOST /api/chat
Content-Type: application/json
{
"message": "안녕하세요"
}응답:
{
"response": "안녕하세요! 무엇을 도와드릴까요?",
"timestamp": 1754402962783,
"sessionId": "rag_SESSION123"
}POST /api/trpg/sessions/new응답:
{
"sessionId": "room_abc12345",
"userName": "플레이어1234",
"message": "새로운 게임 세션이 생성되었습니다."
}POST /api/trpg/chat
Content-Type: application/json
{
"message": "던전에 들어갑니다"
}응답:
{
"response": "어둠 속에서 횃불의 빛이 흔들리며...",
"sources": ["던전_가이드.txt", "몬스터_도감.txt"],
"sessionId": "room_abc12345"
}POST /api/trpg/sessions/{sessionId}/join?userName=플레이어이름GET /api/trpg/sessions/{sessionId}/infoGET /api/trpg/health응답:
{
"spring": "healthy",
"dungeontalk_ai": "healthy",
"timestamp": 1754402962783
}src/main/java/com/pythonspring/
├── PythonSpringApplication.java # 메인 애플리케이션
├── controller/
│ ├── ChatController.java # RAG 채팅 API
│ └── TRPGController.java # TRPG 게임 API
├── service/
│ ├── RagService.java # RAG 서비스
│ ├── DungeonTalkAIService.java # 던전톡 AI 서비스
│ └── SessionService.java # 세션 관리 서비스
└── dto/
├── ChatRequest.java # 채팅 요청 DTO
└── ChatResponse.java # 채팅 응답 DTO
# 서버 포트
server.port=8080
# RAG 서비스 설정 (Python AI 서버)
rag.service.url=http://localhost:8000
rag.service.timeout=30000
# 던전톡 AI 서비스 설정
dungeontalk.ai.base-url=http://localhost:8000
dungeontalk.ai.timeout=30s
# HTTP 클라이언트 설정
http.client.connection.timeout=5000
http.client.read.timeout=60000- Spring Boot 3.4.0: 웹 프레임워크
- Spring WebFlux: 비동기 HTTP 클라이언트
- Java 21: 프로그래밍 언어
- Gradle: 빌드 도구
- WebClient: Python 서버와의 비동기 통신
- RestTemplate: 기존 RAG 서비스와의 통신
- HTTP Session: 사용자 세션 관리
- TRPG 게임:
room_XXXXXXXX형태의 게임방 - RAG 채팅:
rag_XXXXXXXX형태의 개인 세션 - HTTP 세션을 통한 자동 사용자 식별
- 모든 채팅이 동일한 Python
/chat엔드포인트 사용 - 세션 ID와 사용자명을 자동으로 포함하여 전송
- API 스펙 통일로 422 에러 해결
- WebClient 기반 논블로킹 I/O
- Reactive Streams를 활용한 응답성 향상
- 60초 타임아웃으로 AI 응답 대기
- 상세한 로깅 및 에러 메시지
- 서버 헬스체크 기능
- 사용자 친화적인 오류 응답
# RAG 채팅 테스트
curl -X POST http://localhost:8080/api/chat \
-H "Content-Type: application/json" \
-d '{"message":"안녕하세요"}'
# 새 TRPG 게임 시작
curl -X POST http://localhost:8080/api/trpg/sessions/new
# TRPG 채팅 테스트
curl -X POST http://localhost:8080/api/trpg/chat \
-H "Content-Type: application/json" \
-d '{"message":"던전에 들어갑니다"}'
# 서버 상태 확인
curl -X GET http://localhost:8080/api/trpg/health- Python AI 서버: 던전톡 TRPG AI 및 RAG 엔진
- 프론트엔드: 웹 기반 TRPG 게임 인터페이스
- RAG:
rag_+ HTTP 세션 ID - TRPG:
room_+ 8자리 UUID
- 기존 RAG는 단순 메시지만 전송
- TRPG는 세션 정보 포함 필요
- 해결: 모든 API가 세션 정보를 포함하도록 통일
- WebClient로 비동기 처리
- 60초 타임아웃으로 AI 응답 대기
- Connection pooling 적용
# 원격 리포지토리 추가
git remote add origin https://github.com/DungeonTalk/Python-Spring.git
# 원격 리포지토리 확인
git remote -v
# 첫 푸시 (업스트림 설정)
git push -u origin main- GitHub에서 새 리포지토리 생성 (README, .gitignore, 라이선스 없이)
- 로컬에서 Git 초기화 (이미 완료됨)
- 원격 리포지토리 연결:
git remote add origin https://github.com/DungeonTalk/Python-Spring.git
- 첫 커밋 및 푸시:
git add . git commit -m "feat: 초기 TRPG 챗봇 시스템 구현" git push -u origin main
# 변경사항 스테이징
git add .
# 커밋 (한국어 메시지 사용)
git commit -m "feat: 새로운 기능 추가"
# 원격 리포지토리에 푸시
git push origin main- 이슈 확인 및 생성
- feature 브랜치 생성
- 변경사항 구현
- 테스트 수행
- Pull Request 생성
이 프로젝트는 MIT 라이선스 하에 있습니다.