README.md

OMS Analyze — Prototype

โปรเจกต์นี้เป็นแอปพลิเคชันต้นแบบสำหรับวิเคราะห์ข้อมูลการดับไฟฟ้า (OMS - Outage Management System) โดยใช้ AI และ Machine Learning เพื่อสรุป สืบหาความผิดปกติ พยากรณ์ และจำแนกสาเหตุ

แอปสร้างด้วย Gradio สำหรับใช้งานผ่านเว็บเบราว์เซอร์ และรองรับการอัปโหลดไฟล์ CSV เพื่อวิเคราะห์

การติดตั้งและรัน

ข้อกำหนด

• Python 3.12.9
• ติดตั้งแพ็คเกจจาก requirements.txt:

  pip install -r requirements.txt
  

การตั้งค่าสภาพแวดล้อมด้วย pyenv (แนะนำ)

ตัวอย่างคำสั่งที่ผมใช้เพื่อเตรียม environment บน macOS (แนะนำใช้ pyenv เพื่อจัดการเวอร์ชัน Python):

cd /Users/peace/Documents/projects/huggingface/AI-OMS-Analyze
pyenv install 3.12.9
pyenv local 3.12.9
/Users/$(whoami)/.pyenv/versions/3.12.9/bin/python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt

หมายเหตุ:

• ผมคอมเมนต์ prophet ใน requirements.txt เพราะการติดตั้งจะพยายามคอมไพล์ CmdStan (C++ build) ซึ่งใช้เวลานานและมักต้องการเครื่องมือเพิ่มเติม (Xcode command line tools). ถ้าต้องการติดตั้ง prophet ให้ uncomment แล้วเตรียมเครื่องมือ build.

• ผมอัปเดต fsspec และ openai เป็นเวอร์ชันที่มีอยู่ใน PyPI เพื่อให้ pip หาแพ็กเกจเจอได้

• สำหรับการใช้ Hugging Face Router (สำหรับ LLM ใน Summarization และ Classification): ตั้งค่า HF_TOKEN ในไฟล์ .env (ดู .env.example)

Windows (ใช้ pyenv-win)

ถ้าคุณใช้ Windows ผมแนะนำติดตั้ง pyenv-win เพื่อจัดการเวอร์ชัน Python (หรือใช้ Python ที่ติดตั้งผ่าน Chocolatey / Microsoft Store แล้วสร้าง venv ตามปกติ)

1. ติดตั้ง pyenv-win (PowerShell - Run as Administrator แนะนำ)

# ผ่าน PowerShell (Admin)
Invoke-WebRequest -UseBasicParsing -Uri "https://pyenv.run" -OutFile "pyenv-win-install.ps1"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
.\n+\pyenv-win-install.ps1

# หรือ ติดตั้งด้วย Scoop (ถ้ามี scoop)
scoop install pyenv

แอปแบ่งเป็นแท็บหลัก (UI) ดังนี้ — คำอธิบายสรุปการใช้งานและไฟล์ผลลัพธ์ที่ระบบจะสร้างในโฟลเดอร์ `outputs/`:

### 1. Upload & Preview
- วัตถุประสงค์: อัปโหลดไฟล์ CSV และตรวจสอบตัวอย่างข้อมูล
- วิธีใช้:
  1. คลิก "Upload CSV" แล้วเลือกไฟล์ (ตัวอย่าง: `data/data_1.csv`, `data/data_3.csv`)
  2. ดูตัวอย่าง 10 แถวแรกและตรวจสอบชนิดของคอลัมน์
- ผลลัพธ์: preview เท่านั้น — การรันฟังก์ชันวิเคราะห์จะสร้างผลลัพธ์ลงใน `outputs/`

### 2. Summarization
- วัตถุประสงค์: สร้างสรุปภาษาธรรมชาติสำหรับแต่ละเหตุการณ์หรือชุดข้อมูล
- วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. ระบุแถวที่ต้องการสรุป (เว้นว่าง = ทั้งหมด; หรือระบุ index เช่น `0,1,2`)
  3. ถ้าต้องการใช้ LLM ให้เปิด "Use Hugging Face Router" และตั้ง `HF_TOKEN` ใน `.env`
  4. เลือกระดับรายละเอียด (brief / medium / detailed) แล้วคลิก "Generate Summaries"
- ผลลัพธ์: ไฟล์ `outputs/summaries_from_ui.csv` (UI run) หรือ `outputs/summaries.csv` (batch export)

### 3. Anomaly Detection
- วัตถุประสงค์: ตรวจหาเหตุการณ์ผิดปกติด้วย ML (IsolationForest, LOF)
- วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. เลือก algorithm: `both` (IsolationForest + LOF), `iso`, หรือ `lof`
  3. ปรับค่า contamination (0.01–0.2, default 0.05)
  4. คลิก "Run Anomaly Detection"
- ผลลัพธ์: `outputs/anomalies_from_ui.csv` (UI run) หรือ `outputs/anomalies.csv` (batch). รายการ suspects จะถูกบันทึกเป็น `outputs/ntl_suspects.csv` ถ้ามีการตรวจจับ

### 4. Forecasting
- วัตถุประสงค์: พยากรณ์จำนวนเหตุการณ์หรือ downtime ในอนาคต
- วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. เลือก metric: `count` หรือ `downtime_minutes`
  3. ตั้ง horizon (7–90 วัน, default 14)
  4. คลิก "Run Forecast"
- ผลลัพธ์: `outputs/forecast_count_from_ui.csv`, `outputs/forecast_downtime_minutes_from_ui.csv` (UI run) หรือ batch outputs `outputs/forecast_count.csv`, `outputs/forecast_downtime_minutes.csv`
  (หากต้องการความแม่นยำมากขึ้น ให้ติดตั้ง `prophet==1.1.7`)

### 5. Classification
- วัตถุประสงค์: จำแนกสาเหตุของเหตุการณ์ (root-cause classification)
- วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. (Optional) เปิด "Run weak-labeling using HF" เพื่อให้ LLM สร้าง weak labels (`HF_TOKEN` ต้องถูกตั้ง)
  3. (Optional) เลือก "Run GridSearch" สำหรับ tuning
  4. คลิก "Train Classifier"
- ผลลัพธ์: โมเดลและผลลัพธ์จะถูกบันทึกลง `outputs/`, ตัวอย่างไฟล์:
  - `outputs/rf_cause_pipeline.joblib`
  - `outputs/predictions_cause.csv`
  - ถ้ามีหลายโมเดล: `outputs/predictions_gb_CauseType.csv`, `outputs/predictions_mlp_CauseType.csv`, `outputs/predictions_rf_CauseType.csv`

python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt

หมายเหตุ สำหรับ Windows:

• บางแพ็กเกจ (เช่น geopandas, fiona, pyproj, shapely) มี native dependencies (GDAL, PROJ) — การใช้ Miniforge/Conda จะทำให้ง่ายกว่า (conda-forge)
• prophet มักจะต้องการการติดตั้ง CmdStan/cmdstanpy ล่วงหน้า และอาจจะซับซ้อนบน Windows — พิจารณาใช้ WSL2 หรือ conda สำหรับงานนี้

รันแอป

python app.py

แอปจะรันที่ http://127.0.0.1:7860 (หรือปรับ port ด้วย --server.port PORT)

โครงสร้างไฟล์

• data/data.csv: ไฟล์ข้อมูลตัวอย่าง
• scripts/: โมดูล Python สำหรับแต่ละฟีเจอร์
• outputs/: ไฟล์ผลลัพธ์จากการวิเคราะห์
• app.py: แอป Gradio หลัก

คู่มือการใช้งาน

แอปแบ่งเป็นแท็บต่างๆ ดังนี้:

1. Upload & Preview

• วัตถุประสงค์: อัปโหลดไฟล์ CSV และดูตัวอย่างข้อมูล
• วิธีใช้:
  1. คลิก "Upload CSV" เลือกไฟล์ CSV (เช่น data/data.csv)
  2. แสดงตัวอย่าง 10 แถวแรกในตาราง HTML
• หมายเหตุ: ใช้สำหรับตรวจสอบข้อมูลก่อนวิเคราะห์

2. Summarization

• วัตถุประสงค์: สร้างสรุปภาษาธรรมชาติสำหรับเหตุการณ์ดับไฟฟ้า
• วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. เลือกแถวที่ต้องการสรุป (เว้นว่าง = ทั้งหมด, หรือใส่ index เช่น 0,1,2)
  3. เลือก "Use Hugging Face Router" ถ้ามี HF_TOKEN (ใช้ LLM สำหรับสรุปละเอียด)
  4. เลือก verbosity: brief/medium/detailed
  5. คลิก "Generate Summaries"
  6. ดูผลสรุปในตาราง และ download ไฟล์ summaries_from_ui.csv
• ฟีเจอร์: รองรับ fallback เป็น rule-based summary ถ้าไม่มี HF token
• ผลลัพธ์: CSV กับคอลัมน์ EventNumber, OutageDateTime, Summary

3. Anomaly Detection

• วัตถุประสงค์: ตรวจหาเหตุการณ์ผิดปกติโดยใช้ Machine Learning
• วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. เลือก algorithm: both (IsolationForest + LOF), iso, หรือ lof
  3. ปรับ contamination (0.01-0.2, ค่าเริ่มต้น 0.05)
  4. คลิก "Run Anomaly Detection"
  5. ดูผลในตาราง (รวมคอลัมน์ anomaly flags และ explanations)
  6. Download ไฟล์ anomalies_from_ui.csv
• ฟีเจอร์: Feature engineering (duration, load, affected customers, etc.), z-score explanations
• ผลลัพธ์: CSV กับคอลัมน์ anomaly scores และ textual explanations

4. Forecasting

• วัตถุประสงค์: พยากรณ์จำนวนเหตุการณ์หรือ downtime ในอนาคต
• วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. เลือก metric: count (จำนวนเหตุการณ์) หรือ downtime_minutes
  3. ปรับ horizon (7-90 วัน, ค่าเริ่มต้น 14)
  4. คลิก "Run Forecast"
  5. ดูผลในตาราง (แสดง actual ล่าสุด + forecast)
  6. Download ไฟล์ forecast_{metric}_from_ui.csv
• ฟีเจอร์: ใช้ Prophet ถ้าติดตั้งได้, มิฉะนั้นใช้ naive forecast
• ผลลัพธ์: CSV กับคอลัมน์ date และ predicted values

5. Classification

• วัตถุประสงค์: จัดประเภทสาเหตุของเหตุการณ์ (Root-Cause Classification)
• วิธีใช้:
  1. อัปโหลดไฟล์ CSV
  2. เลือก "Run weak-labeling using HF" ถ้าต้องการใช้ LLM เสริม labels (ต้องมี HF_TOKEN)
  3. เลือก "Run GridSearch" สำหรับ hyperparameter tuning (ช้ากว่า)
  4. คลิก "Train Classifier"
  5. ดู classification report ใน textbox
  6. Download โมเดล rf_cause_pipeline.joblib และ predictions predictions_cause.csv
• ฟีเจอร์: Feature engineering, RandomForest pipeline, optional GridSearchCV, weak-labeling ด้วย HF Router
• ผลลัพธ์: โมเดล trained และ predictions CSV

หมายเหตุ

• เป็น prototype: ฟีเจอร์อาจไม่สมบูรณ์หรือปรับปรุงได้
• สำหรับ deployment บน Hugging Face Spaces: อัปโหลดโค้ดและตั้งค่า HF_TOKEN ใน Secrets
• ข้อมูลตัวอย่าง: data/data.csv มีคอลัมน์เช่น EventNumber, OutageDateTime, CauseType, etc.
• ถ้ามีปัญหา: ตรวจสอบ console สำหรับ errors และ ensure Python environment ถูกต้อง

การพัฒนาเพิ่มเติม

• เพิ่ม interactive maps สำหรับ anomalies
• SHAP explanations สำหรับ models
• Human-in-the-loop สำหรับ weak labels
• Alerting และ real-time processing