# Instruct-Reranker

基于大语言模型（LLM）的多模态 Listwise 重排序训练与评估框架，用于电商搜索场景下的商品候选集重排。

## 项目结构

```
rerank_ins/
├── train/                          # 训练脚本
│   ├── train_reranker_qwen3vl.py   # Qwen3-VL-8B 训练
│   └── train_reranker_qwen35.py    # Qwen3.5-9B 训练
├── eval/                           # 评估脚本
│   ├── eval_reranker_qwen3vl.py    # Qwen3-VL 评估 (vLLM)
│   └── eval_reranker_qwen35.py     # Qwen3.5 评估 (Transformers)
├── models/                         # 模型定义
│   ├── ranking_loss.py             # RankingLoss + ListwiseLoss
│   ├── qwen3_vl_rank.py           # Qwen3-VL DPO 变体
│   └── qwen3_5_rank.py            # Qwen3.5 DPO 变体
├── collators/                      # 数据 Collator
│   ├── base.py                     # 基类
│   ├── qwen_vl_rerank.py          # 训练/评估 Collator
│   └── vision_process.py          # 图像/视频预处理
├── loaders/                        # 模型加载器
│   ├── base.py
│   ├── qwen3_vl.py
│   └── qwen3_5.py
├── dataset/                        # 数据集
│   ├── data_utils.py              # 消息构建工具
│   └── dataset_listwise.py        # Listwise 数据集类
├── format_prompt/                  # Prompt 模板
│   ├── listwise_reranker_v1.jinja # 单图模式 (query crop + doc crop)
│   └── listwise_reranker_v2.jinja # 双图模式 (query full+crop + doc full+crop)
├── ds_configs/                     # DeepSpeed 配置
│   ├── zero2.json
│   └── zero3.json
├── scripts/                        # 启动脚本
│   ├── train_qwen3vl.sh
│   ├── train_qwen35.sh
│   ├── eval_qwen3vl.sh
│   └── eval_qwen35.sh
├── arguments.py                    # 参数定义
├── supported_models.py             # 模型注册
├── utils.py                        # 工具函数
├── setup.py
├── requirements.txt
└── README.md
```



## 数据格式

训练/评估数据为 JSONL 格式，每行一个样本：

```json
{
  "query_image": "/path/to/query_image.jpg",
  "query_crop_image": "/path/to/query_crop.jpg",
  "instruction": "找相似款红色连衣裙",
  "intent": "属性筛选",
  "docs": [
    {
      "doc_image": "/path/to/doc_full.jpg",
      "crop_image": "/path/to/doc_crop.jpg",
      "doc_title": "商品标题",
      "label": 0
    }
  ]
}
```

**Label 定义**：
- `0`：绝对正例 — 品类正确，完全满足用户意图
- `1`：相对正例 — 品类正确，基本满足或边界模糊
- `2`：违约负例 — 品类正确但违背关键条件
- `3`：弱负例 — 品类不对，与需求无关

## 训练

记得在train中修改路径

### Qwen3-VL-8B（单图模式）

```bash
bash scripts/train/train_qwen3vl.sh
```
提交训练
```
bash scripts/submit/submit_train_qwen3vl.sh
```

### Qwen3.5-9B（双图模式，最佳效果）

```bash
bash scripts/train/train_qwen35.sh
```
提交训练
```
bash scripts/submit/submit_train_qwen35.sh
```

**关键超参数**：
| 参数 | Qwen3-VL | Qwen3.5 |
|------|----------|---------|
| 学习率 | 5e-6 | 1e-5 |
| Batch Size/GPU | 4 | 2 |
| Gradient Accum | 1 | 2 |
| Full+Crop 双图 | 否 | 是 |
| Max Crop Tokens | 80 | 160 |
| Flash Attention | 是 | 否 |

## 评估

### Qwen3-VL（基于 vLLM 加速推理）

```bash
python eval/eval_reranker_qwen3vl.py \
    --model-path /path/to/checkpoint \
    --eval-data /path/to/eval.jsonl \
    --tp 2 --full-crop-mode
```

### Qwen3.5（基于 Transformers 原生推理）

```bash
python eval/eval_reranker_qwen35.py \
    --model-path /path/to/checkpoint \
    --eval-data /path/to/eval.jsonl \
    --full-crop-mode
```

## 评估指标

| 指标 | 定义 |
|------|------|
| Strict Hit Rate@N | 只有 label=0 算命中 |
| Soft Hit Rate@N | label=0 和 label=1 都算命中 |

**排序方式**：从模型输出的 logits 中提取 token "0"/"1"/"2"/"3" 的概率，以 P(token="0") 降序排列候选商品。

## 模型原理

采用 **Listwise** 训练方式：
- **输入**：1 张查询图 + 用户 instruction + 10 张候选商品图像及标题
- **输出**：10 个连续数字（0-3），分别代表每个候选商品的相关性 label
- **排序依据**：取 token "0" 的概率作为排序分数（概率越高越相关）

## 支持的模型

| Model ID | 模型 | 推荐配置 |
|----------|------|----------|
| `qwen3-vl-8b` | Qwen3-VL-8B-Instruct | 单图 + v1 prompt |
| `qwen3_5-9b` | Qwen3.5-VL-9B | 双图 + v2 prompt（最佳） |

## 注意事项

1. 训练脚本中的 `MODEL_LOCAL_PATH`、`TRAIN_DATA_PATH`、`EVAL_DATA_PATH` 需要修改为实际路径
2. 默认冻结 Vision Encoder 和 Vision Projector，只训练 LLM 部分
3. 支持 LoRA 和全量微调两种模式（脚本默认全量微调）
4. 评估脚本会自动识别 checkpoint 是 LoRA 还是全量格式