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 格式，每行一个样本：

{
  "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 scripts/train/train_qwen3vl.sh

提交训练

bash scripts/submit/submit_train_qwen3vl.sh

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

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 加速推理）

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 原生推理）

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（最佳）

注意事项

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