본문으로 건너뛰기

AI 모듈

모듈 개요​

ai 모듈(modules/ai)은 Lumie 플랫폼의 AI 챗봇 기능을 제공합니다. 2026-05-26 LangGraph 마이그레이션(Phase 5) 완료 이후, Spring AI 및 DeepSeek 직접 연동 코드는 모두 제거되었습니다. 현재 모든 실제 LLM 추론은 lumie-worker의 chatbot-svc(FastAPI + LangGraph)에서 수행되며, 이 모듈은 프록시 + 대화 영속성 레이어 역할만 합니다.

  • 배포: lumie-backend 모놀리스의 modules/ai
  • 데이터베이스: PostgreSQL (멀티테넌트 RLS)
  • 외부 연동: chatbot-svc (lumie-worker) — HTTP/1.1 (ChatbotClient)
  • Spring AI: 제거됨 (Phase 5)

아키텍처​

ChatbotClient는 uvicorn HTTP/1.1과의 호환성을 위해 JDK HttpClient를 HTTP/1.1로 고정합니다. 외부 HTTP 호출은 HARD_RULES_CROSS에 따라 @Transactional 경계 바깥에서 수행됩니다.

API 엔드포인트​

채팅 API​

메서드경로설명
POST/v1/chatAI에 메시지 전송 (단일 응답)
POST/v1/chat/streamSSE 스트리밍 응답 (text/event-stream)
POST/v1/chat/confirm대기 중인 작업 확인/거부

대화 관리 API​

메서드경로설명
GET/v1/conversations대화 목록 조회
GET/v1/conversations/\{id\}대화 상세 조회
DELETE/v1/conversations/\{id\}대화 삭제

스케줄링 API​

메서드경로설명
GET/v1/scheduled-tasks예약 작업 목록
PUT/v1/scheduled-tasks/\{id\}작업 상태 변경 (PAUSED/ACTIVE)
DELETE/v1/scheduled-tasks/\{id\}작업 삭제

내부 API (/internal/chatbot/**)​

chatbot-svc가 실행/영속성 콜백에 사용합니다. HMAC 서명 검증으로 보호됩니다.

도메인 모델​

// Conversation — 대화 세션 (tenantId 스코프)
// ChatMessage — 메시지 (role: USER / ASSISTANT / TOOL / SYSTEM)
//               toolCalls, toolCallId, pendingAction 필드 포함
// ScheduledTask — 반복 작업 예약 (ONCE / DAILY / WEEKLY / MONTHLY)
//                 TaskStatus: ACTIVE / PAUSED / COMPLETED / FAILED

타임스탬프 필드는 모두 Instant (UTC)를 사용합니다.

도구 시스템 (Tool System)​

도구 실행 자체는 chatbot-svc(Python)에서 수행됩니다. BE ai 모듈에는 도구 등록(ToolRegistry)과 WRITE/NOTIFICATION 카테고리 도구에 대한 사용자 확인(/v1/chat/confirm) 흐름만 유지됩니다.

도구 카테고리​

public enum ToolCategory {
    READ,          // 읽기 전용 (즉시 실행)
    WRITE,         // 쓰기 작업 (사용자 확인 필요)
    NOTIFICATION   // 알림 발송 (사용자 확인 필요)
}

스케줄링 시스템​

ScheduledTaskExecutor가 1분마다 실행되어 nextExecutionAt이 지난 ACTIVE 작업을 처리합니다. @SchedulerLock(ShedLock) 적용으로 다중 파드 환경에서 중복 실행을 방지합니다.

설정​

ai 모듈은 독립적인 설정 파일이 없습니다. 모든 설정은 app/src/main/resources/application.yaml에서 통합 관리됩니다.

# chatbot-svc URL
lumie:
  services:
    chatbot:
      url: ${CHATBOT_SVC_URL:http://localhost:8003}

DeepSeek API 키 설정은 제거되었습니다(DEEPSEEK_API_KEY는 chatbot-svc에서 관리).

에러 처리​

public enum AiErrorCode implements ErrorCode {
    DEEPSEEK_API_ERROR("AI_001", "AI 서비스 호출 실패", 500),
    CONVERSATION_NOT_FOUND("CONV_001", "대화를 찾을 수 없습니다", 404),
    MESSAGE_NOT_FOUND("MSG_001", "메시지를 찾을 수 없습니다", 404),
    PENDING_ACTION_NOT_FOUND("ACTION_001", "대기 중인 작업이 없습니다", 404),
    TOOL_EXECUTION_ERROR("TOOL_001", "도구 실행 실패", 500),
    INVALID_SQL("SQL_001", "유효하지 않은 SQL 쿼리", 400),
    SCHEDULED_TASK_NOT_FOUND("TASK_001", "예약된 작업을 찾을 수 없습니다", 404);
}

관련 문서​