로컬 LLM + RAG 기반 AI 채팅봇 만들기 # 35 - 챗봇 API 설계

로컬 LLM + RAG 기반 AI 채팅봇 만들기

5.1 챗봇 API 설계

이제 백엔드와 프론트엔드가 WebSocket을 통해 실시간으로 통신할 수 있도록 구현했습니다.
이번 단계에서는 RESTful API를 활용하여 챗봇 기능을 확장하고, API 문서화를 진행하겠습니다.

---

1) 챗봇 API 설계 개요

✅ 왜 REST API를 추가해야 하는가?

• WebSocket은 실시간 메시지 전송에 적합하지만 대화 이력 조회 및 관리 기능이 부족
• RESTful API를 통해 대화 이력을 저장하고, 특정 세션의 대화를 불러오는 기능 추가
• API 문서화를 진행하여 프론트엔드 및 외부 시스템과의 연동을 쉽게 지원

---

2) API 엔드포인트 설계

📌 챗봇 관련 API 엔드포인트

HTTP 메서드 엔드포인트 설명

POST	/api/chat/send	메시지 전송 (LLM 요청 및 응답)
POST	/api/chat/save	대화 메시지 저장
GET	/api/chat/{sessionId}	특정 대화 세션의 대화 기록 조회
GET	/api/chat/sessions/{userId}	사용자의 전체 대화 세션 목록 조회

---

3) API 엔드포인트 구현

📌 ① AI 챗봇 메시지 전송 API (/api/chat/send)

package ktor_chatbot.routes

import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import ktor_chatbot.services.LlmService
import org.koin.ktor.ext.inject

fun Application.configureChatApi() {
    val llmService: LlmService by inject()

    routing {
        post("/api/chat/send") {
            val request = call.receive<Map<String, String>>()
            val message = request["message"] ?: return@post call.respondText("메시지 필요", status = io.ktor.http.HttpStatusCode.BadRequest)

            val response = llmService.getLlmResponse(message)
            call.respond(mapOf("response" to response))
        }
    }
}

---

📌 ② 대화 저장 API (/api/chat/save)

post("/api/chat/save") {
    val request = call.receive<Map<String, String>>()
    val sessionId = request["sessionId"] ?: return@post call.respondText("세션 ID 필요", status = io.ktor.http.HttpStatusCode.BadRequest)
    val sender = request["sender"] ?: return@post call.respondText("보낸 사람 필요", status = io.ktor.http.HttpStatusCode.BadRequest)
    val message = request["message"] ?: return@post call.respondText("메시지 필요", status = io.ktor.http.HttpStatusCode.BadRequest)

    chatService.saveMessage(sessionId, sender, message)
    call.respondText("메시지 저장 완료", status = io.ktor.http.HttpStatusCode.OK)
}

---

📌 ③ 특정 대화 세션 조회 API (/api/chat/{sessionId})

get("/api/chat/{sessionId}") {
    val sessionId = call.parameters["sessionId"] ?: return@get call.respondText("세션 ID 필요", status = io.ktor.http.HttpStatusCode.BadRequest)
    val messages = chatService.getMessagesBySession(sessionId)
    call.respond(messages)
}

---

📌 ④ 사용자의 전체 대화 세션 조회 API (/api/chat/sessions/{userId})

get("/api/chat/sessions/{userId}") {
    val userId = call.parameters["userId"] ?: return@get call.respondText("사용자 ID 필요", status = io.ktor.http.HttpStatusCode.BadRequest)
    val sessions = chatService.getUserSessions(userId)
    call.respond(sessions)
}

---

4) Ktor 서버에서 API 활성화

📌 Application.kt 수정

package ktor_chatbot

import io.ktor.server.application.*
import ktor_chatbot.plugins.*
import ktor_chatbot.services.ChatService
import ktor_chatbot.routes.configureChatApi
import org.koin.dsl.module
import org.koin.ktor.plugin.Koin

fun Application.module() {
    install(Koin) {
        modules(module {
            single { ChatService() }
        })
    }

    configureChatApi()
    configureRouting()
}

---

5) API 테스트

🔹 Ktor 서버 실행

./gradlew run

🔹 Postman 또는 cURL을 사용한 API 테스트

✅ 1) AI 챗봇 메시지 전송

curl -X POST "http://localhost:8080/api/chat/send" \
     -H "Content-Type: application/json" \
     -d '{"message": "챗봇이 뭐야?"}'

📌 예상 응답

{
    "response": "AI 챗봇은 사용자 질문을 분석하고 응답을 제공하는 시스템입니다."
}

---

✅ 2) 특정 세션의 대화 조회

curl -X GET "http://localhost:8080/api/chat/session123"

📌 예상 응답 (JSON)

[
    { "sender": "user", "message": "안녕하세요!" },
    { "sender": "ai", "message": "안녕하세요! 무엇을 도와드릴까요?" }
]

---

✅ 3) 사용자의 전체 대화 세션 조회

curl -X GET "http://localhost:8080/api/chat/sessions/guest"

📌 예상 응답

[
    "session123",
    "session456"
]

---

6) API 문서화 (Swagger 적용)

Ktor의 Swagger (OpenAPI) 를 활용하여 API 문서를 자동으로 생성할 수 있습니다.

📌 Swagger 플러그인 추가 (build.gradle.kts)

dependencies {
    implementation("io.ktor:ktor-server-swagger:2.3.5")
}

---

📌 Swagger 설정 (SwaggerConfig.kt)

package ktor_chatbot.plugins

import io.ktor.server.application.*
import io.ktor.server.plugins.swagger.*

fun Application.configureSwagger() {
    install(SwaggerUI) {
        path = "/swagger"
    }
}

---

📌 API 문서 확인

서버를 실행한 후, 브라우저에서 다음 URL로 접속하면 API 문서를 확인할 수 있습니다.
👉 http://localhost:8080/swagger

---

7) API 설계 요약

기능 엔드포인트 메서드

AI 챗봇 응답	/api/chat/send	POST
대화 저장	/api/chat/save	POST
세션별 대화 조회	/api/chat/{sessionId}	GET
사용자 세션 조회	/api/chat/sessions/{userId}	GET

---

8) 다음 단계

이제 RESTful API를 통해 챗봇과의 상호작용을 확장하고, API 문서화를 진행했습니다.
다음으로 5.2 API 테스트 (Postman 사용) 을 진행하여 API가 정상적으로 동작하는지 검증하겠습니다! 🚀