資料清洗與分類腳本 (extract_data.py) 功能說明

[bubbleee030]

資料清洗與分類腳本 (extract_data.py) 功能說明

最後更新日期: 2025-07-23

---

🎯 總體目標 (Overall Goal)

此腳本的主要目標是自動化處理 eval_results 目錄下的實驗數據。它會遍歷所有子目錄，從 .json 與 .jsonl 檔案中提取所需資料，並執行一系列的驗證、去重與分類任務，最終產出乾淨、可用於後續分析的結構化資料。

---

⚙️ 核心功能流程 (Core Workflow)

整個處理流程分為三大步驟，依序執行：

步驟 1：資料提取與格式驗證 (extract_and_validate)

此階段負責從原始檔案中讀取資料，並進行初步的篩選與驗證。

• 檔案遍歷: 從指定的根目錄 (./eval_results) 開始，遞迴搜尋所有 .json 及 .jsonl 檔案。
• 智慧篩選:
  • 透過檔名 (findMission) 解析出任務類型 (如 petition, od 等)。
  • 自動跳過檔名包含 raft 的檔案。
  • 從檔案路徑中解析出 genmodel 和 judgemodel 名稱。
• 資料提取:
  • .jsonl 檔案: 逐行讀取並解析為 JSON 物件。
  • .json 檔案: 讀取整個檔案，並特別提取 eval_result_from_first_iteration 欄位中的資料。
• 格式驗證:
  • 確保 full_output 欄位存在、非空，且不包含 "think" 字樣（可能是未處理的原始輸出）。
  • 驗證 full_output 包含所有必要的標籤 (如 【給分原因】, 【分數】 等)。
  • 確保 model_response 欄位存在且非空。
  • 不符合格式的資料會被記錄到 format_error.json 中，並在日誌中留下紀錄。

步驟 2：近似文本去重複 (find_and_remove_duplicates)

為了確保資料的獨特性，此步驟使用 SimHash 演算法 來找出並移除內容相似的資料。

• SimHash 計算: 為每一筆資料的 full_output 文本計算出一個 64-bit 的 SimHash 指紋。
• 相似度比較:
  • 透過計算兩個 SimHash 指紋之間的「漢明距離 (Hamming Distance)」來判斷文本相似度。
  • 若漢明距離小於或等於設定的閾值 (threshold=2)，則將其視為近似重複項。
• 移除重複: 保留先出現的資料，並將後出現的相似資料移除。
• 所有被移除的重複資料及其比對來源，都會被詳細記錄在 deduplicated_log.json 中。

步驟 3：語言與任務分類 (classify)

最後，將清理乾淨的資料進行最終分類。

• 簡繁體偵測:
  • 載入 simplified_chars.txt 字典檔。
  • 檢查每筆資料的 full_output 和 model_response 是否包含簡體字。
  • 若偵測到簡體字，會標記其語言為 simplified，並記錄觸發的字元與來源欄位。否則標記為 traditional。
• 任務分類: 根據步驟 1 解析出的 mission 類型進行分類。
• 資料分桶 (Bucketing):
  • 根據「語言」和「任務」的組合，將資料存放到不同的集合中 (例如 traditional_petition, simplified_qa 等)。
  • 所有分類結果會分別儲存成獨立的 JSON 檔案。

---

🚀 如何執行

1. 確保已安裝所有必要的 Python 套件 (pip install -r requirements.txt)。
2. 確認 simplified_chars.txt 檔案存在於同層目錄。
3. 將所有要處理的原始資料夾放置在 eval_results 目錄下。
4. 在終端機中執行以下指令：

   python extract_data.py

5. 等待程式執行完畢。

---

📂 輸出檔案結構

執行完畢後，所有產出的檔案都會被存放在 final_classified_output/ 目錄下，包含：

• [lang]_[mission].json: 分類好的主要資料檔，例如 traditional_od.json。
• classified_data_[lang].json: 按照簡繁體區分的完整資料，例如 classified_data_traditional.json。
• format_error.json: 所有因格式錯誤而被剔除的資料。
• deduplicated_log.json: 所有因內容近似而被移除的資料紀錄。

同時，腳本執行的詳細過程會記錄在 logs/ 目錄下的 .log 檔案中，方便追蹤與除錯。

---

💬 需要討論的事項

• @mentor：目前 SimHash 的 threshold 設為 2，想與您討論這個值的敏感度是否合適。
• ...