MODEL_USAGE.md

# LoRA Adapter 模型文件说明

## 📁 文件结构说明

这个文件夹包含的是 **LoRA (Low-Rank Adaptation) Adapter**，不是完整的合并模型。以下是各个文件的用途：

### 核心文件

1. **`adapter_config.json`** 
   - LoRA 配置信息
   - 包含 base model 路径、LoRA 参数（r=8, alpha=32）、target modules 等
   - 告诉 PEFT 库如何加载和应用这个 adapter

2. **`adapter_model.safetensors`**
   - LoRA 权重文件（只有训练过的参数，非常小）
   - 包含 LoRA 的 A 和 B 矩阵权重
   - 这是实际需要加载的 adapter 权重

3. **`README.md`**
   - 模型卡片信息
   - 包含 base model 信息：`Qwen/Qwen2.5-1.5B-Instruct`

### Tokenizer 文件（可选，通常与 base model 相同）

4. **`tokenizer.json`** - Tokenizer 的完整配置
5. **`tokenizer_config.json`** - Tokenizer 配置参数
6. **`vocab.json`** - 词汇表
7. **`merges.txt`** - BPE merge 规则
8. **`special_tokens_map.json`** - 特殊 token 映射
9. **`added_tokens.json`** - 额外添加的 tokens
10. **`chat_template.jinja`** - Chat template 模板

## 🔧 使用方法

### 方法 1：不合并（推荐）✅

**优点：**
- 文件小，只保存 adapter 权重
- 可以切换不同的 adapter
- 可以继续训练或微调
- 加载速度快

**代码示例：**

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

# 1. 先加载 base model
base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct",
    trust_remote_code=True,
    torch_dtype="auto",
    device_map="auto"
)

# 2. 加载 LoRA adapter
model = PeftModel.from_pretrained(
    base_model,
    "./1.5B_models/11/my-model/Qwen2.5-1.5B-Instruct-ROI-20260120_205341",
    is_trainable=False  # 推理时设为 False
)

# 3. 加载 tokenizer（使用 adapter 目录中的，或 base model 的）
tokenizer = AutoTokenizer.from_pretrained(
    "./1.5B_models/11/my-model/Qwen2.5-1.5B-Instruct-ROI-20260120_205341",
    trust_remote_code=True
)
```

**在你的 notebook 中：**

根据 `ExamModel` 类的代码，你需要这样使用：

```python
# 方式 A：如果 ExamModel 支持自动检测 adapter
roi_model = ExamModel(
    model_name="Qwen/Qwen2.5-1.5B-Instruct",  # base model
    sft_model_path="./1.5B_models/11/my-model/Qwen2.5-1.5B-Instruct-ROI-20260120_205341",  # adapter 路径
    torch_dtype="auto",
    device_map="auto",
    trust_remote_code=True,
)
```

### 方法 2：合并 LoRA 到 Base Model

**优点：**
- 使用简单，就像普通模型一样
- 不需要 PEFT 库
- 推理速度可能稍快（但差异很小）

**缺点：**
- 文件大（需要保存完整模型权重）
- 无法切换 adapter
- 无法继续训练

**合并代码：**

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

# 1. 加载 base model
base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct",
    trust_remote_code=True,
    torch_dtype="auto",
    device_map="auto"
)

# 2. 加载 adapter
model = PeftModel.from_pretrained(
    base_model,
    "./1.5B_models/11/my-model/Qwen2.5-1.5B-Instruct-ROI-20260120_205341"
)

# 3. 合并权重
merged_model = model.merge_and_unload()

# 4. 保存合并后的模型
merged_model.save_pretrained("./merged_model")
tokenizer = AutoTokenizer.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct",
    trust_remote_code=True
)
tokenizer.save_pretrained("./merged_model")
```

## ❓ 回答你的问题

### Q: 需要合并 base model 和 LoRA 才能跑 benchmark 吗？

**A: 不需要！** ✅

你可以直接使用 **方法 1（不合并）** 来运行 benchmark。实际上：

1. **你的 notebook 代码已经支持 adapter 加载**
   - `ExamModel` 类有 `sft_model_path` 参数
   - 使用 `PeftModel.from_pretrained()` 加载 adapter

2. **只需要修改加载代码：**
   ```python
   ft_model_dir = f"./1.5B_models/{file_num}/my-model/{model_name}"
   
   # 修改为：
   roi_model = ExamModel(
       model_name="Qwen/Qwen2.5-1.5B-Instruct",  # base model ID
       sft_model_path=ft_model_dir,  # adapter 路径
       torch_dtype="auto",
       device_map="auto",
       trust_remote_code=True,
   )
   ```

3. **不合并的好处：**
   - 节省磁盘空间（adapter 只有几 MB，合并后是几 GB）
   - 可以轻松切换不同的 adapter 做对比
   - 加载速度更快

## 🚀 快速开始

直接修改你的 notebook 第 2495 行左右的代码：

```python
ft_model_dir = f"./1.5B_models/{file_num}/my-model/{model_name}"

# load fine-tuned ROI model (使用 adapter，不合并)
roi_model = ExamModel(
    model_name="Qwen/Qwen2.5-1.5B-Instruct",  # base model
    sft_model_path=ft_model_dir,  # LoRA adapter 路径
    torch_dtype="auto",
    device_map="auto",
    use_fast_tokenizer=True,
    trust_remote_code=True,
)
```

这样就可以直接运行 benchmark 了！不需要合并。