Evaluator YAML

Evaluator 模組的 YAML 設定檔案格式。

使用範例

請點擊下方按鈕在 Colab 中執行範例：

建議評估流程

我們建議採用以下評估流程，確保合成資料符合需求：

1. 評估流程概覽

flowchart TD
    Start([開始評估])
    Diagnostic{Step 1:<br/>資料診斷性通過?}
    DiagnosticFail[資料結構問題<br/>需檢查合成過程]
    Privacy{Step 2:<br/>隱私保護力通過?}
    PrivacyFail[隱私風險過高<br/>需調整合成參數]
    Purpose{Step 3:<br/>合成資料使用目的?}
    Release[情境 A:<br/>資料釋出<br/>無特定下游任務]
    Task[情境 B:<br/>特定任務應用<br/>資料增益/模型訓練]
    FidelityFocus[評估重點：<br/>追求最高保真度]
    UtilityFocus[評估重點：<br/>追求高實用性<br/>保真度達標即可]

    Start --> Diagnostic
    Diagnostic -->|否| DiagnosticFail
    Diagnostic -->|是| Privacy
    Privacy -->|否| PrivacyFail
    Privacy -->|是| Purpose
    Purpose -->|A| Release
    Purpose -->|B| Task
    Release --> FidelityFocus
    Task --> UtilityFocus

    style Start fill:#e1f5fe
    style DiagnosticFail fill:#ffcdd2
    style PrivacyFail fill:#ffcdd2
    style FidelityFocus fill:#c8e6c9
    style UtilityFocus fill:#c8e6c9

2. 資料診斷性標準

flowchart TD
    Start([資料診斷性評估])
    Method[評估方法:<br/>sdmetrics-diagnosticreport]
    Check{分數 ≈ 1.0?}
    Pass[診斷通過]
    Fail[需檢查合成過程]

    Start --> Method
    Method --> Check
    Check -->|是| Pass
    Check -->|否| Fail

    style Start fill:#e1f5fe
    style Pass fill:#c8e6c9
    style Fail fill:#ffcdd2
    style Method fill:#fff3e0

3. 隱私保護力標準

flowchart TD
    Start([隱私保護力評估])
    Method[評估方法:<br/>anonymeter-singlingout<br/>anonymeter-linkability<br/>anonymeter-inference]
    Check{風險 < 0.09?}
    Pass[保護力通過]
    Fail[需調整合成參數]

    Start --> Method
    Method --> Check
    Check -->|是| Pass
    Check -->|否| Fail

    style Start fill:#e1f5fe
    style Pass fill:#c8e6c9
    style Fail fill:#ffcdd2
    style Method fill:#fff3e0

4. 資料保真度標準

flowchart TD
    Start([資料保真度評估])
    Method[評估方法:<br/>sdmetrics-qualityreport]
    Check{分數 ≥ 0.75?}
    Pass[保真度達標]
    Fail[需提升保真度]

    Start --> Method
    Method --> Check
    Check -->|是| Pass
    Check -->|否| Fail

    style Start fill:#e1f5fe
    style Pass fill:#c8e6c9
    style Fail fill:#fff3e0
    style Method fill:#fff3e0

5. 資料實用性標準

flowchart TD
    Start([資料實用性評估])
    Method[評估方法:<br/>mlutility]
    TaskType{任務類型與標準}
    Classification{分類 XGBoost:<br/>F1 ≥ 0.7?}
    Regression{迴歸 XGBoost:<br/>R² ≥ 0.7?}
    Clustering{聚類 K-means:<br/>輪廓係數 ≥ 0.5?}
    Pass[實用性達標]
    Fail[需提升模型效用]

    Start --> Method
    Method --> TaskType
    TaskType -->|分類| Classification
    TaskType -->|迴歸| Regression
    TaskType -->|聚類| Clustering
    Classification -->|是| Pass
    Classification -->|否| Fail
    Regression -->|是| Pass
    Regression -->|否| Fail
    Clustering -->|是| Pass
    Clustering -->|否| Fail

    style Start fill:#e1f5fe
    style Pass fill:#c8e6c9
    style Fail fill:#fff3e0
    style Method fill:#fff3e0

圖例說明：

• 淺藍色方框：開始/結束點
• 白色方框：評估步驟
• 菱形：決策點
• 綠色方框：成功結果
• 紅色方框：失敗狀態，需要採取行動
• 黃色方框：需要改進
• 橙色方框：評估方法

1. 基礎評估（必要）

首先確認資料的有效性和隱私保護力：

2. 目標導向評估

通過基礎評估後，根據合成資料的使用目的選擇評估重點：

情境 A：資料釋出（無特定下游任務）

若合成資料將對外釋出，應追求最高的保真度：

Splitter:
  external_split:
    method: custom_data
    filepath:
      ori: benchmark://adult-income_ori
      control: benchmark://adult-income_control
    schema:
      ori: benchmark://adult-income_schema
      control: benchmark://adult-income_schema
Synthesizer:
  external_data:
    method: custom_data
    filepath: benchmark://adult-income_syn
    schema: benchmark://adult-income_schema
Evaluator:
  # Step 1: 資料有效性診斷（應接近 1.0）
  validity_check:
    method: sdmetrics-diagnosticreport
  # Step 2: 隱私保護力評估（風險應 < 0.09）
  singling_out_risk:
    method: anonymeter-singlingout
    n_attacks: 400
    max_attempts: 4000
  linkability_risk:
    method: anonymeter-linkability
    aux_cols:
      -
        - workclass
        - education
        - occupation
        - race
        - gender
      -
        - age
        - marital-status
        - relationship
        - native-country
        - income
  inference_risk:
    method: anonymeter-inference
    secret: income
  # 重點：追求高保真度（分數越高越好）
  fidelity_assessment:
    method: sdmetrics-qualityreport
  # 實用性評估可選（非必要）

情境 B：特定任務應用（資料增益、模型訓練等）

若合成資料用於特定機器學習任務，應追求高實用性：

Splitter:
  external_split:
    method: custom_data
    filepath:
      ori: benchmark://adult-income_ori
      control: benchmark://adult-income_control
    schema:
      ori: benchmark://adult-income_schema
      control: benchmark://adult-income_schema
Synthesizer:
  external_data:
    method: custom_data
    filepath: benchmark://adult-income_syn
    schema: benchmark://adult-income_schema
Evaluator:
  # Step 1: 資料有效性診斷（應接近 1.0）
  validity_check:
    method: sdmetrics-diagnosticreport
  # Step 2: 隱私保護力評估（風險應 < 0.09）
  singling_out_risk:
    method: anonymeter-singlingout
    n_attacks: 400
    max_attempts: 4000
  linkability_risk:
    method: anonymeter-linkability
    aux_cols:
      -
        - workclass
        - education
        - occupation
        - race
        - gender
      -
        - age
        - marital-status
        - relationship
        - native-country
        - income
  # 保真度達標即可（≥ 0.75）
  quality_assessment:
    method: sdmetrics-qualityreport
  # 重點：追求高實用性（依任務類型評估）
  ml_utility_assessment:
    method: mlutility
    task_type: classification  # 或 regression/clustering
    target: income

主要參數

• method (string, 必要參數)
  • 評估方法名稱
  • 支援的方法見下方表格

支援的評估方法

建議標準說明

¹ 保真度標準（分數 ≥ 0.75）：基於統計分佈相似度

² 有效性標準（分數 ≈ 1.0）：資料結構完整性檢查

³ 隱私風險標準（風險 < 0.09）：基於 PDPC Singapore 指引

⁴ 實用性標準（依任務類型）：

• 分類任務（XGBoost）：F1 ≥ 0.7
• 迴歸任務（XGBoost）：R² ≥ 0.7
• 聚類任務（K-means）：輪廓係數 ≥ 0.5

預設方法：當 method: default 時，系統會自動執行 sdmetrics-qualityreport 評估資料保真度。

閾值調整：以上建議標準為一般參考值，請根據您的具體應用場景和風險容忍度調整適當的閾值。各指標的詳細理論基礎和參考文獻請見對應子文件。

執行說明

• 大型資料集的評估可能需要較長時間，特別是 Anonymeter 方法
• 建議依序執行評估，確保前置條件達標後再進行後續評估