> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/user/forecast.md).

# 기계학습 (부가 화면)

## 목차

* [개요](#overview)
* [화면 구성](#layout)
* [상단 — 페이지 제목](#top)
* [좌측 — 양식(입력 폼)](#form)
  * [대상 태그 선택](#tag-select)
  * [데이터 구간](#data-range)
  * [기계학습 속성](#ml-attrs)
  * [기계학습 시작 버튼](#start-button)
* [우측 — 기계학습 결과](#results)
  * [요약 카드 3종](#summary-cards)
  * [결과 차트](#chart)
  * [예측 데이터 테이블](#forecast-table)
  * [이상진단 데이터 테이블](#abnomal-table)
* [예측·이상진단 알고리즘 선택 가이드](#alg-guide)
* [활용 시나리오](#use-cases)
* [자주 묻는 질문](#faq)
* [관련 화면](#related)

***

## 개요 <a href="#overview" id="overview"></a>

예측 분석 화면은 시계열 태그 데이터를 학습해 미래값을 예측하고, 이상치(이상진단)를 탐지합니다. 운영자가 GUI 에서 학습 구간·샘플링 주기·알고리즘만 선택하면 즉시 결과 차트와 표로 확인할 수 있습니다.

이 화면은 다음 분석에 사용됩니다.

* 향후 N개 시점의 태그 값 예측 (수요 예측·생산량 예측 등)
* 과거 데이터에서 통계적으로 벗어난 이상값 탐지
* 알람 룰 임계값을 정하기 위한 기준 분석

**경로**: 현재 통합 사이드바에는 기본 메뉴로 노출되지 않을 수 있습니다. 내부 URL 은 `/forecast/index` 이며 화면 제목은 **기계학습** 입니다.

> 이 문서는 예측·이상진단 부가 화면을 설명합니다. 좌측 메뉴 기준 운영 흐름은 [콘솔 탐색과 공통 화면](/plantpulse-platform/user/navigation.md) 을 우선 참고하세요.

***

## 화면 구성 <a href="#layout" id="layout"></a>

```
┌──────────────────────────────────────────────────────────────────┐
│  🧠 기계학습                                                       │ ← ① 상단
├─────────────────────┬────────────────────────────────────────────┤
│                     │                                            │
│  📄 양식             │  📈 기계학습 결과                           │
│  ─────────────────  │  ────────────────────────────────────────│
│  ◯ 대상 태그 선택    │  [학습 데이터] [이상진단 건수] [실행 시간]  │ ← 요약 카드
│   • 태그명 입력      │                                            │
│                     │  ┌──────────────────────────────────────┐  │
│  ◯ 데이터 구간       │  │                                      │  │
│   • 학습 구간 (날짜)  │  │       결과 차트 (520px)               │  │
│   • 샘플링 주기       │  │                                      │  │
│                     │  └──────────────────────────────────────┘  │
│  ◯ 기계학습 속성      │                                            │
│   • 예측 알고리즘     │  ◯ 예측 데이터 (테이블)                     │
│   • 예측 갯수        │  ◯ 이상진단 데이터 (테이블)                  │
│   • 이상진단 알고리즘 │                                            │
│   • 개연성           │                                            │
│                     │                                            │
│  [🚀 기계학습 시작]   │                                            │
└─────────────────────┴────────────────────────────────────────────┘
```

| 영역   | 위치       | 표시                                    |
| ---- | -------- | ------------------------------------- |
| ① 상단 | 전체 폭     | 페이지 제목                                |
| ② 좌측 | col-lg-3 | 양식(입력 폼) — 4 fieldset + 시작 버튼         |
| ③ 우측 | col-lg-9 | 기계학습 결과 — 요약 카드 3종 + 차트 + 두 개의 결과 테이블 |

***

## 상단 — 페이지 제목 <a href="#top" id="top"></a>

| 항목         | 표시        |
| ---------- | --------- |
| **페이지 제목** | 🧠 "기계학습" |

***

## 좌측 — 양식(입력 폼) <a href="#form" id="form"></a>

좌측 패널의 폼은 4개 그룹(`<fieldset>`)으로 구성됩니다.

### 1) 대상 태그 선택 <a href="#tag-select" id="tag-select"></a>

| 입력      | name       | 폭                 | placeholder | 설명                                                   |
| ------- | ---------- | ----------------- | ----------- | ---------------------------------------------------- |
| **태그명** | `tag_name` | 250px (파랑 보더 2px) | "태그명 입력"    | 등록된 태그 목록에서 자동완성으로 선택. 선택 즉시 hidden 필드 `tag_id` 에 저장 |

> 입력란 우측에는 🧭 아이콘 + "기계학습을 진행할 태그를 선택하십시오." 라는 안내 문구가 함께 표시됩니다.

### 2) 데이터 구간 <a href="#data-range" id="data-range"></a>

| 입력         | name            | 폭                     | 설명                                                                                         |
| ---------- | --------------- | --------------------- | ------------------------------------------------------------------------------------------ |
| **학습 구간**  | `learning_time` | 250px (가운데 정렬, 굵은 글씨) | 시작\~종료 일시. 클릭 시 날짜 범위 선택기. 폼 제출 시 hidden 필드 `learning_date_from` / `learning_date_to` 로 전달 |
| **샘플링 주기** | `term`          | 200px                 | 셀렉터 — "샘플링 주기" 옵션 (예: `1_MIN` / `5_MIN` / `30_MIN` / `1_HOUR` / `1_DAY` 등 시스템에 정의된 주기 목록)  |

#### 샘플링이란?

| 옵션           | 의미                                     |
| ------------ | -------------------------------------- |
| **원본(RAW)**  | 모든 데이터 포인트 그대로 학습 — 데이터가 많고 변동이 빠른 태그에 |
| **샘플링(스냅샷)** | 일정 주기로 대표값 1개를 뽑아 학습 — 장기간 학습·계산 비용 절감 |

> hidden 셀렉터로 `sampling="LAST"` 가 기본 설정됩니다(가장 마지막 값을 대표로 사용).

### 3) 기계학습 속성 <a href="#ml-attrs" id="ml-attrs"></a>

#### 예측 알고리즘 (`forecast_algorithm`)

| 옵션                       | 라벨                                        | 특성                   |
| ------------------------ | ----------------------------------------- | -------------------- |
| `LINEAR_REGRESSION` (기본) | Linear regression                         | 단순 선형 추세 — 빠르고 해석 용이 |
| `ARIMA`                  | Auto-regressive Integrated Moving Average | 시계열 자기상관·계절성 활용      |
| `SMO_REG`                | Support vector machine for regression     | 비선형 패턴, 노이즈 강건       |
| `GAUSSIAN_PROCESSES`     | Stochastic process                        | 확률적 예측 + 불확실성 추정     |

#### 예측 갯수 (`forecast_count`)

| 입력     | 폭              | 설명                  |
| ------ | -------------- | ------------------- |
| 텍스트 입력 | 200px (오른쪽 정렬) | 예측할 결과 갯수(타임스탬프 단위) |

> 예: 샘플링 주기 `1_HOUR` + 예측 갯수 `24` = 향후 24시간 예측

#### 이상진단 알고리즘 (`abnomal_algorithm`)

| 옵션            | 라벨                   | 특성                  |
| ------------- | -------------------- | ------------------- |
| `EGADS` (기본)  | Seasonal-naive-based | 계절성 반영, 운영 데이터에 일반적 |
| `DBSCAN`      | Cluster-based        | 군집에서 벗어나는 점을 이상치로   |
| `GAUSS_BASED` | Statistical-based    | 정규 분포 기반 통계적 이상치 탐지 |
| `HIL_OUT`     | Distance-based       | 거리 기반 이상치           |

#### 개연성 필터 (`probability_filter`)

| 입력     | 폭              | 의미                                           |
| ------ | -------------- | -------------------------------------------- |
| 텍스트 입력 | 200px (오른쪽 정렬) | 0\~1 사이의 임계값. 개연성 값이 이 값 이상인 데이터만 이상 데이터로 판단 |

> 예: `0.95` 입력 시 개연성이 95% 이상인 강한 이상치만 탐지. 값이 작을수록 더 많은 이상치를 잡지만 오탐이 늘어납니다.

### 4) 기계학습 시작 버튼 <a href="#start-button" id="start-button"></a>

| 버튼             | 폭          | 동작                                                                 |
| -------------- | ---------- | ------------------------------------------------------------------ |
| **🚀 기계학습 시작** | 250px (파랑) | 입력 검증 후 백엔드에 학습 요청. 실행 중에는 우측 차트 영역에 진행 표시. 완료되면 결과 차트와 두 테이블이 채워짐 |

***

## 우측 — 기계학습 결과 <a href="#results" id="results"></a>

### 요약 카드 3종 <a href="#summary-cards" id="summary-cards"></a>

차트 위쪽 가로형 3분할 카드(`total_ml_co`).

| 카드          | ID                      | 표시                |
| ----------- | ----------------------- | ----------------- |
| **학습 데이터**  | `result_learning_count` | 학습에 사용된 데이터 포인트 수 |
| **이상진단 건수** | `result_abnomal_count`  | 탐지된 이상치 건수        |
| **실행 시간**   | `result_text`           | 학습+예측 처리에 걸린 시간   |

> 실행 전에는 모두 `-` 으로 표시됩니다. 실행 직후 자동으로 채워집니다.

### 결과 차트 <a href="#chart" id="chart"></a>

차트 영역(`data_chart`, 폭 100% × 높이 520px)에 다음이 한 화면에 그려집니다.

| 시리즈                    | 의미                   |
| ---------------------- | -------------------- |
| **학습 구간 실측값**          | 입력한 학습 기간의 원본 시계열    |
| **예측 값**               | 학습 후 예측한 미래 N 개 시점   |
| **예측 상한 (LIMIT\_MAX)** | 예측 신뢰 구간의 상한         |
| **예측 하한 (LIMIT\_MIN)** | 예측 신뢰 구간의 하한         |
| **이상치 마커**             | 이상진단에서 탐지한 시점에 별도 표시 |

차트가 비어 있을 때 안내 문구가 표시됩니다.

> 🤖 \[머신러닝 일러스트]
>
> 대상 태그를 선택하신 후, 기계학습을 시작하십시오.

### 예측 데이터 테이블 <a href="#forecast-table" id="forecast-table"></a>

`<fieldset>` 의 **예측 데이터** 라벨 아래 테이블(`forecast_data_table`).

| 컬럼             | 폭     | 표시                    |
| -------------- | ----- | --------------------- |
| **No.**        | 60px  | 행 번호                  |
| **타임스탬프**      | 200px | 예측 시점                 |
| **예측 값**       | 자동    | 알고리즘이 산출한 예측치         |
| **WEIGHT**     | 자동    | 예측 가중치(알고리즘별로 의미가 다름) |
| **LIMIT\_MIN** | 자동    | 예측 하한                 |
| **LIMIT\_MAX** | 자동    | 예측 상한                 |

### 이상진단 데이터 테이블 <a href="#abnomal-table" id="abnomal-table"></a>

`<fieldset>` 의 **이상진단 데이터** 라벨 아래 테이블(`abnomal_data_table`).

| 컬럼                    | 폭     | 표시                              |
| --------------------- | ----- | ------------------------------- |
| **No.**               | 60px  | 행 번호                            |
| **타임스탬프**             | 200px | 이상치가 탐지된 시점                     |
| **이상진단 값**            | 200px | 그 시점의 실제 측정값                    |
| **개연성 (PROBABILITY)** | 자동    | 이상치 확신도 (0\~1, 1에 가까울수록 강한 이상치) |

***

## 예측·이상진단 알고리즘 선택 가이드 <a href="#alg-guide" id="alg-guide"></a>

운영 데이터에 어울리는 알고리즘을 고르실 때 참고하세요.

### 예측 알고리즘

| 데이터 특성               | 권장 알고리즘              |
| -------------------- | -------------------- |
| 단조 증가/감소 추세          | `LINEAR_REGRESSION`  |
| 일/주 단위 반복 패턴         | `ARIMA`              |
| 비선형이고 노이즈가 큰 데이터     | `SMO_REG`            |
| 예측의 불확실성도 함께 보고 싶을 때 | `GAUSSIAN_PROCESSES` |

### 이상진단 알고리즘

| 데이터 특성               | 권장 알고리즘       |
| -------------------- | ------------- |
| 시즈널리티가 있는 일반 운영 데이터  | `EGADS` (기본)  |
| 다차원 군집 분석이 적합한 다변량   | `DBSCAN`      |
| 정규 분포에 가까운 안정 데이터    | `GAUSS_BASED` |
| 점들 간 거리 기반(전역/지역 이상) | `HIL_OUT`     |

### 개연성 필터 가이드

| 값      | 효과                              |
| ------ | ------------------------------- |
| `0.5`  | 약한 이상치까지 탐지 (오탐 가능성 ↑)          |
| `0.8`  | 일반 운영에 적합                       |
| `0.95` | 강한 이상치만 탐지 (확실한 이상만)            |
| `0.99` | 매우 강한 이상치만 (오탐 거의 없음, 누락 가능성 ↑) |

***

## 활용 시나리오 <a href="#use-cases" id="use-cases"></a>

| 시나리오              | 설정 예시                                                                |
| ----------------- | -------------------------------------------------------------------- |
| **모터 온도 24시간 예측** | 태그=`MOTOR-001.TEMP` / 학습 7일 / 샘플링 1시간 / `LINEAR_REGRESSION` / 예측 24개 |
| **에너지 소비 일주일 예측** | 태그=`POWER.kWh` / 학습 30일 / 샘플링 1시간 / `ARIMA` / 예측 168개                |
| **품질 측정값 이상치 탐지** | 태그=`QUALITY.SCORE` / 학습 14일 / 샘플링 5분 / `EGADS` / 개연성 `0.9`           |
| **진동 센서 비정상 감지**  | 태그=`VIB-001.RMS` / 학습 7일 / 샘플링 RAW / `DBSCAN` / 개연성 `0.95`           |
| **알람 임계값 결정**     | 안정 운영 1주일 학습 → `GAUSS_BASED` 의 LIMIT\_MAX 를 알람 임계값으로 채택              |

***

## 자주 묻는 질문 <a href="#faq" id="faq"></a>

**Q. 학습 시작 후 결과가 빨리 안 나옵니다.** A. 학습 구간이 길거나 샘플링 주기가 짧으면 시간이 오래 걸립니다. 첫 시도에서는 학습 구간을 1\~3일 + 샘플링 주기 1시간 정도로 가볍게 잡아 시간을 측정하세요.

**Q. 예측 값이 너무 평탄하게 나옵니다.** A. 학습 알고리즘이 `LINEAR_REGRESSION` 인 경우 단조 추세만 잡습니다. 주기성이 있는 데이터라면 `ARIMA` 로 바꿔 보세요.

**Q. 이상치가 너무 많이 잡힙니다 / 너무 적게 잡힙니다.** A. **개연성 필터** 값을 조정하세요. 너무 많이 잡힌다면 0.9~~0.95 로 올리고, 너무 적게 잡힌다면 0.5~~0.7 로 낮추세요.

**Q. 학습 구간이 짧으면 안 되나요?** A. 학습 구간이 너무 짧으면 모델이 충분한 패턴을 학습하지 못합니다. 일반적으로 **예측 갯수의 10배 이상**을 학습 구간으로 잡으시기를 권장합니다.

**Q. 결과 테이블의 WEIGHT 컬럼은 무슨 의미인가요?** A. 알고리즘마다 다릅니다. 회귀 모델에서는 예측 가중치, 확률 모델에서는 신뢰도 척도로 사용됩니다. 일반 운영자는 LIMIT\_MIN/LIMIT\_MAX 의 신뢰 구간에 더 주목하시면 됩니다.

**Q. 결과를 다른 사람에게 전달하고 싶어요.** A. 차트는 차트의 다운로드 아이콘으로 PNG 이미지를, 테이블은 브라우저의 표 복사 또는 우클릭 메뉴로 복사해 사용하세요. (CSV 다운로드 버튼은 현재 비활성화 상태)

**Q. 같은 태그에 여러 알고리즘을 비교하고 싶습니다.** A. 각 알고리즘으로 한 번씩 실행하시고 차트의 PNG 를 저장한 뒤 외부 도구에서 나란히 비교하세요. 이상진단 알고리즘은 EGADS↔DBSCAN 비교가 자주 사용됩니다.

**Q. 예측 결과를 알람 룰의 임계값으로 사용할 수 있나요?** A. 네. 안정적인 학습 결과의 LIMIT\_MAX/LIMIT\_MIN 을 [알람](/plantpulse-platform/user/alarm.md) 의 EQL 알람 임계값으로 옮겨 사용하시면 통계 기반 임계값을 자동화할 수 있습니다.

**Q. 학습 결과를 자동으로 알람밴드에 반영할 수 있나요?** A. 네. [플로우](/plantpulse-platform/user/flow.md) 의 `flow_update_tag_alarm_band_numeric` 노드를 결선해 자동화할 수 있습니다.

***

## 관련 화면 <a href="#related" id="related"></a>

* [데이터 포인트](/plantpulse-platform/user/data-point.md) — 트렌드 화면에서 원본 데이터 시각 확인
* [알람](/plantpulse-platform/user/alarm.md) — 학습 결과의 임계값을 알람 룰로 이전
* [일일 통계](/plantpulse-platform/user/statistics.md) — 사이트·라인·설비별 비교 분석
* [플로우](/plantpulse-platform/user/flow.md) — 학습 결과를 자동 적용하는 자동화 구성