[rerank]: Refine documentation for rerank comps (opea-project#758)

* [rerank]: Refine documentation for rerank comps

Restructure and refine README documentation for rerank components.

Signed-off-by: Yeoh, Hoong Tee <[email protected]>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* rerank-doc: Break up README lines for viewing experience

Signed-off-by: Yeoh, Hoong Tee <[email protected]>

---------

Signed-off-by: Yeoh, Hoong Tee <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: chen, suyue <[email protected]>

Author: 3 people

comps/reranks/README.md

@@ -0,0 +1,35 @@
+# Reranking Microservice
+
+The Reranking Microservice, fueled by reranking models, stands as a straightforward yet immensely potent tool for semantic search.
+When provided with a query and a collection of documents, reranking swiftly indexes the documents based on their semantic relevance to the query,
+arranging them from most to least pertinent. This microservice significantly enhances overall accuracy. In a text retrieval system,
+either a dense embedding model or a sparse lexical search index is often employed to retrieve relevant text documents based on the input.
+However, a reranking model can further refine this process by rearranging potential candidates into a final, optimized order.
+
+![Flow Chart](./assets/img/reranking_flow.png)
+
+---
+
+## 🛠️ Features
+
+- **rerank on retrieved documents**: Perform reranking on the given documents using reranking models together with query.
+
+---
+
+## ⚙️ Implementation
+
+### Utilizing Reranking with fastRAG
+
+For additional information, please refer to this [README](./fastrag/README.md)
+
+### Utilizing Reranking with Mosec
+
+For additional information, please refer to this [README](./mosec/langchain/README.md)
+
+### Utilizing Reranking with TEI
+
+For additional information, please refer to this [README](./tei/README.md)
+
+### Utilizing Reranking with VideoQnA
+
+For additional information, please refer to this [README](./videoqna/README.md)

comps/reranks/assets/img/reranking_flow.png

@@ -1,6 +1,13 @@
-# Reranking Microservice
+# Reranking Microservice with fastRAG
 
-The Reranking Microservice, fueled by reranking models, stands as a straightforward yet immensely potent tool for semantic search. When provided with a query and a collection of documents, reranking swiftly indexes the documents based on their semantic relevance to the query, arranging them from most to least pertinent. This microservice significantly enhances overall accuracy. In a text retrieval system, either a dense embedding model or a sparse lexical search index is often employed to retrieve relevant text documents based on the input. However, a reranking model can further refine this process by rearranging potential candidates into a final, optimized order.
+`fastRAG` is a research framework for efficient and optimized retrieval augmented generative pipelines, incorporating state-of-the-art LLMs and Information Retrieval.
+
+Please refer to [Official fastRAG repo](https://github.com/IntelLabs/fastRAG/tree/main)
+for more information.
+
+This README provides set-up instructions and comprehensive details regarding the reranking microservice via fastRAG.
+
+---
 
 ## 🚀1. Start Microservice with Python (Option 1)
 
@@ -28,6 +35,8 @@ export EMBED_MODEL="Intel/bge-small-en-v1.5-rag-int8-static"
 python local_reranking.py
 ```
 
+---
+
 ## 🚀2. Start Microservice with Docker (Option 2)
 
 ### 2.1 Setup Environment Variables
@@ -49,21 +58,25 @@ docker build -t opea/reranking-fastrag:latest --build-arg https_proxy=$https_pro
 docker run -d --name="reranking-fastrag-server" -p 8000:8000 --ipc=host -e http_proxy=$http_proxy -e https_proxy=$https_proxy -e EMBED_MODEL=$EMBED_MODEL opea/reranking-fastrag:latest
 ```
 
-## 🚀3. Consume Reranking Service
+---
 
-### 3.1 Check Service Status
+## ✅ 3. Invoke Reranking Microservice
 
-```bash
-curl http://localhost:8000/v1/health_check \
-  -X GET \
-  -H 'Content-Type: application/json'
-```
+The Reranking microservice exposes following API endpoints:
 
-### 3.2 Consume Reranking Service
+- Check Service Status
 
-```bash
-curl http://localhost:8000/v1/reranking \
-  -X POST \
-  -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}]}' \
-  -H 'Content-Type: application/json'
-```
+  ```bash
+  curl http://localhost:8000/v1/health_check \
+    -X GET \
+    -H 'Content-Type: application/json'
+  ```
+
+- Execute reranking process by providing query and documents
+
+  ```bash
+  curl http://localhost:8000/v1/reranking \
+    -X POST \
+    -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}]}' \
+    -H 'Content-Type: application/json'
+  ```

comps/reranks/fastrag/README.md

@@ -1,33 +1,65 @@
-# build reranking Mosec endpoint docker image
+# Reranking Microservice with Mosec
 
-```
-docker build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$https_proxy -t opea/reranking-langchain-mosec-endpoint:latest -f comps/reranks/mosec/langchain/dependency/Dockerfile .
-```
+`Mosec` is a high-performance and flexible model serving framework for building ML model-enabled backend and microservices.
 
-## build reranking microservice docker image
+Please refer to [Official mosec repo](https://github.com/mosecorg/mosec)
+for more information.
 
-```
-docker build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$https_proxy -t opea/reranking-langchain-mosec:latest -f comps/reranks/mosec/langchain/Dockerfile .
-```
+This README provides set-up instructions and comprehensive details regarding the reranking microservice via mosec.
 
-## launch Mosec endpoint docker container
+---
 
-```
-docker run -d --name="reranking-langchain-mosec-endpoint" -p 6001:8000  opea/reranking-langchain-mosec-endpoint:latest
-```
+## Build Reranking Mosec Image
 
-## launch embedding microservice docker container
+- Build reranking mosec endpoint docker image.
 
-```
-export MOSEC_RERANKING_ENDPOINT=http://127.0.0.1:6001
-docker run -d --name="reranking-langchain-mosec-server" -e http_proxy=$http_proxy -e https_proxy=$https_proxy -p 6000:8000 --ipc=host -e MOSEC_RERANKING_ENDPOINT=$MOSEC_RERANKING_ENDPOINT opea/reranking-langchain-mosec:latest
-```
+  ```
+  docker build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$https_proxy -t opea/reranking-langchain-mosec-endpoint:latest -f comps/reranks/mosec/langchain/dependency/Dockerfile .
+  ```
 
-## run client test
+---
 
-```
-curl http://localhost:6000/v1/reranking \
-   -X POST \
-   -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}]}' \
-   -H 'Content-Type: application/json'
-```
+## Build Reranking Microservice Image
+
+- Build reranking microservice docker image.
+
+  ```
+  docker build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$https_proxy -t opea/reranking-langchain-mosec:latest -f comps/reranks/mosec/langchain/Dockerfile .
+  ```
+
+---
+
+## Launch Mosec Endpoint Image Container
+
+- Start the mosec endpoint image docker container.
+
+  ```
+  docker run -d --name="reranking-langchain-mosec-endpoint" -p 6001:8000  opea/reranking-langchain-mosec-endpoint:latest
+  ```
+
+---
+
+## Launch Embedding Microservice Image Container
+
+- Start the embedding microservice image docker container.
+
+  ```
+  export MOSEC_RERANKING_ENDPOINT=http://127.0.0.1:6001
+
+  docker run -d --name="reranking-langchain-mosec-server" -e http_proxy=$http_proxy -e https_proxy=$https_proxy -p 6000:8000 --ipc=host -e MOSEC_RERANKING_ENDPOINT=$MOSEC_RERANKING_ENDPOINT opea/reranking-langchain-mosec:latest
+  ```
+
+---
+
+## ✅ Invoke Reranking Microservice
+
+The Reranking microservice exposes following API endpoints:
+
+- Execute reranking process by providing query and documents
+
+  ```
+  curl http://localhost:6000/v1/reranking \
+     -X POST \
+     -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}]}' \
+     -H 'Content-Type: application/json'
+  ```

comps/reranks/mosec/langchain/README.md

@@ -1,6 +1,11 @@
-# Reranking Microservice
+# Reranking Microservice via TEI
 
-The Reranking Microservice, fueled by reranking models, stands as a straightforward yet immensely potent tool for semantic search. When provided with a query and a collection of documents, reranking swiftly indexes the documents based on their semantic relevance to the query, arranging them from most to least pertinent. This microservice significantly enhances overall accuracy. In a text retrieval system, either a dense embedding model or a sparse lexical search index is often employed to retrieve relevant text documents based on the input. However, a reranking model can further refine this process by rearranging potential candidates into a final, optimized order.
+`Text Embeddings Inference (TEI)` is a comprehensive toolkit designed for efficient deployment and serving of open source text embeddings models.
+It enable us to host our own reranker endpoint seamlessly.
+
+This README provides set-up instructions and comprehensive details regarding the reranking microservice via TEI.
+
+---
 
 ## 🚀1. Start Microservice with Python (Option 1)
 
@@ -17,7 +22,8 @@ pip install -r requirements.txt
 ```bash
 export HF_TOKEN=${your_hf_api_token}
 export RERANK_MODEL_ID="BAAI/bge-reranker-base"
-volume=$PWD/data
+export volume=$PWD/data
+
 docker run -d -p 6060:80 -v $volume:/data -e http_proxy=$http_proxy -e https_proxy=$https_proxy --pull always ghcr.io/huggingface/text-embeddings-inference:cpu-1.5 --model-id $RERANK_MODEL_ID --hf-api-token $HF_TOKEN
 ```
 
@@ -34,9 +40,12 @@ curl 127.0.0.1:6060/rerank \
 
 ```bash
 export TEI_RERANKING_ENDPOINT="http://${your_ip}:6060"
+
 python reranking_tei_xeon.py
 ```
 
+---
+
 ## 🚀2. Start Microservice with Docker (Option 2)
 
 If you start an Reranking microservice with docker, the `docker_compose_reranking.yaml` file will automatically start a TEI service with docker.
@@ -74,30 +83,34 @@ docker run -d --name="reranking-tei-server" -p 8000:8000 --ipc=host -e http_prox
 docker compose -f docker_compose_reranking.yaml up -d
 ```
 
-## 🚀3. Consume Reranking Service
+---
 
-### 3.1 Check Service Status
+## ✅3. Invoke Reranking Microservice
 
-```bash
-curl http://localhost:8000/v1/health_check \
-  -X GET \
-  -H 'Content-Type: application/json'
-```
+The Reranking microservice exposes following API endpoints:
 
-### 3.2 Consume Reranking Service
+- Check Service Status
 
-```bash
-curl http://localhost:8000/v1/reranking \
-  -X POST \
-  -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}]}' \
-  -H 'Content-Type: application/json'
-```
+  ```bash
+  curl http://localhost:8000/v1/health_check \
+    -X GET \
+    -H 'Content-Type: application/json'
+  ```
 
-You can add the parameter `top_n` to specify the return number of the reranker model, default value is 1.
+- Execute reranking process by providing query and documents
 
-```bash
-curl http://localhost:8000/v1/reranking \
-  -X POST \
-  -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}], "top_n":2}' \
-  -H 'Content-Type: application/json'
-```
+  ```bash
+  curl http://localhost:8000/v1/reranking \
+    -X POST \
+    -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}]}' \
+    -H 'Content-Type: application/json'
+  ```
+
+  - You can add the parameter `top_n` to specify the return number of the reranker model, default value is 1.
+
+  ```bash
+  curl http://localhost:8000/v1/reranking \
+    -X POST \
+    -d '{"initial_query":"What is Deep Learning?", "retrieved_docs": [{"text":"Deep Learning is not..."}, {"text":"Deep learning is..."}], "top_n":2}' \
+    -H 'Content-Type: application/json'
+  ```

comps/reranks/tei/README.md

@@ -1,8 +1,14 @@
-# Rerank Microservice
+# Rerank Microservice with VideoQnA
 
-This is a Docker-based microservice that do result rerank for VideoQnA use case. Local rerank is used rather than rerank model.
+This README provides set-up instructions and comprehensive details regarding the reranking microservice with VideoQnA.
+This microservice is designed that do result rerank for VideoQnA use case. Local rerank is used rather than rerank model.
 
-For the `VideoQnA` usecase, during the data preparation phase, frames are extracted from videos and stored in a vector database. To identify the most relevant video, we count the occurrences of each video source among the retrieved data with rerank function `get_top_doc`. This sorts the video as a descending list of names, ranked by their degree of match with the query. Then we could send the `top_n` videos to the downstream LVM.
+For the `VideoQnA` usecase, during the data preparation phase, frames are extracted from videos and stored in a vector database.
+To identify the most relevant video, we count the occurrences of each video source among the retrieved data with rerank function `get_top_doc`.
+This sorts the video as a descending list of names, ranked by their degree of match with the query.
+Then we could send the `top_n` videos to the downstream LVM.
+
+---
 
 ## 🚀1. Start Microservice with Docker
 
@@ -23,14 +29,21 @@ until docker logs reranking-videoqna-server 2>&1 | grep -q "Uvicorn running on";
 done
 ```
 
-Available configuration by environment variable:
+### 1.3 Configuration available by setting environment variable
+
+Configuration that available by setting environment variable:
 
 - CHUNK_DURATION: target chunk duration, should be aligned with VideoQnA dataprep. Default 10s.
 
-## ✅ 2. Test
+---
+
+## ✅ 2. Invoke Reranking Microservice
+
+The Reranking microservice exposes following API endpoints:
 
 ```bash
 export ip_address=$(hostname -I | awk '{print $1}')
+
 curl -X 'POST' \
 "http://${ip_address}:8000/v1/reranking" \
 -H 'accept: application/json' \
@@ -45,15 +58,14 @@ curl -X 'POST' \
       {"other_key": "value", "video":"top_video_name", "timestamp":"20"}
   ]
 }'
-```
-
-The result should be:
 
-```bash
-{"id":"random number","video_url":"http://0.0.0.0:6005/top_video_name","chunk_start":20.0,"chunk_duration":10.0,"prompt":"this is the query","max_new_tokens":512}
+# Expected output result:
+# {"id":"random number","video_url":"http://0.0.0.0:6005/top_video_name","chunk_start":20.0,"chunk_duration":10.0,"prompt":"this is the query","max_new_tokens":512}
 ```
 
-## ♻️ 3. Clean
+---
+
+## ♻️ 3. Cleaning the Container
 
 ```bash
 # remove the container