Upload readme.txt

readme.txt

@@ -0,0 +1,254 @@
+---
+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 討論。
+
+---
+
+**⚡ 提示**: 首次使用建議先閱讀「使用說明」頁面，了解完整的操作流程！