# 🎯 自動格式推斷系統

> ConvertX-CN 透過本地小模型與行為學習，自動推斷使用者最可能的格式搜尋與引擎選擇，並在不干擾操作自由的前提下，提前完成引擎準備以降低轉檔延遲。

## ✨ 核心亮點

- **🧠 智能推斷**：基於檔案特徵 + 使用者歷史行為，自動預測最可能的目標格式
- **⚡ 引擎預調用**：高信心度時提前 warm-up 引擎，降低冷啟動延遲
- **📊 持續學習**：每次轉檔都會更新使用者偏好模型，推薦越用越準
- **🔒 完全本地**：不使用任何付費 API，所有推斷在本地完成
- **🎛️ 無干擾設計**：使用者可隨時點擊 X 清除推薦，系統會記錄為負樣本

## 🏗️ 系統架構

```
[檔案上傳] → [特徵抽取] → [格式候選生成] → [格式預測模型] → [引擎預測模型] → [預調用]
                                ↑                    ↑                ↑
                           規則配置             使用者 Profile       引擎能力矩陣
```

## 📁 模組結構

```
src/inference/
├── index.ts                 # 統一導出
├── inferenceService.ts      # 推斷服務主入口
├── featureExtraction.ts     # 檔案特徵抽取
├── formatCandidateRules.ts  # 格式候選規則配置
├── formatPredictionModel.ts # 格式預測模型
├── enginePredictionModel.ts # 引擎預測模型
├── behaviorStore.ts         # 使用者行為資料儲存
└── engineWarmup.ts          # 引擎預調用管理

public/
└── inference.js             # 前端推斷整合

src/pages/
└── inference.tsx            # 推斷 API 端點
```

## 🔧 使用方式

### 後端 API

```typescript
// 請求格式推斷
POST /inference/predict
{
  "ext": "jpg",
  "file_size_kb": 2400
}

// 回應
{
  "success": true,
  "data": {
    "format": {
      "search_format": "png",
      "confidence": 0.82,
      "top_k": [
        { "format": "png", "score": 0.82 },
        { "format": "webp", "score": 0.75 }
      ]
    },
    "engine": {
      "engine": "vips",
      "confidence": 0.88,
      "should_warmup": true
    },
    "should_auto_fill": true
  }
}
```

### 前端整合

```javascript
// 上傳檔案後自動觸發推斷
if (window.inferenceModule) {
  const result = await inferenceModule.requestFormatInference("jpg", 2400);
  if (result?.should_auto_fill) {
    inferenceModule.autoFillInferredFormat(result.format.search_format);
  }
}
```

## 📊 資料 Schema

### 轉檔事件

```json
{
  "event": "conversion_completed",
  "user_id": 123,
  "input_ext": "jpg",
  "searched_format": "png",
  "selected_engine": "vips",
  "success": true,
  "duration_ms": 820
}
```

### 使用者 Profile

```json
{
  "user_id": 123,
  "format_preferences": {
    "jpg->png": 0.71,
    "jpg->webp": 0.19
  },
  "engine_preferences": {
    "png": { "vips": 0.65, "imagemagick": 0.3 }
  },
  "recent_formats": ["png", "webp", "pdf"]
}
```

## ⚙️ 配置選項

在 `InferenceServiceConfig` 中可配置：

| 選項                        | 預設值 | 說明               |
| --------------------------- | ------ | ------------------ |
| `formatConfidenceThreshold` | 0.4    | 格式推斷最低信心度 |
| `engineConfidenceThreshold` | 0.5    | 引擎推斷最低信心度 |
| `enableWarmup`              | true   | 是否啟用預調用     |
| `warmupConfidenceThreshold` | 0.7    | 預調用觸發閾值     |

## 🧪 驗收測試

- ✅ 使用者歷史偏好 `jpg→png` → 新 jpg 自動填 `png`
- ✅ 高解析 jpg → vips 優先於 imagemagick
- ✅ 小圖示 jpg → imagemagick 優先
- ✅ 不會在圖片流程預調用 ffmpeg
- ✅ 使用者點 X → 推斷被記為負樣本
- ✅ 多次使用後推薦準確率提升