
---

# 🧠 異常検知システム (Embedding版)

> **LLMのEmbeddingを活用した汎用異常検知フレームワーク**
> 正常データのベクトル空間を学習し、新たなデータとの距離で異常を検出します。

---

## 📘 システム概要

このシステムは以下の3段階で構成されています：

1. **試験データ生成**：ネットワーク・ログ・センサーなどの模擬データをCSV形式で生成
2. **ベースライン学習**：正常データをEmbedding化して特徴ベクトル空間を構築
3. **異常検知**：新規データをEmbedding変換し、ベースラインと比較して異常度を算出

---

## 🧩 システム構成図

```mermaid
graph TD
  A[📄 generate_test_data.py<br/>試験データ生成] -->|正常データ| B[🧠 train_baseline.py<br/>Embedding学習]
  A -->|異常含むデータ| C[🔍 detect_anomaly_unified.py<br/>異常検知実行]
  B -->|ベースライン| C
  C --> D[📊 検知結果出力<br/>標準出力]
    subgraph DataFlow["💾 データ"]
        E1[data/train_data_*.csv]
        E2[data/test_data_*.csv]
        E3[baseline/*.npz]
        E4[data/detect_result_*.csv]
    end
    
    A -.-> E1
    A -.-> E2
    B -.-> E3
    C -.-> E4
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#ffe1f5
    style D fill:#e1ffe1
```

---

## ⚙️ 環境要件

| 項目      | 内容                                               |
| ------- | ------------------------------------------------ |
| Python  | 3.10以上                                            |
| 必須ライブラリ | `numpy`, `pandas`, `requests`                    |
| LLM環境   | [Ollama](https://ollama.ai/) （例: `ollama serve`） |
| 推奨モデル   | `llama3.2:1b` または `llama3.2:3b`                  |

---

## 🧱 ディレクトリ構造

```
project_root/
├── train_baseline.py          # 正常データのEmbedding学習
├── detect_anomaly_unified.py  # 異常検知スクリプト
├── generate_test_data.py      # テストデータ生成
├── data/                      # CSV入出力ディレクトリ
│   ├── train_data_*.csv
│   ├── test_data_*.csv
│   └── detect_data_*.csv
└── baseline/                  # 学習済みベースライン
    ├── baseline_xxx.npz
    └── baseline_xxx_metadata.json
```

---

## 🧪 ステップ別の使用例

### ① 試験データの生成

```bash
python generate_test_data.py --type network --count 100 --anomaly-rate 5
```

| オプション            | 内容                                 |
| ---------------- | ---------------------------------- |
| `--type`         | データ種類 (`network`, `log`, `sensor`) |
| `--count`        | 生成件数                               |
| `--anomaly-rate` | 異常データ割合（％）                         |

生成されるファイル：

```
data/train_data_network_100_5.csv
data/test_data_network_100_5.csv
```

---

### ② 正常データのベースライン学習

```bash
python train_baseline.py --input data/train_data_network_100_5.csv
```

オプション例：

```bash
python train_baseline.py \
  --input data/train_data_log_150_10.csv \
  --model llama3.2:1b \
  --text-columns timestamp,level,event,detail
```

出力：

```
baseline/train_data_network_100_5.npz
baseline/train_data_network_100_5_metadata.json
```

---

### ③ 異常検知の実行

```bash
python detect_anomaly_unified.py \
  --input data/test_data_network_100_5.csv \
  --baseline baseline/train_data_network_100_5.npz
```

結果例：

```
✓ 検知結果: 正常 95件, 異常 5件
出力: data/detect_result_network_100_5.csv
```

---

## 🔍 異常検知の仕組み（概念図）

```mermaid
  flowchart TD
  subgraph 学習
  A[正常データ群] -->|Embedding変換| B[ベクトル空間にマッピング]
  B --> C[平均・分散を学習]
  end
	  subgraph 異常検知
	    D[新規データ] -->|Embedding変換| E[距離計算]
	    E -->|類似度が低い| F[🚨 異常判定]
	    E -->|類似度が高い| G[✅ 正常判定]
	  end
  C --> E

```

---

## 🧾 ベースラインファイルの内容

| ファイル             | 内容                              |
| ---------------- | ------------------------------- |
| `.npz`           | Embeddingデータ（mean/std/median含む） |
| `_metadata.json` | 学習条件・統計情報を記録                    |

```json
{
  "model_name": "llama3.2:3b",
  "train_count": 70,
  "embedding_dim": 4096,
  "success_rate": 100.0,
  "trained_at": "2025-10-20T12:34:56"
}
```

---

## 📊 出力結果例

| timestamp           | src_ip       | dst_ip         | protocol | 判定      | 類似度  |
| ------------------- | ------------ | -------------- | -------- | ------- | ---- |
| 2025-10-20 10:00:00 | 192.168.1.12 | 8.8.8.8        | HTTPS    | normal  | 0.98 |
| 2025-10-20 12:30:00 | 192.168.1.33 | 185.220.101.22 | TCP      | anomaly | 0.42 |

---

## ⚠️ 注意事項

* Ollamaサーバーを起動していないとEmbedding取得に失敗します。
* NaNや欠損値は自動的に`null`に変換されます。
* 異常判定は距離閾値に基づき、モデルによって結果が変動します。

---

## 🧩 応用例

* IoTセンサー異常監視
* ネットワーク侵入検知
* システムログの異常行動検出

---

## 📜 ライセンス
このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。
本プログラムは研究・学習目的での利用を想定しています。
商用利用時は使用するLLM（例: `llama3`）のライセンス条項をご確認ください。

---
