Update README.md

README.md

@@ -1,3 +1,230 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+base_model:
+- Qwen/Qwen2.5-1.5B-Instruct
+pipeline_tag: text-ranking
+---
+
+# Lychee Rerank
+
+[Github](https://github.com/vec-ai/lychee-embed) | [Paper](https://openreview.net/pdf?id=NC6G1KCxlt)
+
+`Lychee-rerank` is the latest generalist text embedding model based on the `Qwen2.5` model. It is suitable for reranking of various text retrieval tasks, and supports multiple languages of `Qwen2.5`.
+`Lychee-rerank` is jointly developed by the NLP Team of Harbin Institute of Technology, Shenzhen and is built based on an innovative multi-stage training framework (warm-up, task-learning, model merging, annealing).
+The first batch of open source is 1.5B parameter version.
+
+![The multi-stage training framework](framework-crop.png)
+
+
+**Lychee-embed**:
+
+- Model Type: Text Reranking
+- Language Support: 100+ Languages
+- Param Size: 1.5B
+- Context Length: 32k
+- Model Precision: BF16
+
+For more details, please refer to our [paper](https://openreview.net/pdf?id=NC6G1KCxlt).
+
+
+### Model List
+
+| Model Type       | Models               | Size | Layers | Sequence Length | Embedding Dimension | MRL Support | Instruction Aware |
+|------------------|----------------------|------|--------|-----------------|---------------------|-------------|----------------|
+| Text Embedding   | [lychee-embed](https://huggingface.co/vec-ai/lychee-embed) | 1.5B | 28     | 8K             | 1636                | Yes         | Yes            |
+| Text Reranking   | [lychee-rerank](https://huggingface.co/vec-ai/lychee-rerank) | 1.5B | 28     | 8K             | -                   | -           | Yes            |
+
+
+> **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.
+> - Like most models, 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.
+
+
+## Model Usage
+
+📌 **Tips**: 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%.
+
+
+### Transformers Usage
+
+```python
+# Requires transformers>=4.51.0
+import torch
+from transformers import 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("vec-ai/lychee-rerank", padding_side='left')
+model = AutoModelForCausalLM.from_pretrained("vec-ai/lychee-rerank").eval()
+
+# We recommend enabling flash_attention_2 for better acceleration and memory saving.
+# model = AutoModelForCausalLM.from_pretrained("vec-ai/lychee-rerank", 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"
+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 = [
+    "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 = [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)
+# [0.9398471117019653, 0.5553759336471558]
+```
+
+### vLLM Usage 
+
+```python
+# Requires vllm>=0.8.5
+import math
+
+import torch
+from transformers import AutoTokenizer, is_torch_npu_available
+from vllm import LLM, SamplingParams
+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('vec-ai/lychee-rerank')
+model = LLM(model='vec-ai/lychee-rerank', max_model_len=10000, enable_prefix_caching=True)
+tokenizer.padding_side = "left"
+tokenizer.pad_token = tokenizer.eos_token
+suffix = "<|im_end|>\n<|im_start|>assistant\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)
+# TODO
+```
+
+
+## Evaluation
+
+| Model | Param | MTEB-R | CMTEB-R | MMTEB-R | MLDR | MTEB-Code | ToolBench | FollowIR | BRIGHT |
+|---|---|---|---|---|---|---|---|---|---|
+| **Lychee-embed** | 1.54B | 68.39 |69.77 | 58.43 | 53.85 | 72.54 | 86.35 | 5.74 | 19.47 |
+||
+| Jina-multilingual-reranker-v2-base | 278M | 54.61 | 70.18 | 54.43 | 50.32 | 46.32 | 67.80 | -0.69 | 16.69  |
+| mGTE-reranker | 304M | 55.71 | 72.01 | 56.61 | 61.40 | 45.92 | 67.58 | -1.14 | 10.76 |
+| BGE-reranker-v2-m3 | 568M | 55.36 | 71.82 | 57.13 | 60.80 | 50.81 | 62.52	| -0.06	| 15.87 |
+| BGE-reranker-v2-gemma | 9.24B | 60.81 | 71.74 | 69.80 | 49.10 | 68.63 | 68.14 | -2.13	| 17.68  |
+| **Lychee-rerank** | 1.54B  | 59.56 | 76.37 | 62.47 | 64.09 | 78.03 | 90.82 | 7.38 | 16.92 |
+
+For more details, please refer to our [paper](assets/colm25-paper.pdf).
+
+## Citation
+
+If you find our work helpful, feel free to give us a cite.
+
+```
+@inproceedings{zhang2025phased,
+title={Phased Training for LLM-powered Text Retrieval Models Beyond Data Scaling},
+author={Xin Zhang and Yanzhao Zhang and Wen Xie and Dingkun Long and Mingxin Li and Pengjun Xie and Meishan Zhang and Wenjie Li and Min Zhang},
+booktitle={Second Conference on Language Modeling},
+year={2025},
+url={https://openreview.net/forum?id=NC6G1KCxlt}
+}
+```