| # 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 还是全量格式 |
|
|
