Upload README.md with huggingface_hub

README.md

@@ -1,201 +1,371 @@
 ---
-library_name: transformers
-tags: []
+license: apache-2.0
+pipeline_tag: text-classification
+tags:
+- transformers
+- sentence-transformers
+language:
+- multilingual
 ---
 
-# Model Card for Model ID
+# Reranker
 
-<!-- Provide a quick summary of what the model is/does. -->
+**More details please refer to our Github: [FlagEmbedding](https://github.com/FlagOpen/FlagEmbedding/tree/master).**
 
+- [Model List](#model-list)
+- [Usage](#usage)
+- [Fine-tuning](#fine-tune)
+- [Evaluation](#evaluation)
+- [Citation](#citation)
 
+Different from embedding model, reranker uses question and document as input and directly output similarity instead of embedding. 
+You can get a relevance score by inputting query and passage to the reranker. 
+And the score can be mapped to a float value in [0,1] by sigmoid function.
 
-## Model Details
 
-### Model Description
+## Model List
 
-<!-- Provide a longer summary of what this model is. -->
+| Model                                                                     | Base model                                                           | Language | layerwise |                           feature                            |
+|:--------------------------------------------------------------------------|:--------:|:-----------------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:|
+| [BAAI/bge-reranker-base](https://huggingface.co/BAAI/bge-reranker-base) | [xlm-roberta-base](https://huggingface.co/xlm-roberta-base) | Chinese and English |     -     | Lightweight reranker model, easy to deploy, with fast inference. |
+| [BAAI/bge-reranker-large](https://huggingface.co/BAAI/bge-reranker-large) | [xlm-roberta-large](https://huggingface.co/FacebookAI/xlm-roberta-large) | Chinese and English |     -     | Lightweight reranker model, easy to deploy, with fast inference. |
+| [BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) | [bge-m3](https://huggingface.co/BAAI/bge-m3) |    Multilingual     |     -     | Lightweight reranker model, possesses strong multilingual capabilities, easy to deploy, with fast inference. |
+| [BAAI/bge-reranker-v2-gemma](https://huggingface.co/BAAI/bge-reranker-v2-gemma) | [google/gemma-2b](https://huggingface.co/google/gemma-2b) |    Multilingual     |     -     | Suitable for multilingual contexts, performs well in both English proficiency and multilingual capabilities. |
+| [BAAI/bge-reranker-v2-minicpm-layerwise](https://huggingface.co/BAAI/bge-reranker-v2-minicpm-layerwise) | [openbmb/MiniCPM-2B-dpo-fp16](https://huggingface.co/openbmb/MiniCPM-2B-dpo-fp16/tree/main) |    Multilingual     |   8-40    | Suitable for multilingual contexts, performs well in both English and Chinese proficiency, allows freedom to select layers for output, facilitating accelerated inference. |
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+You can select the model according your senario and resource. 
+- For **multilingual**, utilize [BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) and [BAAI/bge-reranker-v2-gemma](https://huggingface.co/BAAI/bge-reranker-v2-gemma)
 
-### Model Sources [optional]
+- For **Chinese or English**, utilize [BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) and [BAAI/bge-reranker-v2-minicpm-layerwise](https://huggingface.co/BAAI/bge-reranker-v2-minicpm-layerwise). 
 
-<!-- Provide the basic links for the model. -->
+- For **efficiency**, utilize [BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) and the low layer of [BAAI/bge-reranker-v2-minicpm-layerwise](https://huggingface.co/BAAI/bge-reranker-v2-minicpm-layerwise). 
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- For better performance, recommand [BAAI/bge-reranker-v2-minicpm-layerwise](https://huggingface.co/BAAI/bge-reranker-v2-minicpm-layerwise) and [BAAI/bge-reranker-v2-gemma](https://huggingface.co/BAAI/bge-reranker-v2-gemma)
 
-## Uses
+## Usage 
+### Using FlagEmbedding
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+```
+pip install -U FlagEmbedding
+```
 
-### Direct Use
+#### For normal reranker (bge-reranker-base / bge-reranker-large / bge-reranker-v2-m3 )
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+Get relevance scores (higher scores indicate more relevance):
 
-[More Information Needed]
+```python
+from FlagEmbedding import FlagReranker
+reranker = FlagReranker('BAAI/bge-reranker-v2-m3', use_fp16=True) # Setting use_fp16 to True speeds up computation with a slight performance degradation
 
-### Downstream Use [optional]
+score = reranker.compute_score(['query', 'passage'])
+print(score) # -5.65234375
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure 
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+# You can map the scores into 0-1 by set "normalize=True", which will apply sigmoid function to the score
+score = reranker.compute_score(['query', 'passage'], normalize=True)
+print(score) # 0.003497010252573502
+
+scores = reranker.compute_score([['what is panda?', 'hi'], ['what is panda?', 'The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.']])
+print(scores) # [-8.1875, 5.26171875]
+
+# You can map the scores into 0-1 by set "normalize=True", which will apply sigmoid function to the score
+scores = reranker.compute_score([['what is panda?', 'hi'], ['what is panda?', 'The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.']], normalize=True)
+print(scores) # [0.00027803096387751553, 0.9948403768236574]
+```
+
+#### For LLM-based reranker
+
+```python
+from FlagEmbedding import FlagLLMReranker
+reranker = FlagLLMReranker('BAAI/bge-reranker-v2-gemma', use_bf16=True) # Setting use_bf16 to True speeds up computation with a slight performance degradation
+
+score = reranker.compute_score(['query', 'passage'])
+print(score) # 2.15625
+
+scores = reranker.compute_score([['what is panda?', 'hi'], ['what is panda?', 'The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.']])
+print(scores) # [-0.84765625, 10.625]
+```
+
+#### For LLM-based layerwise reranker
+
+```python
+from FlagEmbedding import LayerWiseFlagLLMReranker
+reranker = LayerWiseFlagLLMReranker('BAAI/bge-reranker-v2-minicpm-layerwise', use_bf16=True) # Setting use_bf16 to True speeds up computation with a slight performance degradation
+
+score = reranker.compute_score(['query', 'passage'], cutoff_layers=[28]) # Adjusting 'cutoff_layers' to pick which layers are used for computing the score.
+print(score) # -7.03125
+
+scores = reranker.compute_score([['what is panda?', 'hi'], ['what is panda?', 'The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.']], cutoff_layers=[28])
+print(scores) # [-10.0, 1.8203125]
+```
+
+### Using Huggingface transformers
+
+#### For normal reranker (bge-reranker-base / bge-reranker-large / bge-reranker-v2-m3 )
+
+Get relevance scores (higher scores indicate more relevance):
+
+```python
+import torch
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+tokenizer = AutoTokenizer.from_pretrained('BAAI/bge-reranker-v2-m3')
+model = AutoModelForSequenceClassification.from_pretrained('BAAI/bge-reranker-v2-m3')
+model.eval()
+
+pairs = [['what is panda?', 'hi'], ['what is panda?', 'The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.']]
+with torch.no_grad():
+    inputs = tokenizer(pairs, padding=True, truncation=True, return_tensors='pt', max_length=512)
+    scores = model(**inputs, return_dict=True).logits.view(-1, ).float()
+    print(scores)
+```
+
+#### For LLM-based reranker
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+def get_inputs(pairs, tokenizer, prompt=None, max_length=1024):
+    if prompt is None:
+        prompt = "Given a query A and a passage B, determine whether the passage contains an answer to the query by providing a prediction of either 'Yes' or 'No'."
+    sep = "\n"
+    prompt_inputs = tokenizer(prompt,
+                              return_tensors=None,
+                              add_special_tokens=False)['input_ids']
+    sep_inputs = tokenizer(sep,
+                           return_tensors=None,
+                           add_special_tokens=False)['input_ids']
+    inputs = []
+    for query, passage in pairs:
+        query_inputs = tokenizer(f'A: {query}',
+                                 return_tensors=None,
+                                 add_special_tokens=False,
+                                 max_length=max_length * 3 // 4,
+                                 truncation=True)
+        passage_inputs = tokenizer(f'B: {passage}',
+                                   return_tensors=None,
+                                   add_special_tokens=False,
+                                   max_length=max_length,
+                                   truncation=True)
+        item = tokenizer.prepare_for_model(
+            [tokenizer.bos_token_id] + query_inputs['input_ids'],
+            sep_inputs + passage_inputs['input_ids'],
+            truncation='only_second',
+            max_length=max_length,
+            padding=False,
+            return_attention_mask=False,
+            return_token_type_ids=False,
+            add_special_tokens=False
+        )
+        item['input_ids'] = item['input_ids'] + sep_inputs + prompt_inputs
+        item['attention_mask'] = [1] * len(item['input_ids'])
+        inputs.append(item)
+    return tokenizer.pad(
+            inputs,
+            padding=True,
+            max_length=max_length + len(sep_inputs) + len(prompt_inputs),
+            pad_to_multiple_of=8,
+            return_tensors='pt',
+    )
+
+tokenizer = AutoTokenizer.from_pretrained('BAAI/bge-reranker-v2-gemma')
+model = AutoModelForCausalLM.from_pretrained('BAAI/bge-reranker-v2-gemma')
+yes_loc = tokenizer('Yes', add_special_tokens=False)['input_ids'][0]
+model.eval()
+
+pairs = [['what is panda?', 'hi'], ['what is panda?', 'The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.']]
+with torch.no_grad():
+    inputs = get_inputs(pairs, tokenizer)
+    scores = model(**inputs, return_dict=True).logits[:, -1, yes_loc].view(-1, ).float()
+    print(scores)
+```
+
+#### For LLM-based layerwise reranker
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+def get_inputs(pairs, tokenizer, prompt=None, max_length=1024):
+    if prompt is None:
+        prompt = "Given a query A and a passage B, determine whether the passage contains an answer to the query by providing a prediction of either 'Yes' or 'No'."
+    sep = "\n"
+    prompt_inputs = tokenizer(prompt,
+                              return_tensors=None,
+                              add_special_tokens=False)['input_ids']
+    sep_inputs = tokenizer(sep,
+                           return_tensors=None,
+                           add_special_tokens=False)['input_ids']
+    inputs = []
+    for query, passage in pairs:
+        query_inputs = tokenizer(f'A: {query}',
+                                 return_tensors=None,
+                                 add_special_tokens=False,
+                                 max_length=max_length * 3 // 4,
+                                 truncation=True)
+        passage_inputs = tokenizer(f'B: {passage}',
+                                   return_tensors=None,
+                                   add_special_tokens=False,
+                                   max_length=max_length,
+                                   truncation=True)
+        item = tokenizer.prepare_for_model(
+            [tokenizer.bos_token_id] + query_inputs['input_ids'],
+            sep_inputs + passage_inputs['input_ids'],
+            truncation='only_second',
+            max_length=max_length,
+            padding=False,
+            return_attention_mask=False,
+            return_token_type_ids=False,
+            add_special_tokens=False
+        )
+        item['input_ids'] = item['input_ids'] + sep_inputs + prompt_inputs
+        item['attention_mask'] = [1] * len(item['input_ids'])
+        inputs.append(item)
+    return tokenizer.pad(
+            inputs,
+            padding=True,
+            max_length=max_length + len(sep_inputs) + len(prompt_inputs),
+            pad_to_multiple_of=8,
+            return_tensors='pt',
+    )
+
+tokenizer = AutoTokenizer.from_pretrained('BAAI/bge-reranker-v2-minicpm-layerwise', trust_remote_code=True, torch_dtype=torch.bfloat16)
+model = AutoModelForCausalLM.from_pretrained('BAAI/bge-reranker-v2-minicpm-layerwise', trust_remote_code=True, torch_dtype=torch.bfloat16)
+model = model.to('cuda')
+model.eval()
+
+pairs = [['what is panda?', 'hi'], ['what is panda?', 'The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.']]
+with torch.no_grad():
+    inputs = get_inputs(pairs, tokenizer).to(model.device)
+    all_scores = model(**inputs, return_dict=True, cutoff_layers=[28])
+    all_scores = [scores[:, -1].view(-1, ).float() for scores in all_scores[0]]
+    print(all_scores)
+```
+
+## Fine-tune
+
+You can fine-tune the reranker with the following code:
+
+**For llm-based reranker**
+
+```shell
+torchrun --nproc_per_node {number of gpus} \
+-m FlagEmbedding.llm_reranker.finetune_for_instruction.run \
+--output_dir {path to save model} \
+--model_name_or_path BAAI/bge-reranker-v2-gemma \
+--train_data ./toy_finetune_data.jsonl \
+--learning_rate 2e-4 \
+--num_train_epochs 1 \
+--per_device_train_batch_size 1 \
+--gradient_accumulation_steps 16 \
+--dataloader_drop_last True \
+--query_max_len 512 \
+--passage_max_len 512 \
+--train_group_size 16 \
+--logging_steps 1 \
+--save_steps 2000 \
+--save_total_limit 50 \
+--ddp_find_unused_parameters False \
+--gradient_checkpointing \
+--deepspeed stage1.json \
+--warmup_ratio 0.1 \
+--bf16 \
+--use_lora True \
+--lora_rank 32 \
+--lora_alpha 64 \
+--use_flash_attn True \
+--target_modules q_proj k_proj v_proj o_proj
+```
+
+**For llm-based layerwise reranker**
+
+```shell
+torchrun --nproc_per_node {number of gpus} \
+-m FlagEmbedding.llm_reranker.finetune_for_layerwise.run \
+--output_dir {path to save model} \
+--model_name_or_path BAAI/bge-reranker-v2-minicpm-layerwise \
+--train_data ./toy_finetune_data.jsonl \
+--learning_rate 2e-4 \
+--num_train_epochs 1 \
+--per_device_train_batch_size 1 \
+--gradient_accumulation_steps 16 \
+--dataloader_drop_last True \
+--query_max_len 512 \
+--passage_max_len 512 \
+--train_group_size 16 \
+--logging_steps 1 \
+--save_steps 2000 \
+--save_total_limit 50 \
+--ddp_find_unused_parameters False \
+--gradient_checkpointing \
+--deepspeed stage1.json \
+--warmup_ratio 0.1 \
+--bf16 \
+--use_lora True \
+--lora_rank 32 \
+--lora_alpha 64 \
+--use_flash_attn True \
+--target_modules q_proj k_proj v_proj o_proj \
+--start_layer 8 \
+--head_multi True \
+--head_type simple
+```
+
+Our rerankers are initialized from [google/gemma-2b](https://huggingface.co/google/gemma-2b) (for llm-based reranker) and [openbmb/MiniCPM-2B-dpo-fp16](https://huggingface.co/openbmb/MiniCPM-2B-dpo-fp16/tree/main) (for llm-based layerwise reranker), and we train it on a mixture of multilingual datasets:
+
+- [bge-m3-data](https://huggingface.co/datasets/Shitao/bge-m3-data)
+- [quora train data](https://huggingface.co/datasets/quora)
+- [fever train data](https://fever.ai/dataset/fever.html)
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
+- llama-index.
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+![image-20240317193909373](./assets/llama-index.png)
 
-**BibTeX:**
 
-[More Information Needed]
+- BEIR.   
 
-**APA:**
+rereank the top 100 results from bge-en-v1.5 large.
 
-[More Information Needed]
+![image-20240317174633333](./assets/BEIR-bge-en-v1.5.png)
 
-## Glossary [optional]
+rereank the top 100 results from e5 mistral 7b instruct.
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+![image-20240317172949713](./assets/BEIR-e5-mistral.png)
 
-[More Information Needed]
+- CMTEB-retrieval.   
+It rereank the top 100 results from bge-zh-v1.5 large.
 
-## More Information [optional]
+![image-20240317173026235](./assets/CMTEB-retrieval-bge-zh-v1.5.png)
 
-[More Information Needed]
+- miracl (multi-language).   
+It rereank the top 100 results from bge-m3.
 
-## Model Card Authors [optional]
+![image-20240317173117639](./assets/miracl-bge-m3.png)
 
-[More Information Needed]
 
-## Model Card Contact
 
-[More Information Needed]
+## Citation
 
+If you find this repository useful, please consider giving a star and citation
 
+```bibtex
+@misc{li2023making,
+      title={Making Large Language Models A Better Foundation For Dense Retrieval}, 
+      author={Chaofan Li and Zheng Liu and Shitao Xiao and Yingxia Shao},
+      year={2023},
+      eprint={2312.15503},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL}
+}
+@misc{chen2024bge,
+      title={BGE M3-Embedding: Multi-Lingual, Multi-Functionality, Multi-Granularity Text Embeddings Through Self-Knowledge Distillation}, 
+      author={Jianlv Chen and Shitao Xiao and Peitian Zhang and Kun Luo and Defu Lian and Zheng Liu},
+      year={2024},
+      eprint={2402.03216},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL}
+}
+```