feat: implement automatic format inference service with candidate generation and prediction model

- Add formatCandidateRules.ts to define rules for generating format candidates based on file features. - Introduce formatPredictionModel.ts to predict the most likely target format based on user behavior and file features. - Create inferenceService.ts to integrate all inference modules and provide a unified inference API. - Develop inference.tsx as an API endpoint for frontend calls to predict formats and engines based on file extensions. - Implement logging for conversion events and dismissals, along with user profile retrieval. - Ensure warmup management for engine predictions and provide status checks.
2026-01-26 12:47:16 +08:00 · 2026-01-26 12:47:16 +08:00 · 6d948b0873
commit 6d948b0873
parent 1173d505f7
18 changed files with 3710 additions and 14 deletions
--- a/docs/功能說明/自動格式推斷.md
+++ b/docs/功能說明/自動格式推斷.md
@ -0,0 +1,137 @@
+# 🎯 自動格式推斷系統
+
+> 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 → 推斷被記為負樣本
+- ✅ 多次使用後推薦準確率提升