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

chatbotApi 설명서

해당 문서는 md(Markdown) 방식으로 작성되었기 때문에 마크다운 뷰어 기능이있는 편집기(vscode 등)에서 보는것을 추천드립니다.(vscode 사용 시 문서 열고 Ctrl + Shift + V)

1. 개요

챗봇에서 데이터 조회를 위한 api 서비스(backend, was). intent 정책(SSOT intent-definitions.yml)·검증·정규화와 도메인 데이터 조회(Oracle Handler / WEB 위임)를 담당합니다.

1.1 시스템 구성 흐름 (WAS 역할)

flowchart TD
    RAG[exAiChatBot AgentService] --> TE[AgentToolController /api/v1/tools/*]

    POL[intent-definitions.yml + validator/normalizer]
    TE --> POL
    POL --> OWN{fetchOwner}
    OWN -->|WAS| ORA[IntentHandler → Oracle/TROAD]
    OWN -->|WEB| SKI[KakaoSkillToolClient → Skill /internal/tools/data-portal]
    ORA --> FMT[LlmDomainDataFormatter]
    SKI --> FMT
    FMT --> OUT([domainData + uiType])

진입	사용 모드	설명
GET /api/v1/tools/definitions	Agent	YAML → OpenAI function schema (RAG tool 목록)
POST /api/v1/tools/execute	Agent	domain tool 실행 (fetchOwner 분기: WAS Oracle / WEB Skill 역호출)

• 정책 SSOT: src/main/resources/intent-definitions.yml (fetchOwner/uiType/requiredParams/clarification).
• 핵심 원칙: LLM은 intent·params만 결정, fetchOwner/uiType/needsClarification은 WAS+YAML+validator가 결정.
• 전체 구조: ../SYSTEM_ARCHITECTURE.md · Agent tool API 상세: ../docs/AGENT_ARCHITECTURE.md · RAG API: RAG_API_IMPLEMENTATION.md

2. 프로그램 관련 정보

서비스 기동 서버 : 172.16.180.130(통합정산개발#1)

• Java version : 8(JDK 1.8)
• 서비스 기동 시점 : 상시
• 연계DB : TROAD(교통정보, Oracle), chatbot(MongoDB)
• 사용 계정 : song
• 서비스 홈 디렉토리 : /home/song/bin/chatbotApi
• 서비스 파일 : chatbotApi-0.0.1-SNAPSHOT.jar
• 서비스 설정 파일(config) : application.yml, logback-spring.xml
• 서비스 로그 파일(logs) : chatbotApi.log
• 서비스 시작 명령어(서비스 홈 디렉토리에서 수행해야한다.)

./start.sh start   ## 백그라운드(실운영) 기동 명령어, 평시에는 해당 명령어를 사용한다.
./start.sh starta  ## 포그라운드 기동 명령어, 에러 탐색 및 모니터링시 활용

3. 기타 주의 사항

해당 서비스에는 교통정보 관련 API만 개발 되어있다. 향후에는 미납 조회 등 모든 서비스를 구현하면 좋을듯. (현재는 DMZ존에 위치한 챗봇 WEB서버(128.200.100.61)에 대부분의 조회 서비스가 운영되고있다. 별로 좋지않은 구조라 생각된다.)

[ASIS] WEB ↔ DB, [TOBE] WEB ↔ WAS ↔ DB)

※ API 일별 사용 건수 조회 Mongo쿼리

db.api_use_log.aggregate([
  {
    $group: {
      _id: {
        $substr: ["$request_time", 0, 10]  // 'yyyy-MM-dd' 부분만 추출
      },
      count: { $sum: 1 } // 각 날짜별로 문서 수를 계산
    }
  },
  {
    $sort: { "_id": 1 } // 날짜별로 정렬
  }
]);

※ API apikey 및 일별 사용 건수 조회 Mongo쿼리

db.api_use_log.aggregate([
  {
    $addFields: {
      // 'yyyy-MM-dd' 형식으로 날짜 부분만 추출하여 새 필드에 저장
      "dateOnly": {
        $substr: ["$request_time", 0, 10] // '2023-11-11' 부분만 추출
      }
    }
  },
  {
    $group: {
      // api_key와 추출된 날짜를 기준으로 그룹화
      _id: {
        api_key: "$api_key",
        date: "$dateOnly"
      },
      count: { $sum: 1 } // 각 api_key와 날짜별로 문서 수를 계산
    }
  },
  {
    $sort: {
      "_id.date": 1, // 날짜별로 정렬
      "_id.api_key": 1 // api_key별로 정렬
    }
  }
]);