Macbook
4b86b2a660
- server-dev start/stop/deploy 및 Gitea push 자동 배포 - local-dev 로컬 개발 환경 Co-authored-by: Cursor <cursoragent@cursor.com>
102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# chatbotApi 설명서
|
|
|
|
> 해당 문서는 md(Markdown) 방식으로 작성되었기 때문에 마크다운 뷰어 기능이있는 편집기(vscode 등)에서 보는것을 추천드립니다.(vscode 사용 시 문서 열고 Ctrl + Shift + V)
|
|
|
|
|
|
## 1. 개요
|
|
챗봇에서 데이터 조회를 위한 api 서비스(backend, was). intent 정책(SSOT `intent-definitions.yml`)·검증·정규화와 도메인 데이터 조회(Oracle Handler / WEB 위임)를 담당합니다.
|
|
|
|
### 1.1 시스템 구성 흐름 (WAS 역할)
|
|
|
|
```mermaid
|
|
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`](../SYSTEM_ARCHITECTURE.md) · Agent tool API 상세: [`../docs/AGENT_ARCHITECTURE.md`](../docs/AGENT_ARCHITECTURE.md) · RAG API: [`RAG_API_IMPLEMENTATION.md`](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
|
|
* 서비스 시작 명령어(서비스 홈 디렉토리에서 수행해야한다.)
|
|
|
|
``` bash
|
|
./start.sh start ## 백그라운드(실운영) 기동 명령어, 평시에는 해당 명령어를 사용한다.
|
|
./start.sh starta ## 포그라운드 기동 명령어, 에러 탐색 및 모니터링시 활용
|
|
```
|
|
|
|
## 3. 기타 주의 사항
|
|
> 해당 서비스에는 교통정보 관련 API만 개발 되어있다. 향후에는 미납 조회 등 모든 서비스를 구현하면 좋을듯. (현재는 DMZ존에 위치한 챗봇 WEB서버(128.200.100.61)에 대부분의 조회 서비스가 운영되고있다. 별로 좋지않은 구조라 생각된다.)
|
|
|
|
> [ASIS] WEB ↔ DB, [TOBE] WEB ↔ WAS ↔ DB)
|
|
|
|
## ※ API 일별 사용 건수 조회 Mongo쿼리
|
|
```javascript
|
|
db.api_use_log.aggregate([
|
|
{
|
|
$group: {
|
|
_id: {
|
|
$substr: ["$request_time", 0, 10] // 'yyyy-MM-dd' 부분만 추출
|
|
},
|
|
count: { $sum: 1 } // 각 날짜별로 문서 수를 계산
|
|
}
|
|
},
|
|
{
|
|
$sort: { "_id": 1 } // 날짜별로 정렬
|
|
}
|
|
]);
|
|
```
|
|
|
|
## ※ API apikey 및 일별 사용 건수 조회 Mongo쿼리
|
|
```javascript
|
|
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별로 정렬
|
|
}
|
|
}
|
|
]);
|
|
``` |