From d66ba4a59af7e869d341498ba8db1285df4fb0ac Mon Sep 17 00:00:00 2001
From: cheng-wang2002 <wangdaxia2002@outlook.com>
Date: Sun, 28 Jul 2024 04:58:28 +0800
Subject: [PATCH] Enable rag inference and evaluation

---
 contrib/rag/README.md             |  44 ++++++++
 contrib/rag/build_corpus_index.py |  87 ++++++++++++++++
 contrib/rag/corpus.dpr_index      | Bin 0 -> 41533 bytes
 contrib/rag/corpus.txt            |   1 +
 contrib/rag/rag_evaluation.py     | 130 ++++++++++++++++++++++++
 contrib/rag/rag_inference.py      | 160 ++++++++++++++++++++++++++++++
 contrib/rag/run_rag_evaluation.sh |  58 +++++++++++
 contrib/rag/run_rag_inference.sh  |  56 +++++++++++
 8 files changed, 536 insertions(+)
 create mode 100644 contrib/rag/README.md
 create mode 100644 contrib/rag/build_corpus_index.py
 create mode 100644 contrib/rag/corpus.dpr_index
 create mode 100644 contrib/rag/corpus.txt
 create mode 100644 contrib/rag/rag_evaluation.py
 create mode 100644 contrib/rag/rag_inference.py
 create mode 100644 contrib/rag/run_rag_evaluation.sh
 create mode 100644 contrib/rag/run_rag_inference.sh

diff --git a/contrib/rag/README.md b/contrib/rag/README.md
new file mode 100644
index 000000000..29866cf44
--- /dev/null
+++ b/contrib/rag/README.md
@@ -0,0 +1,44 @@
+# Retrieval-augmented generation
+
+LMFlow now supports retrieval-augmented generation. We offer four different retrieval methods which include  DPR embeddings and BM25. Also, any model supported by LMFlow can be used for generation.
+
+* DPR(Dense Passage Retrieval) Embeddings: \
+https://arxiv.org/pdf/2004.04906
+* BM25 retriever: \
+https://python.langchain.com/v0.2/docs/integrations/retrievers/bm25/
+
+## Requirements
+Faiss library is required for dataset indexing.
+```
+pip install faiss-cpu pickle rank_bm25
+```
+
+## Build indexing for custom corpus for retrieval
+If you want to use your own corpus for retrieval, first use `build_corpus_index.py` to build an index of the corpus embeddings. We offer one type of embedding method `dpr`and one retrieval method, `bm25`, which also requires indexing.
+
+Below is an example that utilizes OpenAI embedding to index a corpus using '\n\n' as the splitter.
+
+```
+python ./scripts/build_corpus_index --corpus_path='corpus.txt' --splitter='\n\n' --embedding_type='dpr' --data_index_path='corpus'
+```
+Then it would save corpus and corpus index to ```corpus.dpr_index```.
+
+## Inference and Evaluation
+
+After building indexing of corpus, you can run the script `run_rag_inference.sh` that user can directly input question, and the script `run_rag_evaluation.sh` that user can input the path of dataset.
+
+Here are two examples of each script.
+
+```
+bash ./scripts/run_rag_inference.sh --retriever_type='dpr' --corpus_index_path='corpus.dpr_index' --top_k_retrieve=5
+```
+
+```
+bash ./scripts/run_rag_evaluation.sh --retriever_type='dpr' --corpus_index_path='corpus.dpr_index' --top_k_retrieve=5
+```
+
+## Known issue
+
+Current `build_corpus_index.py` has memory issue, since it would load all corpus into memory at once, so if the size of corpus is larger than your memory, the process would be broken. Our next step is to enable our program to load corpus piece by piece, so that memory would not be an issue. Also, 
+
+
diff --git a/contrib/rag/build_corpus_index.py b/contrib/rag/build_corpus_index.py
new file mode 100644
index 000000000..027a662ce
--- /dev/null
+++ b/contrib/rag/build_corpus_index.py
@@ -0,0 +1,87 @@
+import pickle
+import os
+from transformers import AutoTokenizer, AutoModel
+from transformers import HfArgumentParser
+from dataclasses import dataclass, field
+from typing import Optional
+import torch
+import faiss
+import numpy as np
+@dataclass
+class RetrieverArguments:
+    corpus_path: str = field(
+        metadata={
+            "help": "Please specify the path to the document corpus."
+        }
+    )
+
+    embedding_type: Optional[str] = field(
+        default="dpr",
+        metadata={
+            "help": "Please specify the type of retriever: bm25, or dpr"
+        }
+    )
+    splitter: Optional[str] = field(
+        default="\n\n",
+        metadata={
+            "help": "Please specify the splitter of your document."
+        }
+    )
+    
+    data_index_path: Optional[str] = field(
+        default = './data/corpus',
+        metadata={
+            "help": "Please specify the name of data index name."
+        }
+    )
+
+    device: int = field(
+        default=0,
+        metadata={
+            "help": "The machine rank of gpu is used."
+        }
+    )
+
+    
+
+parser = HfArgumentParser((RetrieverArguments))
+retriever_args = parser.parse_args_into_dataclasses()[0]
+with open(retriever_args.corpus_path) as f:
+    text = f.read()
+texts = text.split(retriever_args.splitter)
+
+if retriever_args.embedding_type == 'dpr':
+    model_name = 'sentence-transformers/facebook-dpr-question_encoder-single-nq-base'
+    device = torch.device(f'cuda:{retriever_args.device}')
+    
+    tokenizer = AutoTokenizer.from_pretrained('sentence-transformers/facebook-dpr-question_encoder-single-nq-base')
+    model = AutoModel.from_pretrained('sentence-transformers/facebook-dpr-question_encoder-single-nq-base').to(device)
+    encoded_input = tokenizer(texts, padding=True, truncation=True, return_tensors='pt').to(device)
+
+    with torch.no_grad():
+        model_output = model(**encoded_input)
+    def cls_pooling(model_output):
+        return model_output[0][:,0]
+    embeddings = cls_pooling(model_output)
+
+
+    dim = 768
+    index = faiss.IndexFlatL2(dim)
+    index.add(embeddings.cpu().numpy())
+    chunks = faiss.serialize_index(index)
+    with open(retriever_args.data_index_path+'.dpr_index', "wb") as fp:
+        pickle.dump(texts, fp)
+        pickle.dump(chunks, fp)
+    
+elif retriever_args.embedding_type == 'bm25':
+    with open(retriever_args.data_index_path+'.bm25_index', "wb") as fp:
+        pickle.dump(texts, fp)
+else:
+    raise ValueError('The embedded method is not implemented. \
+    Please specify the type of document embedding as one of the choices, [dpr, bm25].')
+
+
+
+
+
+
diff --git a/contrib/rag/corpus.dpr_index b/contrib/rag/corpus.dpr_index
new file mode 100644
index 0000000000000000000000000000000000000000..8f075784644cd216d0154e5ad89eb6b6170170ad
GIT binary patch
literal 41533
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
AJpcdz

literal 0
HcmV?d00001

diff --git a/contrib/rag/corpus.txt b/contrib/rag/corpus.txt
new file mode 100644
index 000000000..a87d14ef5
--- /dev/null
+++ b/contrib/rag/corpus.txt
@@ -0,0 +1 @@
+In recent years, the rise of Large Language Models (LLMs) has spurred a growing demand for plug-and-play AI systems. Among the various AI techniques, prompt engineering stands out as particularly significant. However, users often face challenges in writing prompts due to the steep learning curve and significant time investment, and existing automatic prompt engineering (APE) models can be difficult to use. To address this issue, we propose PAS, an LLM-based plug-and-play APE system. PAS utilizes LLMs trained on high-quality, automatically generated prompt complementary datasets, resulting in exceptional performance. In comprehensive benchmarks, PAS achieves state-of-the-art (SoTA) results compared to previous APE models, with an average improvement of 6.09 points. Moreover, PAS is highly efficient, achieving SoTA performance with only 9000 data points. Additionally, PAS can autonomously generate prompt augmentation data without requiring additional human labor. Its flexibility also allows it to be compatible with all existing LLMs and applicable to a wide range of tasks. PAS excels in human evaluations, underscoring its suitability as a plug-in for users. This combination of high performance, efficiency, and flexibility makes PAS a valuable system for enhancing the usability and effectiveness of LLMs through improved prompt engineering.
\ No newline at end of file
diff --git a/contrib/rag/rag_evaluation.py b/contrib/rag/rag_evaluation.py
new file mode 100644
index 000000000..2bad8071d
--- /dev/null
+++ b/contrib/rag/rag_evaluation.py
@@ -0,0 +1,130 @@
+#!/usr/bin/env python
+# coding=utf-8
+# Copyright 2023 Statistics and Machine Learning Research Group at HKUST. All rights reserved.
+"""A one-line summary of the module or program, terminated by a period.
+
+Leave one blank line.  The rest of this docstring should contain an
+overall description of the module or program.  Optionally, it may also
+contain a brief description of exported classes and functions and/or usage
+examples.
+
+Typical usage example:
+
+  foo = ClassFoo()
+  bar = foo.FunctionBar()
+"""
+import json
+import os
+import sys
+sys.path.remove(os.path.abspath(os.path.dirname(sys.argv[0])))
+from transformers import HfArgumentParser
+from transformers import AutoModel as AM
+from transformers import AutoTokenizer as AT
+from dataclasses import dataclass, field
+from typing import Optional
+import torch
+
+import faiss
+import pickle
+from rank_bm25 import BM25Okapi
+
+
+from lmflow.datasets.dataset import Dataset
+from lmflow.pipeline.auto_pipeline import AutoPipeline
+from lmflow.models.auto_model import AutoModel
+from lmflow.args import ModelArguments, DatasetArguments, AutoArguments
+
+@dataclass
+class RAGEvalArguments:
+    retriever_type: Optional[str] = field(
+        default='dpr',
+        metadata={
+            "help": "Please specify the type of document embedding: dpr, and bm25"
+        }
+    )
+    corpus_index_path: Optional[str] = field(
+        default="corpus.dpr_index",
+        metadata={
+            "help": "Please specify the path of corpus index. If you select wiki search, you do not need specify it."
+        }
+    )
+    prompt_structure: Optional[str] = field(
+        default="Answer the following question based on the background information.\n\nQuestion:{input_text}\n\nBackground:{background}\n\nAnswer:",
+        metadata={
+            "help": "prompt structure given user's input text."
+        },
+    )
+    top_k_retrieve: int = field(
+        default=5,
+        metadata={
+            "help": "Please specify the number of the most relevant documents to be retrieved."
+        }
+    )
+
+pipeline_name = "evaluator"
+PipelineArguments = AutoArguments.get_pipeline_args_class(pipeline_name)
+
+parser = HfArgumentParser((ModelArguments, DatasetArguments, PipelineArguments, RAGEvalArguments))
+model_args, data_args, pipeline_args, rag_args = parser.parse_args_into_dataclasses()
+
+with open (pipeline_args.deepspeed, "r") as f:
+    ds_config = json.load(f)
+
+model = AutoModel.get_model(
+    model_args, 
+    tune_strategy='none', 
+    ds_config=ds_config, 
+    use_accelerator=pipeline_args.use_accelerator_for_evaluator
+)
+top_k = rag_args.top_k_retrieve
+if rag_args.retriever_type == 'dpr':
+    with open(rag_args.corpus_index_path, 'rb') as fp:
+        corpus = pickle.load(fp)
+        index = faiss.deserialize_index(pickle.load(fp))
+
+    model_name = 'sentence-transformers/facebook-dpr-question_encoder-single-nq-base'
+    tokenizer = AT.from_pretrained(model_name)
+    embed = AM.from_pretrained(model_name)
+    def cls_pooling(model_output):
+        return model_output[0][:,0]
+
+elif rag_args.retriever_type == 'bm25':
+    with open(rag_args.corpus_index_path, "rb") as fp:
+        corpus = pickle.load(fp)
+    tokenized_corpus = [doc.split(" ") for doc in corpus]
+    bm25 = BM25Okapi(tokenized_corpus)
+else:
+    raise ValueError('The type of retriever you specify is not implemented. Please specify it as one of [openai_embed, dpr_embed, wiki]')
+
+dataset = Dataset(data_args)
+
+data_dict = dataset.to_dict()
+
+for i, instance in enumerate(data_dict["instances"]):
+    input_text = instance['input']
+    
+    if rag_args.retriever_type == 'dpr':
+        encoded_input = tokenizer(input_text, padding=True, truncation=True, return_tensors='pt')
+        with torch.no_grad():
+            model_output = embed(**encoded_input)
+        embeddings = cls_pooling(model_output).numpy()
+
+        _, ids = index.search(embeddings, k=top_k)
+        docs = [corpus[int(id)] for id in ids[0]]
+    elif rag_args.retriever_type == 'bm25':
+        tokenized_query = input_text.split()
+        docs = bm25.get_top_n(tokenized_query, corpus, n=top_k)
+    
+    background = '\n'.join(docs)
+    all_input = rag_args.prompt_structure.format(input_text=input_text, background=background)
+    data_dict["instances"][i] = all_input
+
+dataset = dataset.from_dict(data_dict)
+
+evaluator = AutoPipeline.get_pipeline(
+    pipeline_name=pipeline_name,
+    model_args=model_args,
+    data_args=data_args,
+    pipeline_args=pipeline_args,
+)
+evaluator.evaluate(model=model, dataset=dataset, metric=pipeline_args.metric)
diff --git a/contrib/rag/rag_inference.py b/contrib/rag/rag_inference.py
new file mode 100644
index 000000000..6e7a31ff0
--- /dev/null
+++ b/contrib/rag/rag_inference.py
@@ -0,0 +1,160 @@
+#!/usr/bin/env python
+# coding=utf-8
+# Copyright 2023 Statistics and Machine Learning Research Group at HKUST. All rights reserved.
+"""A simple shell chatbot implemented with lmflow APIs.
+"""
+import logging
+import json
+import os
+import sys
+sys.path.remove(os.path.abspath(os.path.dirname(sys.argv[0])))
+import warnings
+import pickle
+import faiss
+import pickle
+import torch
+from rank_bm25 import BM25Okapi
+
+from dataclasses import dataclass, field
+from transformers import HfArgumentParser
+from transformers import AutoModel as AM
+from transformers import AutoTokenizer as AT
+from typing import Optional
+
+from lmflow.datasets.dataset import Dataset
+from lmflow.pipeline.auto_pipeline import AutoPipeline
+from lmflow.models.auto_model import AutoModel
+from lmflow.args import ModelArguments, DatasetArguments, AutoArguments
+
+
+
+
+logging.disable(logging.ERROR)
+warnings.filterwarnings("ignore")
+
+
+@dataclass
+class RAGInferArguments:
+    retriever_type: Optional[str] = field(
+        default='dpr',
+        metadata={
+            "help": "Please specify the type of document embedding: dpr, or bm25"
+        }
+    )
+    corpus_index_path: Optional[str] = field(
+        default="corpus.dpr_index",
+        metadata={
+            "help": "Please specify the path of corpus index. If you select wiki search, you do not need specify it."
+        }
+    )
+    prompt_structure: Optional[str] = field(
+        default="Answer the following question based on the background information.\n\nQuestion:{input_text}\n\nBackground:{background}\n\nAnswer:",
+        metadata={
+            "help": "prompt structure given user's input text and background information."
+        },
+    )
+    top_k_retrieve: int = field(
+        default=5,
+        metadata={
+            "help": "Please specify the number of the most relevant documents to be retrieved."
+        }
+    )
+
+logging.disable(logging.ERROR)
+warnings.filterwarnings("ignore")
+
+def main():
+    pipeline_name = "inferencer"
+    PipelineArguments = AutoArguments.get_pipeline_args_class(pipeline_name)
+
+    parser = HfArgumentParser((
+        ModelArguments,
+        PipelineArguments,
+        RAGInferArguments
+    ))
+    model_args, pipeline_args, rag_args = parser.parse_args_into_dataclasses()
+    inferencer_args = pipeline_args
+
+    with open (pipeline_args.deepspeed, "r") as f:
+        ds_config = json.load(f)
+
+    model = AutoModel.get_model(
+        model_args,
+        tune_strategy='none',
+        ds_config=ds_config,
+        device=pipeline_args.device,
+        use_accelerator=True,
+    )
+
+    # We don't need input data, we will read interactively from stdin
+    data_args = DatasetArguments(dataset_path=None)
+    dataset = Dataset(data_args)
+
+    inferencer = AutoPipeline.get_pipeline(
+        pipeline_name=pipeline_name,
+        model_args=model_args,
+        data_args=data_args,
+        pipeline_args=pipeline_args,
+    )
+
+    # Inferences
+    model_name = model_args.model_name_or_path
+    if model_args.lora_model_path is not None:
+        model_name += f" + {model_args.lora_model_path}"
+    
+    top_k = rag_args.top_k_retrieve
+    if rag_args.retriever_type == 'dpr':
+        with open(rag_args.corpus_index_path, 'rb') as fp:
+            corpus = pickle.load(fp)
+            index = faiss.deserialize_index(pickle.load(fp))
+
+        model_name = 'sentence-transformers/facebook-dpr-question_encoder-single-nq-base'
+        tokenizer = AT.from_pretrained(model_name)
+        embed = AM.from_pretrained(model_name)
+        def cls_pooling(model_output):
+            return model_output[0][:,0]
+
+    elif rag_args.retriever_type == 'bm25':
+        with open(rag_args.corpus_index_path, "rb") as fp:
+            corpus = pickle.load(fp)
+        tokenized_corpus = [doc.split(" ") for doc in corpus]
+        bm25 = BM25Okapi(tokenized_corpus)
+    else:
+        raise ValueError('The type of retriever you specify is not implemented. Please specify it as one of [openai_embed, dpr_embed, wiki]')
+    
+    while True:
+        input_text = input("User >>> ")
+        prompt = rag_args.prompt_structure
+        
+        if rag_args.retriever_type == 'dpr':
+            encoded_input = tokenizer(input_text, padding=True, truncation=True, return_tensors='pt')
+            with torch.no_grad():
+                model_output = embed(**encoded_input)
+            embeddings = cls_pooling(model_output).numpy()
+
+            _, ids = index.search(embeddings, k=top_k)
+            docs = [corpus[int(id)] for id in ids[0]]
+        elif rag_args.retriever_type == 'bm25':
+            tokenized_query = input_text.split()
+            docs = bm25.get_top_n(tokenized_query, corpus, n=top_k)
+
+        background = '\n'.join(docs)
+        background = background[-(model.get_max_length()-len(input_text)-len(prompt)):]
+        all_input = prompt.format(input_text=input_text, background=background)
+        input_dataset = dataset.from_dict({
+            "type": "text_only",
+            "instances": [ { "text": all_input } ]
+        })
+        output_dataset = inferencer.inference(
+            model=model,
+            dataset=input_dataset,
+            max_new_tokens=inferencer_args.max_new_tokens,
+            temperature=inferencer_args.temperature,
+        )
+        output = output_dataset.to_dict()["instances"][0]["text"]
+        print('Bot:')
+        print(output)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/contrib/rag/run_rag_evaluation.sh b/contrib/rag/run_rag_evaluation.sh
new file mode 100644
index 000000000..34615eefb
--- /dev/null
+++ b/contrib/rag/run_rag_evaluation.sh
@@ -0,0 +1,58 @@
+#!/bin/bash
+
+if [ ! -d data/MedQA-USMLE ]; then
+  cd data && ./download.sh MedQA-USMLE && cd -
+fi
+
+lora_args=""
+retriever_type=""
+corpus_index_path=""
+prompt_structure=""
+
+top_k=""
+while [[ $# -ge 1 ]]; do
+  key="$1"
+  case ${key} in
+    -m|--model_name_or_path)
+      model="$2"
+      shift
+      ;;
+    --lora_model_path)
+      lora_args="--lora_model_path $2"
+      shift
+      ;;
+    -r|--retriever_type)
+      retriever_type="--retriever_type $2"
+      shift
+      ;;
+    --corpus_index_path)
+      corpus_index_path="--corpus_index_path $2"
+      shift
+      ;;
+    --prompt_structure)
+      prompt_structure="--prompt_structure $2"
+      shift
+      ;;
+    --top_k_retrieve)
+      top_k="--top_k_retrieve $2"
+      shift
+      ;;
+    *)
+      echo "error: unknown option \"${key}\"" 1>&2
+      exit 1
+  esac
+  shift
+done
+
+CUDA_VISIBLE_DEVICES=0 \
+  deepspeed examples/rag_evaluation.py \
+  --answer_type medmcqa \
+  --model_name_or_path gpt2 \
+  --dataset_path data/MedQA-USMLE/validation \
+  --deepspeed examples/ds_config.json \
+  --inference_batch_size_per_device 1 \
+  --metric accuracy
+  ${retriever_type} \
+  ${corpus_index_path} \
+  ${prompt_structure} \
+  ${top_k}
diff --git a/contrib/rag/run_rag_inference.sh b/contrib/rag/run_rag_inference.sh
new file mode 100644
index 000000000..73373b1e7
--- /dev/null
+++ b/contrib/rag/run_rag_inference.sh
@@ -0,0 +1,56 @@
+#!/bin/bash
+# An interactive inference script without context history, i.e. the chatbot
+# won't have conversation memory.
+
+model=gpt2
+lora_args=""
+retriever_type=""
+corpus_index_path=""
+prompt_structure=""
+top_k=""
+while [[ $# -ge 1 ]]; do
+  key="$1"
+  case ${key} in
+    -m|--model_name_or_path)
+      model="$2"
+      shift
+      ;;
+    --lora_model_path)
+      lora_args="--lora_model_path $2"
+      shift
+      ;;
+    -r|--retriever_type)
+      retriever_type="--retriever_type $2"
+      shift
+      ;;
+    --corpus_index_path)
+      corpus_index_path="--corpus_index_path $2"
+      shift
+      ;;
+    --prompt_structure)
+      prompt_structure="--prompt_structure $2"
+      shift
+      ;;
+    --top_k_retrieve)
+      top_k="--top_k_retrieve $2"
+      shift
+      ;;
+    *)
+      echo "error: unknown option \"${key}\"" 1>&2
+      exit 1
+  esac
+  shift
+done
+
+accelerate launch --config_file ../../configs/accelerator_singlegpu_config.yaml \
+  rag_inference.py \
+    --deepspeed ../../configs/ds_config_chatbot.json \
+    --model_name_or_path ${model} \
+    --use_accelerator True \
+    --max_new_tokens 256 \
+    --temperature 1.0 \
+    ${lora_args} \
+    ${retriever_type} \
+    ${corpus_index_path} \
+    ${prompt_structure} \
+    ${top_k}