Qwen3-Reranker-4B-seq-cls-entity-disambiguation

Qwen3-Reranker-4B-seq-cls-entity-disambiguation

<p align="center"> <img src="https://qianwen-res.oss-accelerate-overseas.aliyuncs.com/logo_qwen3.png" width="400"/> <p>

[!NOTE] This model is based on Qwen3-Reranker-4B-seq-cls model, part of the Qwen3 Reranker series, modified as a sequence classification model instead. See Updated Usage for details on how to use it, or Original Usage for the original usage.

This model was fine-tuned for entity disambiguation on 50K Wikipedia mentions with QLoRA. It should be used as the original one (described bellow), simply providing it with the document, queries and task in the correct format:

• Entity candidate documents in the {title} {description} format
• The following entity disambiguation task: Given a text with a mention enclosed between the '[' and ']' characters, retrieve relevant entities that the mention refers to.
• The mention+context query with the mention enclosed between the [ and ] characters

vLLM usage example:

from vllm import LLM

MODEL_NAME = "samyhaff/Qwen3-Reranker-4B-seq-cls-entity-disambiguation"

PREFIX = '<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or
"no".<|im_end|>\n<|im_start|>user\n'
SUFFIX = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
TASK = "Given a text with a mention enclosed between the '[' and ']' characters, retrieve relevant entities that the mention refers to."

model = LLM(model=MODEL_NAME, runner="pooling")

# Enclose the mention between '[' and ']' in the context
context = "In 1969, [Armstrong] became the first human to walk on the Moon."

# Candidates as title, description couples
candidates = [
    ("Neil Armstrong", "American astronaut and aeronautical engineer who was the first person to walk on the Moon."),
    ("Louis Armstrong", "American jazz trumpeter, vocalist, and one of the most influential figures in jazz history."),
]

query = f"{PREFIX}<Instruct>: {TASK}\n<Query>: {context}\n"
documents = [
    f"<Document>: {title} {description}{SUFFIX}"
    for title, description in candidates
]

outputs = model.score(query, documents)
scores = [out.outputs.score for out in outputs]
best_idx = scores.index(max(scores))
print(f"Best candidate: {candidates[best_idx][0]}")  # Neil Armstrong

Citation

@article{qwen3embedding,
  title={LELA: an LLM-based Entity Linking Approach with Zero-Shot Domain Adaptation},
  author={Samy Haffoudhi, Fabian M. Suchanek, Nils Holzenberger},
  journal={arXiv preprint arXiv:2601.05192},
  year={2026}
}

@article{qwen3embedding,
  title={Qwen3 Embedding: Advancing Text Embedding and Reranking Through Foundation Models},
  author={Zhang, Yanzhao and Li, Mingxin and Long, Dingkun and Zhang, Xin and Lin, Huan and Yang, Baosong and Xie, Pengjun and Yang, An and Liu, Dayiheng and Lin, Junyang and Huang, Fei and Zhou, Jingren},
  journal={arXiv preprint arXiv:2506.05176},
  year={2025}
}

Orignial model README

Highlights

The Qwen3 Embedding model series is the latest proprietary model of the Qwen family, specifically designed for text embedding and ranking tasks. Building upon the dense foundational models of the Qwen3 series, it provides a comprehensive range of text embeddings and reranking models in various sizes (0.6B, 4B, and 8B). This series inherits the exceptional multilingual capabilities, long-text understanding, and reasoning skills of its foundational model. The Qwen3 Embedding series represents significant advancements in multiple text embedding and ranking tasks, including text retrieval, code retrieval, text classification, text clustering, and bitext mining.

Exceptional Versatility: The embedding model has achieved state-of-the-art performance across a wide range of downstream application evaluations. The 8B size embedding model ranks No.1 in the MTEB multilingual leaderboard (as of June 5, 2025, score 70.58), while the reranking model excels in various text retrieval scenarios.

Comprehensive Flexibility: The Qwen3 Embedding series offers a full spectrum of sizes (from 0.6B to 8B) for both embedding and reranking models, catering to diverse use cases that prioritize efficiency and effectiveness. Developers can seamlessly combine these two modules. Additionally, the embedding model allows for flexible vector definitions across all dimensions, and both embedding and reranking models support user-defined instructions to enhance performance for specific tasks, languages, or scenarios.

Multilingual Capability: The Qwen3 Embedding series offer support for over 100 languages, thanks to the multilingual capabilites of Qwen3 models. This includes various programming languages, and provides robust multilingual, cross-lingual, and code retrieval capabilities.

Qwen3-Reranker-4B has the following features:

• Model Type: Text Reranking
• Supported Languages: 100+ Languages
• Number of Paramaters: 4B
• Context Length: 32k

For more details, including benchmark evaluation, hardware requirements, and inference performance, please refer to our blog, GitHub.

Qwen3 Embedding Series Model list

Note:

• MRL Support indicates whether the embedding model supports custom dimensions for the final embedding.
• Instruction Aware notes whether the embedding or reranking model supports customizing the input instruction according to different tasks.
• Our evaluation indicates that, for most downstream tasks, using instructions (instruct) typically yields an improvement of 1% to 5% compared to not using them. Therefore, we recommend that developers create tailored instructions specific to their tasks and scenarios. In multilingual contexts, we also advise users to write their instructions in English, as most instructions utilized during the model training process were originally written in English.

Usage

With Transformers versions earlier than 4.51.0, you may encounter the following error:

KeyError: 'qwen3'

Updated Usage

Updated Sentence Transformers Usage

# Requires transformers>=4.51.0
from sentence_transformers import CrossEncoder


def format_queries(query, instruction=None):
    prefix = '<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>\n<|im_start|>user\n'
    if instruction is None:
        instruction = (
            "Given a web search query, retrieve relevant passages that answer the query"
        )
    return f"{prefix}<Instruct>: {instruction}\n<Query>: {query}\n"


def format_document(document):
    suffix = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
    return f"<Document>: {document}{suffix}"


model = CrossEncoder("tomaarsen/Qwen3-Reranker-4B-seq-cls")

task = "Given a web search query, retrieve relevant passages that answer the query"

queries = [
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
]

documents = [
    "Venus is often called Earth's twin because of its similar size and proximity.",
    "Mars, known for its reddish appearance, is often referred to as the Red Planet.",
    "Jupiter, the largest planet in our solar system, has a prominent red spot.",
    "Saturn, famous for its rings, is sometimes mistaken for the Red Planet.",
]

pairs = [
    [format_queries(query, task), format_document(doc)]
    for query, doc in zip(queries, documents)
]
scores = model.predict(pairs)
print(scores.tolist())
# [0.00012360254186205566, 0.98269122838974, 0.0014677430735900998, 0.2251107543706894]

Updated Transformers Usage

# Requires transformers>=4.51.0
from transformers import AutoModelForSequenceClassification, AutoTokenizer


def format_instruction(instruction, query, doc):
    prefix = '<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>\n<|im_start|>user\n'
    suffix = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
    if instruction is None:
        instruction = (
            "Given a web search query, retrieve relevant passages that answer the query"
        )
    output = f"{prefix}<Instruct>: {instruction}\n<Query>: {query}\n<Document>: {doc}{suffix}"
    return output


tokenizer = AutoTokenizer.from_pretrained("tomaarsen/Qwen3-Reranker-4B-seq-cls", padding_side="left")
model = AutoModelForSequenceClassification.from_pretrained("tomaarsen/Qwen3-Reranker-4B-seq-cls").eval()
# We recommend enabling flash_attention_2 for better acceleration and memory saving.
# model = AutoModelForSequenceClassification.from_pretrained("tomaarsen/Qwen3-Reranker-4B-seq-cls", torch_dtype=torch.float16, attn_implementation="flash_attention_2").cuda().eval()
max_length = 8192

task = "Given a web search query, retrieve relevant passages that answer the query"

queries = [
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
]

documents = [
    "Venus is often called Earth's twin because of its similar size and proximity.",
    "Mars, known for its reddish appearance, is often referred to as the Red Planet.",
    "Jupiter, the largest planet in our solar system, has a prominent red spot.",
    "Saturn, famous for its rings, is sometimes mistaken for the Red Planet.",
]

pairs = [format_instruction(task, query, doc) for query, doc in zip(queries, documents)]
inputs = tokenizer(
    pairs,
    padding=True,
    truncation=True,
    max_length=max_length,
    return_tensors="pt",
)
logits = model(**inputs).logits.squeeze()
print(logits.tolist())
# [-8.998334884643555, 4.0390801429748535, -6.5225725173950195, -1.2361359596252441]

scores = logits.sigmoid()
print(scores.tolist())
# [0.00012360018445178866, 0.98269122838974, 0.001467725494876504, 0.2251092940568924]

Original Usage

Original Transformers Usage

# Requires transformers>=4.51.0
import torch
from transformers import AutoModel, AutoTokenizer, AutoModelForCausalLM

def format_instruction(instruction, query, doc):
    if instruction is None:
        instruction = 'Given a web search query, retrieve relevant passages that answer the query'
    output = "<Instruct>: {instruction}\n<Query>: {query}\n<Document>: {doc}".format(instruction=instruction,query=query, doc=doc)
    return output

def process_inputs(pairs):
    inputs = tokenizer(
        pairs, padding=False, truncation='longest_first',
        return_attention_mask=False, max_length=max_length - len(prefix_tokens) - len(suffix_tokens)
    )
    for i, ele in enumerate(inputs['input_ids']):
        inputs['input_ids'][i] = prefix_tokens + ele + suffix_tokens
    inputs = tokenizer.pad(inputs, padding=True, return_tensors="pt", max_length=max_length)
    for key in inputs:
        inputs[key] = inputs[key].to(model.device)
    return inputs

@torch.no_grad()
def compute_logits(inputs, **kwargs):
    batch_scores = model(**inputs).logits[:, -1, :]
    true_vector = batch_scores[:, token_true_id]
    false_vector = batch_scores[:, token_false_id]
    batch_scores = torch.stack([false_vector, true_vector], dim=1)
    batch_scores = torch.nn.functional.log_softmax(batch_scores, dim=1)
    scores = batch_scores[:, 1].exp().tolist()
    return scores

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-Reranker-4B", padding_side='left')
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-Reranker-4B").eval()

# We recommend enabling flash_attention_2 for better acceleration and memory saving.
# model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-Reranker-4B", torch_dtype=torch.float16, attn_implementation="flash_attention_2").cuda().eval()

token_false_id = tokenizer.convert_tokens_to_ids("no")
token_true_id = tokenizer.convert_tokens_to_ids("yes")
max_length = 8192

prefix = "<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be \"yes\" or \"no\".<|im_end|>\n<|im_start|>user\n"
suffix = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
prefix_tokens = tokenizer.encode(prefix, add_special_tokens=False)
suffix_tokens = tokenizer.encode(suffix, add_special_tokens=False)
        
task = 'Given a web search query, retrieve relevant passages that answer the query'

queries = [
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
    "Which planet is known as the Red Planet?",
]

documents = [
    "Venus is often called Earth's twin because of its similar size and proximity.",
    "Mars, known for its reddish appearance, is often referred to as the Red Planet.",
    "Jupiter, the largest planet in our solar system, has a prominent red spot.",
    "Saturn, famous for its rings, is sometimes mistaken for the Red Planet.",
]

pairs = [format_instruction(task, query, doc) for query, doc in zip(queries, documents)]

# Tokenize the input texts
inputs = process_inputs(pairs)
scores = compute_logits(inputs)

print("scores: ", scores)
# scores:  [0.0001237865217262879, 0.9826870560646057, 0.0014700202737003565, 0.2253335416316986]

Original vLLM Usage

# Requires vllm>=0.8.5
import logging
from typing import Dict, Optional, List

import json
import logging

import torch

from transformers import AutoTokenizer, is_torch_npu_available
from vllm import LLM, SamplingParams
from vllm.distributed.parallel_state import destroy_model_parallel
import gc
import math
from vllm.inputs.data import TokensPrompt


        
def format_instruction(instruction, query, doc):
    text = [
        {"role": "system", "content": "Judge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be \"yes\" or \"no\"."},
        {"role": "user", "content": f"<Instruct>: {instruction}\n\n<Query>: {query}\n\n<Document>: {doc}"}
    ]
    return text

def process_inputs(pairs, instruction, max_length, suffix_tokens):
    messages = [format_instruction(instruction, query, doc) for query, doc in pairs]
    messages =  tokenizer.apply_chat_template(
        messages, tokenize=True, add_generation_prompt=False, enable_thinking=False
    )
    messages = [ele[:max_length] + suffix_tokens for ele in messages]
    messages = [TokensPrompt(prompt_token_ids=ele) for ele in messages]
    return messages

def compute_logits(model, messages, sampling_params, true_token, false_token):
    outputs = model.generate(messages, sampling_params, use_tqdm=False)
    scores = []
    for i in range(len(outputs)):
        final_logits = outputs[i].outputs[0].logprobs[-1]
        token_count = len(outputs[i].outputs[0].token_ids)
        if true_token not in final_logits:
            true_logit = -10
        else:
            true_logit = final_logits[true_token].logprob
        if false_token not in final_logits:
            false_logit = -10
        else:
            false_logit = final_logits[false_token].logprob
        true_score = math.exp(true_logit)
        false_score = math.exp(false_logit)
        score = true_score / (true_score + false_score)
        scores.append(score)
    return scores

number_of_gpu = torch.cuda.device_count()
tokenizer = AutoTokenizer.from_pretrained('Qwen/Qwen3-Reranker-4B')
model = LLM(model='Qwen/Qwen3-Reranker-4B', tensor_parallel_size=number_of_gpu, max_model_len=10000, enable_prefix_caching=True, gpu_memory_utilization=0.8)
tokenizer.padding_side = "left"
tokenizer.pad_token = tokenizer.eos_token
suffix = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
max_length=8192
suffix_tokens = tokenizer.encode(suffix, add_special_tokens=False)
true_token = tokenizer("yes", add_special_tokens=False).input_ids[0]
false_token = tokenizer("no", add_special_tokens=False).input_ids[0]
sampling_params = SamplingParams(temperature=0, 
    max_tokens=1,
    logprobs=20, 
    allowed_token_ids=[true_token, false_token],
)

        
task = 'Given a web search query, retrieve relevant passages that answer the query'
queries = ["What is the capital of China?",
    "Explain gravity",
]
documents = [
    "The capital of China is Beijing.",
    "Gravity is a force that attracts two bodies towards each other. It gives weight to physical objects and is responsible for the movement of planets around the sun.",
]

pairs = list(zip(queries, documents))
inputs = process_inputs(pairs, task, max_length-len(suffix_tokens), suffix_tokens)
scores = compute_logits(model, inputs, sampling_params, true_token, false_token)
print('scores', scores)

destroy_model_parallel()

📌 Tip: We recommend that developers customize the instruct according to their specific scenarios, tasks, and languages. Our tests have shown that in most retrieval scenarios, not using an instruct on the query side can lead to a drop in retrieval performance by approximately 1% to 5%.

Evaluation

Note:

• Evaluation results for reranking models. We use the retrieval subsets of MTEB(eng, v2), MTEB(cmn, v1), MMTEB and MTEB (Code), which are MTEB-R, CMTEB-R, MMTEB-R and MTEB-Code.
• All scores are our runs based on the top-100 candidates retrieved by dense embedding model Qwen3-Embedding-0.6B.

Citation

If you find our work helpful, feel free to give us a cite.

@article{qwen3embedding,
  title={Qwen3 Embedding: Advancing Text Embedding and Reranking Through Foundation Models},
  author={Zhang, Yanzhao and Li, Mingxin and Long, Dingkun and Zhang, Xin and Lin, Huan and Yang, Baosong and Xie, Pengjun and Yang, An and Liu, Dayiheng and Lin, Junyang and Huang, Fei and Zhou, Jingren},
  journal={arXiv preprint arXiv:2506.05176},
  year={2025}
}