Recommendation ‐ 세부기능 - nhnacademy-aiot3-4iren/4iren-wiki GitHub Wiki

기능 요구사항

사용 모델: Google Gemini (Spring AI). 의도 분류·답변 생성·브리핑·요약 모두 동일한 단일 모델을 사용하며, 용도별 경량/고성능 모델 분리는 적용하지 않는다.

1. 자연어 질의 처리

기능

사용자의 자연어 질의를 분석하여 적절한 기능을 수행한다.

요구사항

별도의 의도 분류 단계를 두지 않고, 단일 프롬프트 안에서 모델의 Tool Calling으로 의도 해석과 도구 선택을 함께 수행한다.
질문에 포함된 대상(팀, 건물, 공간, 기기, 센서 등)을 추출한다.
질문에 포함된 시간 정보를 분석한다.
이전 대화에서 언급된 공간을 참조하여 "그 강의실" 같은 지시어를 해석한다.
응답은 answer와 후속 선택지 options를 담은 고정 JSON 형식으로 생성하며, 파싱에 실패하면 원문 텍스트를 답변으로 사용한다.

2. Tool 호출 관리

기능

사용자 질의를 처리하기 위해 필요한 Tool을 선택하고 호출한다.

요구사항

질의에 적합한 Tool을 선택한다.
하나 이상의 Tool이 필요한 경우 순차 또는 병렬 호출한다.
Tool 호출 결과를 종합하여 응답을 생성한다.
Tool 호출 실패 시 적절한 예외 처리를 수행한다.
불필요한 Tool 호출을 최소화한다.

3. 대화 응답 생성

기능

Tool 실행 결과를 기반으로 자연어 응답을 생성한다.

요구사항

조회 결과를 자연스러운 문장으로 생성한다.
필요한 경우 응답의 근거를 함께 제공한다.
조회 결과가 없는 경우 적절한 안내 메시지를 제공한다.
오류 발생 시 사용자에게 이해하기 쉬운 오류 메시지를 제공한다.
일관된 응답 형식을 유지한다.

4. 사용자 정보 조회

기능

사용자의 정보를 자연어로 조회한다.

요구사항

사용자가 가입한 팀 목록을 조회할 수 있다.
사용자가 구독 중인 공간 목록을 조회할 수 있다.
사용자의 권한 정보를 조회할 수 있다.

5. 팀 정보 조회

기능

팀과 관련된 정보를 자연어로 조회한다.

요구사항

팀이 관리하는 건물 목록을 조회할 수 있다.
팀이 관리하는 공간 목록을 조회할 수 있다.
팀이 관리하는 기기 목록을 조회할 수 있다.
팀이 관리하는 센서 목록을 조회할 수 있다.
특정 건물 또는 공간에 포함된 리소스를 조회할 수 있다.

6. 공간 정보 조회

기능

공간과 관련된 정보를 자연어로 조회한다.

요구사항

공간의 기기 목록을 조회할 수 있다.
공간의 센서 목록을 조회할 수 있다.
공간의 현재 환경 정보를 조회할 수 있다.
공간의 최근 센서 데이터를 조회할 수 있다.
공간의 평균 센서 데이터를 조회할 수 있다.

7. 공간 구독 관리

기능

자연어를 이용하여 공간 구독을 관리한다.

요구사항

공간을 구독할 수 있다.
공간 구독을 취소할 수 있다.
대상 공간이 특정되지 않은 경우 후보 목록을 선택지로 제시한다. (공간이 특정되면 실행 전 별도 확인 없이 바로 처리한다)
구독 결과를 사용자에게 안내한다.

8. 기상 정보 제공

기능

기상청 데이터를 활용하여 날씨 정보를 제공한다.

요구사항

현재 날씨를 조회할 수 있다.
초단기 예보를 조회할 수 있다.
특정 시각의 날씨를 조회할 수 있다.
공간 환경과 날씨를 함께 분석하여 안내할 수 있다.

9. 환경 분석

기능

센서 데이터와 외부 데이터를 종합하여 현재 환경을 서술한다.

요구사항

조회한 센서값과 날씨를 근거로 현재 공간의 환경 상태를 자연어로 설명한다.
데이터가 부족한 항목은 단정하지 않고 "확인이 필요합니다" 형태로 안내한다.
환경 개선 방안을 제안한다.

규칙·모델 기반의 이상 징후 탐지나 위험도 산출 로직은 이 서비스에 없다. 임계치 이탈 탐지는 Processing, 조건 기반 알림은 Rule Engine이 담당하며, 여기서는 조회한 값에 대한 LLM 서술만 수행한다.

10. 환경 리포트 생성

기능

환경 데이터를 기반으로 요약 리포트를 생성한다.

요구사항

공간 단위로 하루 환경 요약(일일 요약)을 생성할 수 있다.
실내 센서 시계열과 외부 기상 이력을 비교하여 요약한다.
요약 결과는 Redis에 캐시하며(12시간), 캐시 삭제 API를 제공한다.

팀 전체 단위 요약, 주간·월간 리포트는 제공하지 않는다. 리포트 단위는 항상 공간(강의실) 하나다.

11. 웰컴 브리핑

기능

특정 공간의 당일 환경을 종합하여 브리핑을 제공한다.

요구사항

요청받은 공간 1곳에 대해 브리핑을 생성한다. (구독 공간 전체를 순회하지 않는다)
현재 센서값을 우선 근거로 사용하고, 당일 운영 계획은 ML 추천 결과를 근거로 사용한다.
현재 날씨를 함께 제공한다.
필요한 행동을 추천한다.
오전 10시 이전에만 생성 가능하며, 이후 요청은 거부한다.
결과는 Redis에 캐시하며(1시간, 팀·공간·날짜 단위), 캐시 삭제 API를 제공한다.

브리핑은 요청 시 생성(pull) 방식이다. 웹의 강의실 상세 화면 진입 시 호출되며, 도어 센서 등 이벤트로 자동 발송되는 경로는 없다.

12. 브리핑 정책 관리

기능

팀·공간별로 브리핑 생성 조건을 설정한다.

요구사항

강수확률·풍속·습도 임계값을 팀 또는 공간 단위로 등록·조회·수정·삭제할 수 있다.
정책 활성/비활성을 전환할 수 있다.
정책 접근 시 요청자의 권한을 검증한다.

13. 기기 운전 추천 (ML 모델 서빙)

기능

학습된 ONNX 모델로 기기 운전 시점을 추천하고, 브리핑 근거로 제공한다.

요구사항

MinIO에서 모델 번들을 내려받아 매니페스트·체크섬을 검증하고 ONNX Runtime 세션으로 적재한다.
기동 시 스모크 테스트로 추론 가능 여부를 확인한다.
냉난방기·환기 기기의 가동 시작/종료 시간대와 확신도를 산출한다.
공간별 선호 환경 프로필을 함께 적용한다.
설정값으로 모델 서빙 전체를 비활성화할 수 있다.

산출물은 기기 운전 시간대 추천이며, 미래 시점의 CO₂·온도 예측값이나 임계치 도달 예상 시각, 재실 인원·밀집도는 제공하지 않는다.

14. 대화 컨텍스트 관리

기능

이전 대화 내용을 활용하여 연속적인 대화를 지원한다.

요구사항

직전 질문·답변과 최근 언급된 대상(팀·건물·공간)을 Redis에 20분간 보관한다.
보관된 대상 정보로 후속 질문의 지시어를 해석한다.
직전 대화의 센서값은 현재 상태로 재사용하지 않는다. 값이 필요하면 반드시 도구를 다시 호출하도록 강제한다.
텔레그램 채널 요청은 대화 컨텍스트를 저장하지 않고, 봇이 관리하는 별도 컨텍스트를 참조한다.

15. 접근 제어

기능

요청자의 권한 범위를 벗어난 데이터 조회를 차단한다.

요구사항

센서 데이터 조회 도구는 요청자의 역할·구독 범위에 따라 접근을 제한한다.
권한이 없는 경우 모델이 우회하지 못하도록 거부 응답 코드를 반환한다.

16. 응답 최적화

기능

응답 속도와 비용을 최적화한다.

요구사항

브리핑(1시간), 일일 요약(12시간), 일일 날씨(6시간)는 Redis TTL 캐시를 적용한다.
각 캐시는 수동 삭제 API를 제공한다.
도구 호출·LLM 호출·Redis 접근 구간별 소요 시간을 로깅한다.

이 서비스 자체에는 서킷브레이커·재시도가 없다. 장애 격리는 호출 측에서 처리하며, 웹은 브리핑 없이 화면을 렌더링하고 텔레그램 봇은 폴백 안내 문구로 대체한다.