README.md

---
license: apache-2.0
pipeline_tag: sentence-similarity
base_model:
- Qwen/Qwen2.5-1.5B
tags:
- transformers
- sentence-transformers
- sentence-similarity
- feature-extraction
---

<a href="https://github.com/vec-ai/lychee-embed">
  <img src="https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white">
</a>
<a href="https://openreview.net/pdf?id=NC6G1KCxlt">
  <img src="https://img.shields.io/badge/Paper-Openreview-red">
</a>

# Lychee Embed

`Lychee-embed` is the latest generalist text embedding model based on the `Qwen2.5` model. It is suitable for text retrieval (semantic correlation), text similarity and other downstream tasks, and supports multiple languages of `Qwen2.5`.
`Lychee-embed` 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 Embedding
- Language Support: 100+ Languages
- Param Size: 1.5B
- Context Length: 8k
- Embedding Dim: 1536, Supports diverse settings with 32 steps from 32 to 1536
- 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 embedding 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%.


### Sentence Transformers Usage

```python
# Requires transformers>=4.51.0
# Requires sentence-transformers>=2.7.0

from sentence_transformers import SentenceTransformer

# Load the model
model = SentenceTransformer("vec-ai/lychee-embed")

# We recommend enabling flash_attention_2 for better acceleration and memory saving,
# together with setting `padding_side` to "left":
# model = SentenceTransformer(
#     "vec-ai/lychee-embed",
#     model_kwargs={"attn_implementation": "flash_attention_2", "device_map": "auto"},
#     tokenizer_kwargs={"padding_side": "left"},
# )

# The queries and documents to embed
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.",
]

# Encode the queries and documents. Note that queries benefit from using a prompt
# Here we use the prompt called "query" stored under `model.prompts`, but you can
# also pass your own prompt via the `prompt` argument
query_embeddings = model.encode(queries, prompt_name="query")
document_embeddings = model.encode(documents)

# Compute the (cosine) similarity between the query and document embeddings
similarity = model.similarity(query_embeddings, document_embeddings)
print(similarity)
# tensor([[0.8952, 0.4001],
#         [0.4668, 0.8334]])
```

### Transformers Usage

```python
# Requires transformers>=4.51.0

import torch
from transformers import AutoTokenizer, AutoModel


def last_token_pool(last_hidden_states: torch.Tensor,
                 attention_mask: torch.Tensor) -> torch.Tensor:
    left_padding = (attention_mask[:, -1].sum() == attention_mask.shape[0])
    if left_padding:
        return last_hidden_states[:, -1]
    else:
        sequence_lengths = attention_mask.sum(dim=1) - 1
        batch_size = last_hidden_states.shape[0]
        return last_hidden_states[torch.arange(batch_size, device=last_hidden_states.device), sequence_lengths]


def get_detailed_instruct(task_description: str, query: str) -> str:
    return f'Instruct: {task_description}\nQuery:{query}'

# Each query must come with a one-sentence instruction that describes the task
task = 'Given a web search query, retrieve relevant passages that answer the query'

queries = [
    get_detailed_instruct(task, 'What is the capital of China?'),
    get_detailed_instruct(task, 'Explain gravity')
]
# No need to add instruction for retrieval documents
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."
]
input_texts = queries + documents

tokenizer = AutoTokenizer.from_pretrained('vec-ai/lychee-embed', padding_side='left')
model = AutoModel.from_pretrained('vec-ai/lychee-embed')

# We recommend enabling flash_attention_2 for better acceleration and memory saving.
# model = AutoModel.from_pretrained('vec-ai/lychee-embed', attn_implementation="flash_attention_2", torch_dtype=torch.float16).cuda()

max_length = 8192

# Tokenize the input texts
batch_dict = tokenizer(
    input_texts,
    padding=True,
    truncation=True,
    max_length=max_length,
    return_tensors="pt",
)
batch_dict.to(model.device)
outputs = model(**batch_dict)
embeddings = last_token_pool(outputs.last_hidden_state, batch_dict['attention_mask'])

# normalize embeddings
embeddings = torch.nn.functional.normalize(embeddings, p=2, dim=1)
scores = (embeddings[:2] @ embeddings[2:].T)
print(scores.tolist())
# [[0.8952088952064514, 0.40010833740234375], [0.4668009877204895, 0.8333653807640076]]
```

### vLLM Usage

```python
# Requires vllm>=0.8.5
import torch
from vllm import LLM

def get_detailed_instruct(task_description: str, query: str) -> str:
    return f'Instruct: {task_description}\nQuery:{query}'

# Each query must come with a one-sentence instruction that describes the task
task = 'Given a web search query, retrieve relevant passages that answer the query'

queries = [
    get_detailed_instruct(task, 'What is the capital of China?'),
    get_detailed_instruct(task, 'Explain gravity')
]
# No need to add instruction for retrieval documents
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."
]
input_texts = queries + documents

model = LLM(model="vec-ai/lychee-embed", task="embed")

outputs = model.embed(input_texts)
embeddings = torch.tensor([o.outputs.embedding for o in outputs])
scores = (embeddings[:2] @ embeddings[2:].T)
print(scores.tolist())
# [[0.9007290601730347, 0.4043760895729065], [0.469818651676178, 0.8317853212356567]]
```


## Evaluation

| Model | Param | MTEB | CMTEB | MMTEB | MLDR | MTEB-Code | ToolBench | FollowIR | BRIGHT |
|---|---|---|---|---|---|---|---|---|---|
| BGE-multilingual | 9.24B  | 69.88 | 68.44 | 61.25  | 49.10 | 62.04  | 63.65  | -2.13 | 17.68 |
| NV-Embed-v2  | 7.85B  | 72.31  | - | 56.25 | - | 63.74 | 50.54 | 1.04 | 19.28 |
| GritLM-7B | 7.24B  | 66.8 | - | 60.93 | - | 73.6 | 35.42 | 3.45 | 20.63 |
| E5-mistral    | 7.11B  | 66.6 | 59.92 | 60.28 | - | 69.2 | 31.79 | -0.62 | 17.54 |
| GTE-Qwen2-7B     | 7.62B  | 69.88 | 71.62 | 62.51 | 56.53 | 62.17 | 59.48 | 4.94 | 22.89 |
| GTE-Qwen2-1.5B   | 1.54B  | 67.19 | 67.12 | 59.47 | 52.11 | 61.98 | 62.57 | 0.74 | 18.47 |
| BGE-M3 (Dense)             | 0.56B  | 59.84 | 61.79 | 59.54 | 52.50 | 58.22  | 58.45 | -3.11 | 11.94 |
| Jina-v3                   | 0.57B  | 65.52 | 63.07 | 58.37 | 40.71 | 58.85 | 59.64 | -1.34 | 11.34 |
|Qwen3-Embedding-8B | 7.57B | | 73.84 | 70.58 | | 80.68 |
|Qwen3-Embedding-4B | 4.02B | | 72.27 | 69.45 | | 80.06 |
|Qwen3-Embedding-0.6B | 0.60B | | 66.33 | 64.33 | | 75.41 |
| **Lychee-embed** | 1.54B | 68.39 |69.77 | 58.43 | 53.85 | 72.54 | 86.35 | 5.74 | 19.47 |

For more details, please refer to our [Paper](https://openreview.net/pdf?id=NC6G1KCxlt).

## 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}
}
```