README.md

---
title: Llama NBCD Second Fine-tuning Platform
emoji: 🦙
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "4.44.0"
app_file: app.py
pinned: false
license: mit
---

# 🦙 Llama NBCD 二次微調完整平台

互動式 Llama 模型二次微調和預測平台，支持多種參數高效微調方法 (LoRA, AdaLoRA, Adapter, BitFit, Prompt Tuning)。

## 🌟 功能特色

- 🎯 **第一次微調**: 從純 Llama 開始訓練，支持 5 種 PEFT 方法
- 🔄 **二次微調**: 基於第一次模型用新數據繼續訓練
- 📊 **Baseline 比較**: 自動比較未微調 vs 微調模型的效果
- 🧪 **新數據測試**: 同時比較 3 個模型在新數據上的表現
- 🎨 **指標選擇**: 可選擇最佳化指標（F1、Accuracy、Precision、Recall、Sensitivity、Specificity）
- 🔮 **即時預測**: 訓練後可直接預測新樣本
- 💾 **模型管理**: 自動儲存和管理多個訓練模型
- 🧹 **記憶體管理**: 自動清理 GPU 記憶體，避免 OOM

## 📋 使用方式

### 📑 頁面結構 (5個Tab)

#### 1️⃣ 第一次微調

1. **上傳資料**: CSV 檔案需包含 `Text` 和 `label` 欄位
2. **選擇模型**: 設定 Llama 模型（預設: meta-llama/Llama-3.2-1B）
3. **選擇微調方法**:
   - ✅ **LoRA**: 通用，效果好
   - ✅ **AdaLoRA**: 自適應，效果更優
   - ✅ **Adapter**: 適合多任務
   - ✅ **BitFit**: 極快速，參數最少
   - ✅ **Prompt Tuning**: 適合小數據集
   - ❌ **Prefix Tuning**: 暫不支持（兼容性問題）
4. **設定參數**: 調整資料平衡、訓練參數和 PEFT 參數
5. **開始訓練**: 點擊「開始第一次微調」按鈕
6. **查看結果**: 比較未微調和微調模型的表現

#### 2️⃣ 二次微調

1. **選擇基礎模型**: 從下拉選單選擇已訓練的第一次微調模型
2. **上傳新資料**: 上傳新的訓練數據 CSV
3. **調整參數**: 
   - ⚠️ 微調方法自動繼承第一次
   - 建議 Epochs 更少 (3-5 輪)
   - 建議 Learning Rate 更小 (5e-5)
4. **開始訓練**: 點擊「開始二次微調」按鈕
5. **查看結果**: 查看二次微調後的表現

#### 3️⃣ 新數據測試

1. **上傳測試數據**: 上傳測試用的 CSV 檔案
2. **選擇要比較的模型**:
   - 純 Llama (Baseline) - 可選
   - 第一次微調模型 - 可選
   - 第二次微調模型 - 可選
3. **開始測試**: 點擊「開始測試」按鈕
4. **查看結果**: 並排比較所有選擇的模型在新數據上的表現

#### 4️⃣ 模型預測

1. **選擇模型**: 從下拉選單選擇已訓練的模型
2. **輸入文本**: 輸入要預測的文本
3. **查看結果**: 同時顯示未微調和微調模型的預測結果

#### 5️⃣ 使用說明

- 完整的操作流程說明
- 微調方法詳細比較
- 參數調整建議
- 注意事項和常見問題

## 🔐 重要設定

### Hugging Face Token

如果要使用 Llama 模型，需要：

1. 在 [Hugging Face Settings](https://huggingface.co/settings/tokens) 創建 Token
2. 在 Space 的 Settings → Repository secrets 中加入：
   - Name: `HF_TOKEN`
   - Value: 你的 token

或在本地設定環境變數：
```bash
export HF_TOKEN=your_token_here
```

## ⚙️ 預設參數

### 第一次微調
- **訓練輪數**: 3
- **批次大小**: 4
- **學習率**: 1e-4
- **LoRA rank**: 16
- **LoRA alpha**: 32
- **目標樣本數**: 700 筆/類別
- **類別權重**: 啟用

### 二次微調（建議）
- **訓練輪數**: 3-5（比第一次少）
- **批次大小**: 4
- **學習率**: 5e-5（比第一次小）
- **其他參數**: 自動繼承第一次

## 📊 資料格式

CSV 檔案需包含以下欄位：

```csv
Text,label
"Patient data text here...",0
"Another patient data...",1
```

或

```csv
text,Label
"Patient data text here...",0
"Another patient data...",1
```

- `Text`/`text`: 文本資料
- `Label`/`label`: 標籤 (0 或 1)

## 🎯 微調方法比較

| 方法 | 參數量 | 記憶體 | 訓練速度 | 效果 | 適用場景 |
|------|--------|--------|----------|------|----------|
| **LoRA** | 很少 (~1%) | 低 | 快 | 良好 | 通用，效果好 |
| **AdaLoRA** | 很少 (~1%) | 低 | 快 | 優秀 | 自適應，效果更優 |
| **Adapter** | 少 (~2-5%) | 低 | 中 | 良好 | 多任務學習 |
| **BitFit** | 極少 (~0.1%) | 極低 | 極快 | 可接受 | 快速微調 |
| **Prompt Tuning** | 極少 (可調) | 極低 | 快 | 良好 | 小數據集 |

## 💡 二次微調建議

### 適用場景

1. **領域適應**: 第一次用通用醫療數據，第二次用特定醫院數據
2. **增量學習**: 隨時間增加新病例數據
3. **數據稀缺**: 先用大量相關數據預訓練，再用少量目標數據微調

### 參數調整原則

- **Epochs**: 第二次建議 3-5 輪（第一次通常 5-8 輪）
- **Learning Rate**: 第二次建議 5e-5（第一次通常 1e-4）
- **避免**: 第二次不要用太大的學習率，會破壞已學習的知識

## 📈 評估指標說明

- **F1 Score**: 精確率和召回率的調和平均，平衡指標
- **Accuracy**: 整體準確率
- **Precision**: 預測為正類中的準確率
- **Recall**: 實際正類中被正確識別的比例
- **Sensitivity**: 敏感度，等同於 Recall
- **Specificity**: 特異性，正確識別負類的能力

## ⚠️ 注意事項

- 訓練時間依資料量和硬體而定（通常 10-30 分鐘）
- 需要 Hugging Face Token 才能下載 Llama 模型
- **GPU 訓練強烈建議**: CPU 訓練會非常慢
- 資料量建議: 每個類別至少 500 筆資料
- 二次微調自動繼承第一次的微調方法，無法更改
- Prefix Tuning 因 PEFT 庫兼容性問題暫不支持，請使用 Prompt Tuning 替代

## 🔧 已知問題與解決方案

### ✅ 已修復
- **AdaLoRA**: 簡化配置參數，避免版本兼容性問題
- **BitFit**: 正確處理 gradient 設置，包含分類頭訓練
- **參數顯示**: 各方法現在會正確顯示專屬參數界面

### ❌ 暫不支持
- **Prefix Tuning**: 因 PEFT 版本與 transformers 的 DynamicCache 不兼容
  - **錯誤**: `'DynamicCache' object has no attribute 'key_cache'`
  - **替代方案**: 使用 Prompt Tuning，功能類似且更穩定
  - **預計修復**: 等待 PEFT 庫更新

## 🚀 快速開始

```bash
# 1. 安裝依賴
pip install -r requirements.txt

# 2. 設定 HF Token (可選，但建議設定)
export HF_TOKEN=your_token_here

# 3. 啟動應用
python app.py

# 4. 打開瀏覽器訪問
# http://localhost:7860
```

## 📁 專案結構

```
.
├── app.py                          # 主程式
├── requirements.txt                # 依賴套件
├── README.md                       # 說明文件
├── saved_llama_models_list.json   # 模型列表（自動生成）
└── llama_nbcd_*/                   # 訓練模型目錄（自動生成）
```

## 💻 系統需求

### 最低需求
- **CPU**: 4 核心以上
- **RAM**: 16GB 以上
- **硬碟**: 20GB 可用空間

### 建議配置
- **GPU**: NVIDIA GPU with 16GB+ VRAM (如 V100, A100, RTX 3090/4090)
- **RAM**: 32GB 以上
- **硬碟**: 50GB 可用空間（用於儲存多個模型）

### 無 GPU 訓練
- 可以使用 CPU 訓練，但速度會非常慢（可能需要數小時）
- 建議使用 Google Colab 或 HuggingFace Spaces 的免費 GPU

## 🤝 貢獻

歡迎提交 Issue 和 Pull Request！

## 📝 License

MIT License

## 🙏 致謝

- [Hugging Face Transformers](https://github.com/huggingface/transformers)
- [PEFT](https://github.com/huggingface/peft)
- [Gradio](https://github.com/gradio-app/gradio)
- [Meta Llama](https://ai.meta.com/llama/)

## 📧 聯繫方式

如有問題或建議，請開 Issue 討論。

---

**⚡ 提示**: 首次使用建議先閱讀「使用說明」頁面，了解完整的操作流程！