# 用 YOLOv8 實作身分證欄位偵測（從資料到部署的完整教學）

本文將帶你從零開始，完成以 YOLOv8 偵測身分證上各欄位（姓名、身分證號、生日等）的完整流程。內容包含：資料收集與標註、資料夾結構設計、data.yaml 與 classes.txt 編寫、訓練與驗證、推論與常見問題排解，並提供實用的最佳實務與注意事項，協助你更穩定、可重現地完成專案。

---

## 1. 前置準備與技術背景

- YOLOv8 簡介：YOLO（You Only Look Once）是一系列即時目標偵測模型。YOLOv8 由 Ultralytics 發佈，支援偵測、分類、分割等任務，其中 detect 任務最適合本教學（偵測身分證上多個欄位框）。
- 任務定義：我們的任務是「欄位偵測」（object detection），將身分證上的關鍵區域用邊界框框出，如 name、id_number 等，後續可串接 OCR 擷取文字。
- 工具清單：
- Python 3.8+、pip
- Ultralytics（YOLOv8 套件）
- 影像標註工具：LabelImg（設定 YOLO 格式）
- 可選：Git、VS Code、CUDA（若使用 GPU）

> 法規與隱私提醒：身分證屬於敏感個資。請確保資料來源合法、去識別化處理妥當，並僅在合規與授權範圍內使用與分享模型與資料。

---

## 2. 專案資料夾結構與用途

專案根目錄：`your-dataset/`

- images/train/：訓練影像（.jpg/.png）
- images/val/：驗證影像（與訓練集分離）
- labels/train/：每張訓練影像對應的標註 .txt（LabelImg 產生）
- labels/val/：每張驗證影像對應的標註 .txt
- data.yaml：YOLOv8 讀取的資料設定檔
- classes.txt：標籤定義（供 LabelImg 選單與順序參考）

範例（樹狀圖）：

your-dataset/
 ├─ images/
 │   ├─ train/
 │   │   ├─ 0001.jpg
 │   │   └─ 0002.jpg
 │   └─ val/
 │       ├─ 1001.jpg
 │       └─ 1002.jpg
 └─ labels/
     ├─ train/
     │   ├─ 0001.txt
     │   └─ 0002.txt
     └─ val/
         ├─ 1001.txt
         └─ 1002.txt

---

## 3. 標籤定義與檔案格式

- classes.txt（順序即為類別 id 對應）：

name
id_number
birthday
sex
Issue_date
national_flag
id_photo
watermark

- YOLO 標註 .txt（每張影像一個檔）格式：`class_id x_center y_center width height`，座標皆為「相對值」（0~1），相對於影像寬高。
- 例如：`1 0.523 0.612 0.420 0.110` 表示類別 id=1（id_number），中心點 (0.523W, 0.612H)，框寬 0.420W、框高 0.110H。

---

## 4. data.yaml 編寫（與 classes 對齊）

請確保 names 與 classes.txt 的順序完全一致：

path: ./your-dataset               # 修改為你的實際資料集根路徑
train: images/train
val: images/val

names:
  0: name
  1: id_number
  2: birthday
  3: sex
  4: Issue_date
  5: national_flag
  6: id_photo
  7: watermark

常見錯誤：
- names 順序與 classes.txt 不一致（會造成類別對不上）。
- path 寫成絕對路徑但搬移專案後失效，建議使用相對路徑（如上）。

---

## 5. 使用 LabelImg 進行標註（YOLO 模式）

1) 安裝與啟動：
- 依系統安裝 LabelImg 後，在專案根目錄執行：

labelImg

2) 重要設定：
- 左側模式切換為 YOLO。確保 classes.txt 已載入且順序正確。
- 標註時務必注意：
- 邊界框需緊貼欄位區域，避免過多背景。
- 不確定的欄位先跳過，維持標註品質一致性。

3) 存檔：
- 每張影像存檔會在 labels 對應目錄下生成同名 .txt。

---

## 6. 安裝與訓練 YOLOv8

安裝 Ultralytics：

pip install ultralytics

開始訓練（偵測任務）：

yolo detect train \
  data=your-dataset/data.yaml \
  model=yolov8n.pt \
  epochs=100 imgsz=640 batch=16

參數說明：
- model：可先用 yolov8n.pt（Nano）嘗試，資源占用小；表現不足再升級至 s/m/l/x。
- epochs：訓練回合數（先從 100 起步，觀察收斂）。
- imgsz：輸入影像尺寸（常見 640；若欄位很小可嘗試 800）。
- batch：依 GPU 記憶體調整。

訓練輸出：`runs/detect/train/weights/best.pt`（最佳權重）。

---

## 7. 驗證與推論

驗證 model：

yolo detect val \
  model=runs/detect/train/weights/best.pt \
  data=your-dataset/data.yaml

單張圖片推論並存檔：

yolo detect predict \
  model=runs/detect/train/weights/best.pt \
  source=path/to/test.jpg save=True

輸出會在 `runs/detect/predict/` 生成含框的結果影像。

---

## 8. 常見問題（FAQ）與注意事項

- Q1：預測框不穩定或飄移？
- A：增加資料量與多樣性（不同光線、角度、機型），並確保標註一致；提高 imgsz、嘗試更大模型（yolov8s/m），或延長 epochs。
- Q2：欄位很小容易漏檢？
- A：提高解析度（imgsz 800/1024）、加強小物體的訓練樣本、確保框貼近欄位、嘗試 mosaic/augment（內建資料增強）。
- Q3：驗證 mAP 低但訓練損失低？
- A：資料分布差異或過擬合，檢查 train/val 分割是否合理；提升驗證集數量與多樣性；開啟訓練時的資料增強。
- Q4：類別對不上（預測名稱錯亂）？
- A：確認 data.yaml 的 names 與 classes.txt 順序完全一致，且標註工具使用的 classes.txt 與訓練時一致。
- Q5：如何串接 OCR？
- A：推論輸出框座標後，裁切各欄位影像，交給 OCR（如 Tesseract、Google OCR、PaddleOCR）處理；注意前處理（去噪、二值化）能提升準確度。
- 法規與隱私：
- 僅使用合法來源或合成資料；若需展示，務必打碼或使用虛構樣本。

---

## 9. 最佳實務與專案建議

- 固定隨機種子（reproducibility）：在訓練腳本或環境設定中固定 random seed，以利結果重現。
- 清楚的資料分割：避免相同人、同張證件同時出現在 train 與 val。
- 統一色彩與尺寸前處理：可在載入前對尺寸與顏色做一致化，減少模型負擔。
- 版本控管與實驗紀錄：紀錄 data.yaml 版本、模型超參數、訓練日誌與指標（mAP、Precision、Recall）。
- 部署建議：將 best.pt 轉為 ONNX/TensorRT，可在邊緣裝置或服務端加速推論。

---

## 10. 參考指令速查（可直接複製）

安裝：

pip install ultralytics

訓練：

yolo detect train data=your-dataset/data.yaml model=yolov8n.pt epochs=100 imgsz=640 batch=16

驗證：

yolo detect val model=runs/detect/train/weights/best.pt data=your-dataset/data.yaml

推論：

yolo detect predict model=runs/detect/train/weights/best.pt source=path/to/test.jpg save=True

---

以上教學完成後，你應能得到可用的欄位偵測模型，並可延伸至 OCR 擷取與後續資料處理流程。祝開發順利！