LISA 模型訓練與推論教學文件

適用環境：網格中心虛擬主機
APP：PyTorch (GPU A100)

---

📋 目錄

1. 專案簡介
2. 環境需求
3. Step 0: 環境建置
4. Step 1: 模型推論
5. Step 2: 模型訓練
6. 檔案結構說明

---

1. 專案簡介

LISA (Reasoning Segmentation via Large Language Model) 是一個結合大型語言模型 (LLM) 與圖像分割能力的模型，能夠根據自然語言描述進行推理式分割任務。

主要功能

• 🎯 語意分割：根據文字描述分割圖片中的目標物件
• 🧠 推理能力：支援複雜的推理式分割任務
• 💬 自然語言互動：可用自然語言詢問並獲得分割結果

模型架構

• 基礎模型：LLaVA-7B (視覺語言模型)
• 分割模組：SAM (Segment Anything Model)
• 訓練方式：LoRA (Low-Rank Adaptation)

---

2. 環境需求

硬體需求

軟體需求

---

3. 環境建置

📓 對應筆記本：0_create_env.ipynb

3.1 安裝 Miniconda

在網格中心 PyTorch A100 APP 的 Jupyter 環境中執行：

# 下載 Miniconda 安裝腳本
!wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh

# 安裝 Miniconda 到家目錄
!bash miniconda.sh -b -p $HOME/miniconda

# 初始化 conda
!$HOME/miniconda/bin/conda init bash

3.2 接受 Conda TOS

# 同意 Terms of Service
!$HOME/miniconda/bin/conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
!$HOME/miniconda/bin/conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r

3.3 建立 LISA 虛擬環境

# 建立 Python 3.10 環境
!$HOME/miniconda/bin/conda create -y -n lisa python=3.10

# 升級 pip 相關工具
!$HOME/miniconda/bin/conda run -n lisa pip install --upgrade pip setuptools wheel

# 安裝 git
!$HOME/miniconda/bin/conda run -n lisa conda install -y git

3.4 下載並安裝 LISA

# Clone LISA 專案
!$HOME/miniconda/bin/conda run -n lisa git clone https://github.com/dvlab-research/LISA.git

# 安裝官方 requirements
!$HOME/miniconda/bin/conda run -n lisa pip install -r LISA/requirements.txt

3.5 修正相依套件問題

由於網格中心環境的特殊性，需要調整部分套件：

# 重新安裝相容版本的 OpenCV 和 numpy
!$HOME/miniconda/bin/conda run -n lisa pip uninstall -y numpy opencv-python opencv-contrib-python opencv-python-headless
!$HOME/miniconda/bin/conda run -n lisa pip install "numpy<2.0.0" "opencv-python-headless<5.0.0.0"

# 安裝訓練所需額外套件
!$HOME/miniconda/bin/conda run -n lisa pip install "pydantic<2.0" "deepspeed==0.9.5" tensorboard scikit-image

# 移除 bitsandbytes (避免 CUDA 動態庫載入問題)
!$HOME/miniconda/bin/conda run -n lisa pip uninstall -y bitsandbytes

⚠️ 重要說明：移除 bitsandbytes 是因為網格中心 VM 環境無法正確載入 libcusparse/libcudart，會導致 DeepSpeed + LoRA merge 失敗。LISA 訓練流程不使用 4bit/8bit 量化，因此移除不影響功能。

---

4. 模型推論

📓 對應筆記本：1_inference.ipynb

4.1 下載測試圖片

# 建立資源目錄
!mkdir -p LISA/resources/imgs

# 下載官方範例圖片
!wget -O LISA/resources/imgs/example1.jpg https://raw.githubusercontent.com/dvlab-research/LISA/main/imgs/example1.jpg
!wget -O LISA/resources/imgs/example2.jpg https://raw.githubusercontent.com/dvlab-research/LISA/main/imgs/example2.jpg
!wget -O LISA/resources/imgs/example3.jpg https://raw.githubusercontent.com/dvlab-research/LISA/main/imgs/stand_higher.jpg
!wget -O LISA/resources/imgs/example5.jpg https://storage.googleapis.com/generativeai-downloads/images/breakfast.jpg

4.2 執行推論 (推薦方式)

使用自訂的 infer_lisa.py 腳本進行推論：

!$HOME/miniconda/envs/lisa/bin/python ~/LISA/infer_lisa.py \
    --version="xinlai/LISA-7B-v1-explanatory" \
    --precision="bf16" \
    --prompt="segment food object and give me food name" \
    --image="LISA/resources/imgs/example5.jpg" \
    --output_dir="./vis_output"

4.3 輸出結果

推論完成後，會在 output_dir 產生：

• {image_name}_mask_{i}.png - 分割遮罩 (黑白圖)
• {image_name}_masked_{i}.png - 疊加遮罩的原圖

---

5. 模型訓練

📓 對應筆記本：2_training.ipynb

5.1 設定訓練路徑

# ==== 全域設定 ==== #
BASE_LOG_DIR   = "/ceph/work/yutienchanglab/output"      # 訓練輸出目錄
BASE_MODEL_DIR = "/ceph/work/yutienchanglab/llava-7b"    # LLaVA 基礎模型路徑
LISA_DIR       = "LISA"                                    # LISA 專案目錄
DATASET_DIR    = "dataset"                                 # 資料集目錄
SAM_PATH       = "/ceph/work/yutienchanglab/sam_vit_h_4b8939.pth"  # SAM 權重

# 設定實驗名稱
EXP_NAME = "lisa-7b-reasonseg-only"

# === 自動推導路徑 === #
RUN_DIR    = f"{BASE_LOG_DIR}/{EXP_NAME}"
CKPT_DIR   = f"{RUN_DIR}/ckpt_model"
MERGED_DIR = f"{RUN_DIR}-merged"

5.2 執行 DeepSpeed 訓練

import subprocess

train_cmd = f"""
source $HOME/miniconda/bin/activate lisa && \
MPLBACKEND=Agg deepspeed --master_port=24999 {LISA_DIR}/train_ds.py \
  --version="{BASE_MODEL_DIR}" \
  --dataset_dir="{DATASET_DIR}" \
  --vision_pretrained="{SAM_PATH}" \
  --dataset="reason_seg" \
  --sample_rates="1" \
  --log_base_dir="{BASE_LOG_DIR}" \
  --exp_name="{EXP_NAME}" \
  --batch_size 1 \
  --grad_accumulation_steps 8 \
  --num_classes_per_sample 1 \
  --precision bf16 \
  --epochs 1 \
  --steps_per_epoch 20 \
  --print_freq 20 \
  --no_eval
"""

process = subprocess.Popen(
    train_cmd,
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    shell=True,
    executable="/bin/bash"
)

for line in iter(process.stdout.readline, b''):
    print(line.decode(), end='')

process.wait()

5.3 合併 DeepSpeed 權重

訓練完成後，需將 DeepSpeed 產生的碎片化權重合併：

!$HOME/miniconda/bin/conda run -n lisa python {CKPT_DIR}/zero_to_fp32.py \
    {CKPT_DIR} \
    {RUN_DIR}/pytorch_model.bin

5.4 合併 LoRA 權重

將 LoRA 差異權重合併回原始模型：

import subprocess

merge_cmd = f"""
source $HOME/miniconda/bin/activate lisa && \
python {LISA_DIR}/merge_lora_weights_and_save_hf_model.py \
   --version "{BASE_MODEL_DIR}" \
   --weight "{RUN_DIR}/pytorch_model.bin" \
   --save_path "{MERGED_DIR}" \
   --precision "fp16"
"""

process = subprocess.Popen(merge_cmd, shell=True, executable="/bin/bash")
process.wait()

💡 說明：LoRA 訓練只學習差異權重 (ΔW)，合併後才能得到完整的可推論模型： Final_Weights = Base_Model_Weights + LoRA_Update

5.5 測試訓練結果

!$HOME/miniconda/envs/lisa/bin/python {LISA_DIR}/infer_lisa.py \
    --version="{MERGED_DIR}" \
    --precision="bf16" \
    --prompt="segment food object and give me food name" \
    --image="{LISA_DIR}/resources/imgs/example5.jpg" \
    --output_dir="vis_output"

---

6. 檔案結構說明

6.1 網格中心儲存架構

在網格中心 PyTorch A100 環境中，儲存空間分為兩個主要區域：

📁 個人工作目錄

/dicos_ui_home/<username>/

• <username> 會依據登入者而改變
• 此目錄為個人專屬空間，容量較小
• 適合存放：程式碼、筆記本、小型檔案

📁 Lab 共用儲存區

/ceph/work/yutienchanglab/

• 實驗室共用的大容量儲存空間
• 預先下載的模型權重已存放於此
• 適合存放：大型模型、資料集、訓練輸出

6.2 專案檔案配置

個人目錄結構 (/dicos_ui_home/<username>/)

├── 0_create_env.ipynb      # 環境建置筆記本
├── 1_inference.ipynb       # 推論測試筆記本
├── 2_training.ipynb        # 訓練流程筆記本
├── 
├── README_LISA_Tutorial.md # 本文件
│
├── LISA/                   # LISA 官方專案 (git clone)
│   ├── train_ds.py         # DeepSpeed 訓練腳本
|   ├── infer_lisa.py       # 自訂推論腳本
│   ├── chat.py             # 官方互動推論
│   ├── merge_lora_weights_and_save_hf_model.py
│   ├── model/              # 模型定義
│   └── utils/              # 工具函數
│   └── resources/
│       └── imgs/           # 測試圖片
│
├── dataset/                # 訓練資料集（可選：可連結到共用區）
│   └── reason_seg/         # ReasonSeg 資料集
│
└── vis_output/             # 推論輸出結果

共用目錄結構 (/ceph/work/yutienchanglab/)

yutienchanglab/
├── llava-7b/                        # LLaVA-7B 基礎模型權重 ⭐
│   ├── config.json
│   ├── pytorch_model.bin
│   └── ...
│
├── sam_vit_h_4b8939.pth            # SAM ViT-H 預訓練權重 ⭐
│
├── output/                          # 訓練輸出目錄
│   ├── lisa-7b-reasonseg-only/  # 訓練檢查點
│   │   ├── ckpt_model/             # DeepSpeed 碎片化權重
│   │   └── pytorch_model.bin       # 合併後的權重
│   │
│   └── lisa-7b-reasonseg-only-merged/  # LoRA 合併後的完整模型 ⭐
│       ├── config.json
│       ├── pytorch_model.bin
│       └── ...
│
└── datasets/                        # 共用資料集（可選）
    └── reason_seg/

6.3 重要路徑說明

💡 提示：由於模型權重檔案較大（LLaVA-7B 約 13GB，SAM 約 2.5GB），這些檔案已預先下載至共用儲存區 /ceph/work/yutienchanglab/，避免每位使用者重複下載佔用空間。

---

📚 參考資源

• LISA 官方 GitHub
• LISA 論文
• 網格中心 PyTorch 環境說明
• DeepSpeed 官方文件
• Hugging Face LISA 模型

---

📝 版本歷史

---

💡 提示：如有問題或建議，歡迎提出 Issue 或聯繫維護者。