Update README.md

README.md

@@ -1,3 +1,216 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+pipeline_tag: sentence-similarity
+---
+
+# Lychee Embed
+
+
+`Lychee-embed` is the latest generalist text embedding model developed based on the `Qwen2.5` basic 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 multi-stage training framework](assets/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](assets/colm25-paper.pdf).
+
+
+### 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$^\sigma$ | 35.42 | 3.45 | 20.63 |
+| E5-mistral    | 7.11B  | 66.6 | 59.92 | 60.28 | - | 69.2$^\sigma$ | 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](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}
+}
+```