REAlign: Requirement–Evidence Alignment for Compositional E-Commerce Queries

This repository contains the official source code for the paper "Requirement–Evidence Alignment for Compositional E-Commerce Queries."

REAlign is a requirement–evidence-aligned reranking framework for compositional e-commerce queries. It connects typed query requirements with visible candidate evidence, constructs requirement-targeted contrasts, and optimizes duplicate-free partial rankings through Requirement-Aware Group-Relative Policy Optimization.

Setup

Python 3.10 or later and a CUDA-enabled PyTorch environment are recommended.

git clone https://github.com/Nevaeh7/REAlign.git
cd REAlign
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

The training code uses Qwen/Qwen3.5-4B. To use an existing local model, set:

export NEEDRANK_QWEN_MODEL_ID=/path/to/Qwen3.5-4B

Data Preparation

Download the Shop-Need and KS-Need datasets from Google Drive, then place them under the repository root as follows:

data/
├── shop_need/
│ ├── qwen_sft_train.jsonl
│ ├── qwen_sft_eval.jsonl
│ ├── qwen_grpo_train.jsonl
│ └── qwen_grpo_eval.jsonl
└── ks_need/
├── qwen_sft_train.jsonl
├── qwen_sft_eval.jsonl
├── qwen_grpo_train.jsonl
└── qwen_grpo_eval.jsonl

Do not rename these files: the SFT and REAlign training entry points resolve the filenames directly. Dataset files are intentionally excluded from Git.

Shop-Need

1. Supervised fine-tuning

export NEEDRANK_QWEN_OUTPUT_DIR="$PWD/data/shop_need"export NEEDRANK_QWEN_SFT_OUTPUT_DIR="$PWD/outputs/shop_need/sft_lora"export NEEDRANK_QWEN_GRAD_ACCUM=16
python -m NeedRank.qwen_sft_train

2. REAlign optimization

export NEEDRANK_QWEN_GRPO_MODEL_ID="$NEEDRANK_QWEN_SFT_OUTPUT_DIR"export NEEDRANK_QWEN_GRPO_OUTPUT_DIR="$PWD/outputs/shop_need/realign_lora"export NEEDRANK_QWEN_GRPO_REWARD_MODE=rgrpo
export NEEDRANK_QWEN_GRPO_GRAD_ACCUM=1
export NEEDRANK_QWEN_MAX_COMPLETION_LENGTH=256
python -m NeedRank.qwen_grpo_train

3. Evaluation

python scripts/eval_qwen_resumable.py \
--method realign \
--adapter-dir outputs/shop_need/realign_lora \
--eval-file data/shop_need/qwen_grpo_eval.jsonl \
--output-dir outputs/shop_need/eval \
--base-model "${NEEDRANK_QWEN_MODEL_ID:-Qwen/Qwen3.5-4B}" \
--max-new-tokens 256 \
--batch-size 4

KS-Need

1. Supervised fine-tuning

export NEEDRANK_QWEN_OUTPUT_DIR="$PWD/data/ks_need"export NEEDRANK_QWEN_SFT_OUTPUT_DIR="$PWD/outputs/ks_need/sft_lora"export NEEDRANK_QWEN_GRAD_ACCUM=16
python -m NeedRank.qwen_sft_train

2. REAlign optimization

export NEEDRANK_QWEN_GRPO_MODEL_ID="$NEEDRANK_QWEN_SFT_OUTPUT_DIR"export NEEDRANK_QWEN_GRPO_OUTPUT_DIR="$PWD/outputs/ks_need/realign_lora"export NEEDRANK_QWEN_GRPO_REWARD_MODE=rgrpo_rank_aligned
export NEEDRANK_QWEN_GRPO_GRAD_ACCUM=8
export NEEDRANK_QWEN_MAX_COMPLETION_LENGTH=128
python -m NeedRank.qwen_grpo_train

3. Evaluation

python scripts/eval_qwen_resumable.py \
--method realign \
--adapter-dir outputs/ks_need/realign_lora \
--eval-file data/ks_need/qwen_grpo_eval.jsonl \
--output-dir outputs/ks_need/eval \
--base-model "${NEEDRANK_QWEN_MODEL_ID:-Qwen/Qwen3.5-4B}" \
--max-new-tokens 128 \
--batch-size 4

Evaluation is resumable and writes the generated completions together with JSON and Markdown reports under the selected output directory.

Repository Structure

NeedRank/
├── qwen_sft_train.py # supervised fine-tuning
├── qwen_grpo_train.py # REAlign policy optimization
├── qwen_training.py # requirement-aware reward functions
├── qwen_eval.py # completion parsing and evaluation
├── metrics.py # ranking and requirement metrics
└── schema.py # shared data structures
scripts/
└── eval_qwen_resumable.py # resumable adapter evaluation

The internal NeedRank package name is retained for compatibility with the original experimental entry points.

Citation

@article{shen2026realign,
title = {Requirement--Evidence Alignment for Compositional E-Commerce Queries},
author = {Shen, Weihao and Chen, Wei and Zhang, Fuwei and Yuan, Meng and Lan, Yuqin and Liu, Guojun and Hua, Qingsong and Lin, Wei and Zhuang, Fuzhen},
journal = {arXiv preprint arXiv:2608.02500},
year = {2026}
}