convertor/docs/功能說明/自動格式推斷.md

🎯 自動格式推斷系統

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

// 請求格式推斷
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
  }
}

前端整合

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

📊 資料 Schema

轉檔事件

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

使用者 Profile

{
  "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 → 推斷被記為負樣本
• ✅ 多次使用後推薦準確率提升