116 lines
6.4 KiB
Markdown
116 lines
6.4 KiB
Markdown
# MMCL (Machine Monitoring Control for LLM) 통합 프로젝트 기획 및 설계서
|
|
|
|
> [!NOTE]
|
|
> 본 문서는 지금까지 논의되고 설계된 MMCL 프로젝트의 기획 배경, 아키텍처, 데이터베이스 스키마, 핵심 로직 및 초기 산출물을 **총괄하여 정리한 마스터 기획서**입니다. 본 프로젝트는 실제 장비 납품 전 전체적인 데이터 흐름과 LLM 연동의 가능성을 타진하기 위한 **PoC (Proof of Concept) 목업(Mockup)** 프로젝트입니다.
|
|
|
|
---
|
|
|
|
## 1. 프로젝트 개요
|
|
|
|
* **프로젝트명**: MMCL (Machine Monitoring Control for LLM) Mockup System
|
|
* **프로젝트 목표**:
|
|
1. 기계/설비에 부착된 **NILM(비침입형 부하 모니터링) 장비**로부터 실시간 측정 데이터를 수집 및 저장.
|
|
2. 기구축된 **Mistral LLM**과 연동하여 사용자가 자연어로 장비의 상태를 파악.
|
|
3. LLM 판단 또는 사용자 자연어 명령에 따라 설비의 **경광등(Warning Light) 상태를 간접 제어**.
|
|
* **핵심 컨셉**: 직접적인 하드웨어 API 호출 방식이 아닌, **데이터베이스(MariaDB)의 특정 상태(Target) 필드를 조작**하고 중간의 **Agent가 이를 감지하여 물리적으로 동기화**하는 비동기 핸드쉐이크(Handshake) 방식을 채택하여 결합도를 낮추고 시스템 안정성을 높입니다.
|
|
|
|
---
|
|
|
|
## 2. 시스템 아키텍처 (System Architecture)
|
|
|
|
```mermaid
|
|
graph TD
|
|
subgraph Equipment Layer
|
|
MACH[설비/기계]
|
|
NILM_Equip[NILM 측정 센서]
|
|
Warning_Light[경광등 모듈]
|
|
MACH --- NILM_Equip
|
|
MACH --- Warning_Light
|
|
end
|
|
|
|
subgraph Messaging & Agents Layer
|
|
MQTT_Broker((MQTT Broker))
|
|
NILM_Agent[NILM Agent]
|
|
LED_Agent[경광등 Agent]
|
|
end
|
|
|
|
subgraph Database Layer (MariaDB)
|
|
DB_Master[(dev/pos/type/status_info)]
|
|
DB_Sensor[(sensor_info)]
|
|
DB_Log[(sensor_history_log)]
|
|
end
|
|
|
|
subgraph Backend API (Python/FastAPI)
|
|
API_Server[FastAPI Server]
|
|
LLM[Mistral LLM]
|
|
end
|
|
|
|
subgraph Frontend Web
|
|
UI[React/Vite Dashboard]
|
|
end
|
|
|
|
%% Data Flow
|
|
NILM_Equip -- "1. MQTT Publish" --> MQTT_Broker
|
|
MQTT_Broker -- "2. Subscribe" --> NILM_Agent
|
|
NILM_Agent -- "3. 실시간 데이터 Update & Log Insert" --> DB_Sensor
|
|
NILM_Agent -.-> DB_Log
|
|
|
|
UI -- "4. 자연어 질의/명령" --> API_Server
|
|
API_Server <--> LLM
|
|
|
|
API_Server -- "5. 제어 '목표' 상태 Update" --> DB_Sensor
|
|
|
|
LED_Agent -- "6. 목표 상태 감지 (Polling)" --> DB_Sensor
|
|
LED_Agent -- "7. 물리적 LED 제어" --> Warning_Light
|
|
LED_Agent -- "8. 제어 완료 '현재' 상태 Update" --> DB_Sensor
|
|
|
|
API_Server -. "9. Agent 완료 확인 (비동기 대기)" .-> DB_Sensor
|
|
API_Server -- "10. '적용 완료' 자연어 응답" --> UI
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 핵심 모듈 및 로직 정의
|
|
|
|
### 3.1. NILM 에이전트 (데이터 수집 및 로깅)
|
|
* NILM 장비가 전송하는 데이터를 수신(MQTT)하여 데이터베이스를 실시간으로 최신화합니다.
|
|
* `sensor_info` 테이블의 `value_chX...` 컬럼을 갱신하여 시스템 전반에 최신 상태를 알리고, 동시에 `sensor_history_log` 테이블에 데이터를 Insert하여 **시계열 이력**을 보관합니다. 이를 통해 향후 대시보드에서 전력 사용량 트렌드 분석 등이 가능해집니다.
|
|
|
|
### 3.2. LLM 자연어 인터페이스 및 백엔드 서버
|
|
* **FastAPI**를 활용하여 프론트엔드와 LLM, DB 사이의 통신을 중계합니다.
|
|
* 사용자가 "에러 발생했어, 1번 장비 불빛 바꿔"와 같은 자연어를 입력하면, 백엔드가 Mistral LLM을 통해 사용자 의도를 분석하고 제어할 목표 상태(예: RED)를 결정합니다.
|
|
|
|
### 3.3. 비동기 핸드쉐이크 (Handshake) 제어 및 검증
|
|
* **목표 상태 지시**: 백엔드 서버는 `sensor_info`의 `target_chX_statusID` 필드에 변경하고자 하는 목표 상태값을 기록합니다.
|
|
* **에이전트 동기화**: `경광등 Agent`가 주기적으로 DB를 읽어 `target_...` 값과 `value_...`(현재 물리적 상태) 값이 다름을 감지하면 실제 하드웨어를 제어합니다. 제어가 정상적으로 끝나면 `value_...` 값을 `target_...`과 동일하게 업데이트합니다.
|
|
* **완료 피드백 검증**: 백엔드 서버는 지시 후 대기 루프(Polling)를 돌며 `value_...` 값이 변경되었는지 확인합니다. 값이 목표와 일치하는 것을 확인한 뒤에야 사용자 UI 화면으로 "제어가 정상적으로 완료되었습니다"라는 메시지를 반환합니다.
|
|
|
|
---
|
|
|
|
## 4. 데이터베이스 테이블 구조 요약
|
|
|
|
기존에 설계된 설비 테이블(dev_info) 구조를 바탕으로 MMCL의 핵심 요구사항을 확장 통합한 총 7개의 테이블 구성입니다.
|
|
|
|
| 테이블명 | 주요 역할 및 기능 |
|
|
| --- | --- |
|
|
| `dev_info` | 장비(NILM, 경광등)가 부착된 물리적 **설비 및 기계의 마스터 정보** 및 센서 식별번호 매핑. |
|
|
| `sensor_info` | 각 센서의 **실시간 최신 계측값(Current)** 및 핸드쉐이크 로직을 위한 **목표 상태(Target)** 값 보관. |
|
|
| `sensor_history_log` | (신규) `sensor_info` 갱신 시 해당 시점의 측정값을 보관하는 **시계열 이력 저장소**. |
|
|
| `pos_info` | 기계가 설치된 위치 및 구역 마스터 정보. |
|
|
| `type_info` | 센서 유형 코드 정의 (1: NILM, 2: 경광등). |
|
|
| `status_info` | 0(OFF), 1(ON) 등 시스템 내 공통 상태 코드 매핑. |
|
|
| `nilm_init_value` | 설비별 NILM 측정의 기준이 되는 초기 세팅값. |
|
|
|
|
---
|
|
|
|
## 5. 프로젝트 초기 산출물(뼈대 코드) 내역
|
|
|
|
위 아키텍처를 증명하고 빠르게 테스트해 볼 수 있도록 1차 작업 완료된 뼈대(Scaffolding) 코드 구조입니다.
|
|
|
|
1. **통합 DB 쿼리** (`database/schema.sql`): 통합된 7개 테이블 DDL 및 최초 기동용 테스트 더미 데이터.
|
|
2. **에이전트 모듈** (`agents/`):
|
|
- `nilm_agent_mock.py`: NILM 가상 데이터 갱신 및 시계열 로깅 에이전트.
|
|
- `warning_light_agent.py`: 목표값(Target)을 감지하고 동기화(Current 갱신)하는 핸드쉐이크 에이전트.
|
|
3. **백엔드 모듈** (`backend/main.py`): 핸드쉐이크 대기 로직 및 LLM 텍스트 룰 처리가 포함된 FastAPI 기반 API 서버.
|
|
4. **웹 대시보드** (`frontend/`): React + Vite 기반으로 구축된, Glassmorphism 디자인 패턴을 적용한 현대적 감각의 실시간 모니터링 & 채팅 화면.
|