### Install FlashRAG Project and Dependencies

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/introduction_for_beginners_en.md

Installs the FlashRAG project and its required dependencies from a Git repository. It clones the repository, navigates into the directory, and then installs the project using pip. Note that some packages like vllm, fschat, or pyserini can be optionally commented out if they cause installation issues, as they are not critical for the documented workflow.

```bash
git clone https://github.com/RUC-NLPIR/FlashRAG.git
cd FlashRAG
pip install -e .
```

--------------------------------

### Launch FlashRAG Web UI Interface

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Start the FlashRAG web interface by navigating to the webui directory and executing the Python interface script. This command initializes the user-friendly UI for configuration management, RAG method testing, and benchmark reproduction.

```bash
cd webui
python interface.py
```

--------------------------------

### Example YAML Configuration for FlashRAG

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/configuration.md

Provides a sample YAML configuration file for FlashRAG, detailing global paths for models and indexes, as well as environment and retrieval settings.

```YAML
# basic settings

# ------------------------------------------------Global Paths------------------------------------------------#
# Paths to various models
model2path:
  e5: "intfloat/e5-base-v2"
  bge: "intfloat/e5-base-v2"
  contriever: "facebook/contriever"
  llama2-7B-chat: "meta-llama/Llama-2-7b-chat-hf"
  llama2-7B: "meta-llama/Llama-2-7b-hf"
  llama2-13B: "meta-llama/Llama-2-13b-hf"
  llama2-13B-chat: "meta-llama/Llama-2-13b-chat-hf"
  
# Pooling methods for each embedding model
model2pooling:
  e5: "mean"
  bge: "cls"
  contriever: "mean"
  jina: 'mean'
  dpr: cls

# Indexes path for retrieval models
method2index:
  e5: ~
  bm25: ~
  contriever: ~

# ------------------------------------------------Environment Settings------------------------------------------------#
# Directory paths for data and outputs
data_dir: "dataset/"
save_dir: "output/"

gpu_id: "0,1,2,3"
dataset_name: "nq" # name of the dataset in data_dir
split: ["test"]  # dataset split to load (e.g. train,dev,test)

# Sampling configurations for testing
test_sample_num: ~  # number of samples to test (only work in dev/test split), if None, test all samples
random_sample: False # whether to randomly sample the test samples

# Seed for reproducibility
seed: 2024

# Whether save intermediate data
save_intermediate_data: True
save_note: 'experiment'

# -------------------------------------------------Retrieval Settings------------------------------------------------#

```

--------------------------------

### Install Seismic and Rust for SPLADE Indexing

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Installs Rust, a prerequisite for compiling the Seismic index, and then installs the pyseismic-lsr Python package. These steps are necessary before building an index with SPLADE.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Install Rust for compiling
pip install pyseismic-lsr # Install Seismic
```

--------------------------------

### Execute Pipeline and Get Results (Python)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Illustrates how to run the initialized pipeline with test data and specifies `do_eval=True` to include evaluation in the process. The output dataset contains intermediate results and metric scores.

```python
output_dataset = pipeline.run(test_data, do_eval=True)
```

--------------------------------

### Download Wikipedia Dump (Bash)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/process-wiki.md

Downloads a specified Wikipedia dump file in XML format using wget. This is the initial step to obtain the raw data for corpus creation. Ensure you have wget installed and sufficient disk space.

```bash
wget https://archive.org/download/enwiki-20181220/enwiki-20181220-pages-articles.xml.bz2
```

--------------------------------

### Configure Multi-Retriever with Reranking Merge

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Demonstrates how to configure FlashRAG to use multiple retrieval methods simultaneously and merge their results using a reranking strategy. It sets up two retrievers ('e5' and 'bm25') with their respective configurations and specifies a reranking model. The `get_retriever` function initializes a router that combines results, which are then searched using a query. The example prints the number of combined results and snippets of the top documents.

```python
from flashrag.config import Config
from flashrag.utils import get_retriever

# Configure multiple retrievers with reranking merge
config = Config(config_dict={
    'use_multi_retriever': True,
    'multi_retriever_setting': {
        'merge_method': 'rerank',  # Options: 'concat', 'rrf', 'rerank'
        'retriever_list': [
            {
                'retrieval_method': 'e5',
                'model2path': {'e5': 'intfloat/e5-base-v2'},
                'index_path': 'indexes/e5_Flat.index',
                'corpus_path': 'indexes/wiki_corpus.jsonl',
                'retrieval_topk': 10
            },
            {
                'retrieval_method': 'bm25',
                'index_path': 'indexes/bm25_index/',
                'corpus_path': 'indexes/wiki_corpus.jsonl',
                'bm25_backend': 'bm25s',
                'retrieval_topk': 10
            }
        ],
        'rerank_model_name': 'bge-reranker',
        'rerank_model_path': 'BAAI/bge-reranker-base',
        'rerank_max_length': 512,
        'rerank_batch_size': 256
    },
    'retrieval_topk': 5,
    'model2path': {
        'e5': 'intfloat/e5-base-v2',
        'bge-reranker': 'BAAI/bge-reranker-base'
    }
})

# Initialize multi-retriever router
retriever = get_retriever(config)

# Search combines results from all retrievers
query = "What is quantum computing?"
results = retriever.search(query, num=5)
print(f"Combined top results: {len(results)}")
for i, doc in enumerate(results):
    print(f"[{i+1}] Score: {doc.get('score', 'N/A')}, Content: {doc['contents'][:100]}...")

```

--------------------------------

### Initialize FlashRAG Configuration and Load Dataset (Python)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Demonstrates how to define a configuration dictionary, create a Config object, load a dataset using get_dataset, and extract test data.

```python
from flashrag.utils import get_dataset
from flashrag.pipeline import SequentialPipeline
from flashrag.prompt import PromptTemplate
from flashrag.config import Config

config_dict = {'data_dir': 'dataset/'}
my_config = Config(
    config_file_path = 'my_config.yaml',
    config_dict = config_dict
)
all_split = get_dataset(my_config)
test_data = all_split['test']

pipeline = SequentialPipeline(my_config)
```

--------------------------------

### Load Dataset and Sequential Pipeline with Python

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/introduction_for_beginners_en.md

Loads the dataset using the configuration and initializes the SequentialPipeline for a standard RAG process. The pipeline automatically loads necessary components like the retriever and generator. Dependencies include flashrag.utils and flashrag.pipeline modules.

```python
from flashrag.utils import get_dataset
from flashrag.pipeline import SequentialPipeline

all_split = get_dataset(config)
test_data = all_split['test']
pipeline = SequentialPipeline(config)
```

--------------------------------

### Customize Pipeline with PromptTemplate (Python)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Shows how to define a custom prompt template using PromptTemplate with system and user prompts, and then initialize a SequentialPipeline with this custom template.

```python
prompt_templete = PromptTemplate(
    config,
    system_prompt = "Answer the question based on the given document. Only give me the answer and do not output any other words.\nThe following are given documents.\n\n{reference}",
    user_prompt = "Question: {question}\nAnswer:"
)
pipeline = SequentialPipeline(
  my_config,
  prompt_template = prompt_templete
)
```

--------------------------------

### Initialize Config with Parameter Dictionary (Python)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/configuration.md

Illustrates the initialization of the FlashRAG Config object using a Python dictionary, providing a flexible way to define parameters directly within the code.

```Python
from flashrag.config import Config
config_dict = {'generator_model': 'llama2-7B'}
config = Config(config_dict=config_dict)
```

--------------------------------

### Configure Pipeline with LLMLingua Refiner in Python

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Set up a FlashRAG pipeline using LLMLingua for context refinement, which compresses retrieved documents to a specified ratio before generation. The configuration includes retrieval parameters, refiner settings with compression ratio, and generator model selection. After initialization, the pipeline processes test data and outputs original retrieval results, refined context, and predictions.

```python
config = Config(config_dict={
    'data_dir': 'dataset/',
    'dataset_name': 'nq',
    'retrieval_method': 'e5',
    'index_path': 'indexes/e5_Flat.index',
    'corpus_path': 'indexes/wiki_corpus.jsonl',
    'retrieval_topk': 10,
    'refiner_name': 'llmlingua',
    'refiner_model_path': 'microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank',
    'refiner_compress_ratio': 0.5,
    'generator_model': 'llama3-8B-instruct',
    'generator_model_path': 'meta-llama/Meta-Llama-3-8B-Instruct',
    'framework': 'vllm',
    'metrics': ['em', 'f1']
})

test_data = get_dataset(config)['test']
pipeline = SequentialPipeline(config)
output_dataset = pipeline.run(test_data, do_eval=True)

print(f"Original retrieval: {output_dataset.retrieval_result[0]}")
print(f"Refined context: {output_dataset.refine_result[0]}")
print(f"Prediction: {output_dataset.pred[0]}")
```

--------------------------------

### Build Custom Pipeline by Inheriting BasicPipeline (Python)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Provides a template for creating a custom pipeline by inheriting from `BasicPipeline`. It shows the structure for initializing components and implementing the `run` method, including accessing dataset attributes and updating outputs.

```python
from flashrag.pipeline import BasicPipeline
from flashrag.utils import get_retriever, get_generator

class ToyPipeline(BasicPipeline):
  def __init__(self, config, prompt_templete=None):
    # Load your own components
    pass

  def run(self, dataset, do_eval=True):
    # Complete your own process logic

    # get attribute in dataset using `.`
    input_query = dataset.question
    ...
    # use `update_output` to save intermeidate data
    dataset.update_output("pred",pred_answer_list)
    dataset = self.evaluate(dataset, do_eval=do_eval)
    return dataset
```

--------------------------------

### Run FlashRAG Experiment with Bash Command

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/reproduce_experiment.md

Execute an experiment on the NQ dataset using the run_exp.py script with specified method, split, dataset, and GPU configuration. This command demonstrates how to run RAG methods with multi-GPU support.

```bash
python run_exp.py --method_name 'naive' \
                  --split 'test' \
                  --dataset_name 'nq' \
                  --gpu_id '0,1,2,3'
```

--------------------------------

### Initialize Config with YAML File Path (Python)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/configuration.md

Shows how to load configuration parameters from a YAML file using the FlashRAG Config object. Users must ensure the YAML file is correctly formatted and paths are accessible.

```Python
from flashrag.config import Config
config = Config(config_file_path='myconfig.yaml')
```

--------------------------------

### Build Sparse Retrieval Index with Pyserini Backend

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Builds an index for sparse retrieval using the BM25 algorithm with the 'pyserini' backend. Similar to the 'bm25s' backend, it requires the corpus path and save directory, and does not need a `model_path`.

```bash
python -m flashrag.retriever.index_builder \
  --retrieval_method bm25 \
  --corpus_path indexes/sample_corpus.jsonl \
  --bm25_backend pyserini \
  --save_dir indexes/
```

--------------------------------

### Run RAG Process and Evaluate with Python

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/introduction_for_beginners_en.md

Executes the RAG process on the test dataset using the initialized pipeline and performs evaluation. The output dataset contains intermediate and final results, with predictions available in the 'pred' attribute. Results are saved to an experiment-specific folder. Dependencies include previously set up config, dataset, and pipeline.

```python
from flashrag.config import Config
from flashrag.utils import get_dataset
from flashrag.pipeline import SequentialPipeline

config_dict = { 
                'data_dir': 'dataset/',
                'index_path': 'indexes/e5_Flat.index',
                'corpus_path': 'indexes/general_knowledge.jsonl',
                'model2path': {'e5': <retriever_path>, 'llama2-7B-chat': <generator_path>},
                'generator_model': 'llama2-7B-chat',
                'retrieval_method': 'e5',
                'metrics': ['em','f1','acc'],
                'retrieval_topk': 1,
                'save_intermediate_data': True
            }

config = Config(config_dict = config_dict)

all_split = get_dataset(config)
test_data = all_split['test']
pipeline = SequentialPipeline(config)

output_dataset = pipeline.run(test_data,do_eval=True)
print("---generation output---")
print(output_dataset.pred)
```

--------------------------------

### Load FlashRAG Configuration

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Demonstrates how to load the configuration for the entire RAG process using the `Config` class from FlashRAG. This configuration can be loaded from YAML files or directly from variables, with variables taking precedence.

```python
from flashrag.config import Config
```

--------------------------------

### Initialize Config with Dictionary Access (Python)

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/configuration.md

Demonstrates how to initialize the FlashRAG Config object using a Python dictionary for parameter settings. This method allows for direct access to parameters like a dictionary.

```Python
from flashrag.config import Config
config_dict = {'generator_model': 'llama2-7B'}
config = Config(config_dict=config_dict)
model_name = config['generator_model']
```

--------------------------------

### Configure Complete RAG Pipeline

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Sets up and runs a standard Retrieval-Augmented Generation (RAG) pipeline. It configures data loading, retrieval (using 'e5' model), generation (using 'llama3-8B-instruct' with vLLM), and evaluation. The pipeline is then executed on test data, and results like predictions, retrieval information, and generated prompts are printed. It also shows how to run a naive generation without retrieval for comparison.

```python
from flashrag.config import Config
from flashrag.dataset import get_dataset
from flashrag.prompt import PromptTemplate
from flashrag.pipeline import SequentialPipeline

# Configure complete RAG pipeline
config = Config(config_dict={
    'data_dir': 'dataset/',
    'dataset_name': 'nq',
    'split': ['test'],
    'test_sample_num': 100,

    # Retrieval settings
    'retrieval_method': 'e5',
    'model2path': {'e5': 'intfloat/e5-base-v2'},
    'index_path': 'indexes/e5_Flat.index',
    'corpus_path': 'indexes/general_knowledge.jsonl',
    'retrieval_topk': 5,
    'use_reranker': False,

    # Generator settings
    'generator_model': 'llama3-8B-instruct',
    'model2path': {
        'llama3-8B-instruct': 'meta-llama/Meta-Llama-3-8B-Instruct'
    },
    'framework': 'vllm',
    'generator_batch_size': 8,
    'generation_params': {'max_new_tokens': 32, 'temperature': 0.0},

    # Refiner settings (optional)
    'refiner_name': None,  # Options: 'llmlingua', 'selective-context', etc.

    # Evaluation settings
    'metrics': ['em', 'f1'],
    'save_intermediate_data': True,
    'save_metric_score': True,
    'save_dir': 'results/'
})

# Load dataset
all_splits = get_dataset(config)
test_data = all_splits['test']

# Initialize pipeline with custom prompt
prompt_template = PromptTemplate(
    config,
    system_prompt="Answer the question based on the given document. "
                 "Only give me the answer and do not output any other words.\n"
                 "The following are given documents.\n\n{reference}",
    user_prompt="Question: {question}\nAnswer:"
)

pipeline = SequentialPipeline(config, prompt_template=prompt_template)

# Run pipeline with evaluation
output_dataset = pipeline.run(test_data, do_eval=True)

# Access results
print(f"Predictions: {output_dataset.pred[:5]}")
print(f"Retrieval results: {output_dataset.retrieval_result[0]}")
print(f"Generated prompts: {output_dataset.prompt[0]}")

# Run naive generation (without retrieval)
naive_output = pipeline.naive_run(test_data, do_eval=True)
print(f"Naive predictions: {naive_output.pred[:5]}")

```

--------------------------------

### Create Interactive Streamlit RAG Demo Application in Python

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Build an interactive web application using Streamlit that enables real-time retrieval and generation with configurable parameters. Users can adjust temperature, number of retrieved documents, and token limits via sidebar controls. The app retrieves relevant documents, displays them expandably, and generates answers using a prompt template that incorporates retrieved context.

```python
import streamlit as st
from flashrag.config import Config
from flashrag.utils import get_retriever, get_generator
from flashrag.prompt import PromptTemplate

config_dict = {
    'model2path': {
        'e5': 'intfloat/e5-base-v2',
        'llama3-8B-instruct': 'meta-llama/Meta-Llama-3-8B-Instruct'
    },
    'retrieval_method': 'e5',
    'generator_model': 'llama3-8B-instruct',
    'framework': 'vllm',
    'corpus_path': 'indexes/general_knowledge.jsonl',
    'index_path': 'indexes/e5_Flat.index',
    'generator_max_input_len': 2048
}

@st.cache_resource
def load_components():
    config = Config(config_dict=config_dict)
    retriever = get_retriever(config)
    generator = get_generator(config)
    return config, retriever, generator

st.title("⚡FlashRAG Demo")
st.sidebar.title("Configuration")
temperature = st.sidebar.slider("Temperature:", 0.01, 1.0, 0.7)
topk = st.sidebar.slider("Retrieved documents:", 1, 10, 5)
max_tokens = st.sidebar.slider("Max tokens:", 1, 512, 128)

query = st.text_area("Enter your question:")
config, retriever, generator = load_components()

if st.button("Generate Answer"):
    with st.spinner("Processing..."):
        docs = retriever.search(query, num=topk)
        st.subheader("Retrieved Documents", divider="gray")
        for i, doc in enumerate(docs):
            with st.expander(f"Document {i+1}"):
                st.write(doc['contents'])
        prompt_template = PromptTemplate(
            config,
            system_prompt="Answer based on the documents.\n\n{reference}",
            user_prompt="Question: {question}\nAnswer:"
        )
        prompt = prompt_template.get_string(
            question=query,
            retrieval_result=docs
        )
        answer = generator.generate(
            [prompt],
            temperature=temperature,
            max_new_tokens=max_tokens
        )[0]
        st.subheader("Answer", divider="gray")
        st.write(answer)
```

--------------------------------

### Initialize OpenAI API Generator

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Configure a generator using OpenAI's GPT-4 model via API. Minimal configuration required with model name and generation parameters for cloud-based inference.

```python
openai_config = Config(config_dict={
    'framework': 'openai',
    'generator_model': 'gpt-4',
    'generation_params': {
        'max_tokens': 256,
        'temperature': 0.7
    }
})
openai_generator = get_generator(openai_config)
```

--------------------------------

### Initialize vLLM Generator for Optimized Inference

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Configure a vLLM generator framework for faster inference with LLaMA models. Supports higher batch sizes and optimized generation parameters for production deployments.

```python
vllm_config = Config(config_dict={
    'generator_model': 'llama3-8B-instruct',
    'generator_model_path': 'meta-llama/Meta-Llama-3-8B-Instruct',
    'framework': 'vllm',
    'generator_batch_size': 16,
    'generation_params': {
        'max_new_tokens': 256,
        'temperature': 0.0
    }
})
vllm_generator = get_generator(vllm_config)
```

--------------------------------

### Create Custom Prompt Template for RAG

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Define custom prompt templates with system and user prompts for RAG generation. Supports dynamic formatting with retrieved document references and customizable reference templates. Enables zero-shot generation without retrieval context.

```python
from flashrag.prompt import PromptTemplate
from flashrag.config import Config

config = Config(config_dict={
    'generator_model': 'llama3-8B-instruct',
    'generator_model_path': 'meta-llama/Meta-Llama-3-8B-Instruct',
    'framework': 'hf',
    'generator_max_input_len': 2048
})

prompt_template = PromptTemplate(
    config,
    system_prompt="Answer the question based on the given document. Only give me the answer and do not output any other words.\nThe following are given documents.\n\n{reference}",
    user_prompt="Question: {question}\nAnswer:"
)

retrieval_result = [
    {'contents': 'Paris\nParis is the capital and largest city of France.'},
    {'contents': 'France\nFrance is a country in Western Europe.'}
]

question = "What is the capital of France?"
formatted_prompt = prompt_template.get_string(
    question=question,
    retrieval_result=retrieval_result
)
print(formatted_prompt)

custom_template = PromptTemplate(
    config,
    system_prompt="Use the following documents to answer the question.\n\n{reference}",
    user_prompt="Question: {question}\nAnswer:",
    reference_template="[{idx}] Title: {title}\nContent: {text}\n\n"
)

zeroshot_template = PromptTemplate(
    config,
    system_prompt="Answer the question based on your own knowledge.",
    user_prompt="Question: {question}\nAnswer:"
)
zeroshot_prompt = zeroshot_template.get_string(question=question)
```

--------------------------------

### Available FlashRAG Methods List

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/reproduce_experiment.md

String representation of supported method names that can be used with the method_name parameter in run_exp.py. Includes various retrieval and generation strategies.

```text
naive zero-shot AAR-contriever llmlingua recomp selective-context sure replug skr flare iterretgen ircot trace
```

--------------------------------

### Initialize HuggingFace Generator with LLaMA

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Configure and initialize a HuggingFace decoder-only generator using LLaMA-3-8B-Instruct model. Supports customizable generation parameters including max tokens, sampling, temperature, and top-p settings. Enables batch processing of prompts.

```python
from flashrag.utils import get_generator
from flashrag.config import Config

config = Config(config_dict={
    'generator_model': 'llama3-8B-instruct',
    'model2path': {
        'llama3-8B-instruct': 'meta-llama/Meta-Llama-3-8B-Instruct'
    },
    'framework': 'hf',
    'generator_max_input_len': 2048,
    'generator_batch_size': 4,
    'device': 'cuda',
    'generation_params': {
        'max_new_tokens': 256,
        'do_sample': False,
        'temperature': 0.7,
        'top_p': 0.9
    }
})

generator = get_generator(config)

prompts = [
    "Question: What is the capital of France?\nAnswer:",
    "Question: Who wrote Romeo and Juliet?\nAnswer:"
]
responses = generator.generate(prompts)
for prompt, response in zip(prompts, responses):
    print(f"{prompt} {response}")
```

--------------------------------

### Load Configuration with Python Dictionary

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/introduction_for_beginners_en.md

Loads the Config object by providing a Python dictionary with experiment parameters. This allows overriding default internal parameters for data paths, model paths, and experiment settings. Dependencies include the flashrag.config module.

```python
from flashrag.config import Config

config_dict = { 
    'data_dir': 'dataset/',
    'index_path': 'indexes/e5_Flat.index',
    'corpus_path': 'indexes/general_knowledge.jsonl',
    'model2path': {'e5': <retriever_path>, 'llama2-7B-chat': <generator_path>},
    'generator_model': 'llama2-7B-chat',
    'retrieval_method': 'e5',
    'metrics': ['em', 'f1', 'acc'],
    'retrieval_topk': 1,
    'save_intermediate_data': True
}

config = Config(config_dict=config_dict)
```

--------------------------------

### Build Neural Sparse Retrieval Index with SPLADE and Seismic

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Builds an index for neural sparse retrieval using SPLADE with the Seismic index. This command requires specifying the model path, corpus paths (embedded and raw), save directory, and various Seismic-specific parameters for optimal index construction.

```bash
python -m flashrag.retriever.index_builder \
        --retrieval_method splade \
        --model_path retriever/splade-v3 \
        --corpus_embedded_path data/ms_marco/ms_marco_embedded_corpus.jsonl \
        --corpus_path data/ms_marco/ms_marco_corpus.jsonl \
        --save_dir indexes/ \
        --use_fp16 \
        --max_length 512 \
        --batch_size 4 \
        --n_postings 1000 \
        --centroid_fraction 0.2 \
        --min_cluster_size 2 \
        --summary_energy 0.4 \
        --batched_indexing 10000000 \
        --nknn 32
```

--------------------------------

### Build Dense Retrieval Index with FAISS using Sentence Transformers

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/building-index.md

Builds a dense retrieval index using FAISS, leveraging the `sentence-transformers` library. This simplifies index building as pooling method selection is handled automatically. Requires specifying retrieval method, model path, corpus path, and save directory.

```bash
python -m flashrag.retriever.index_builder \
    --retrieval_method e5 \
    --model_path /model/e5-base-v2/ \
    --corpus_path indexes/sample_corpus.jsonl \
    --save_dir indexes/ \
    --use_fp16 \
    --max_length 512 \
    --batch_size 256 \
    --pooling_method mean \
    --sentence_transformer \
    --faiss_type Flat
```

--------------------------------

### Initialize Retrievers and Perform Document Search

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Initialize dense or sparse retrievers and execute document retrieval queries with optional reranking. Returns top-k relevant documents for RAG pipeline input. Supports configuration-based retriever instantiation.

```python
from flashrag.utils import get_retriever
from flashrag.config import Config
```

--------------------------------

### Build Sparse Retrieval Index with Pyserini

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/building-index.md

Constructs a sparse retrieval index using BM25 with the `Pyserini` backend. This method is for sparse retrieval and does not require a model path. Key parameters include the retrieval method, corpus path, BM25 backend, and save directory.

```bash
python -m flashrag.retriever.index_builder \
    --retrieval_method bm25 \
    --corpus_path indexes/sample_corpus.jsonl \
    --bm25_backend pyserini \
    --save_dir indexes/
```

--------------------------------

### Load and Manage RAG Pipeline Configuration

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Initialize RAG pipeline configuration from YAML files with dictionary overrides. Demonstrates accessing configuration values for model paths, retrieval methods, metrics, and hyperparameters. Dict overrides take precedence over file-based configuration.

```python
from flashrag.config import Config

# Load configuration from YAML file with dictionary overrides
config_dict = {
    'data_dir': 'dataset/',
    'index_path': 'indexes/e5_Flat.index',
    'corpus_path': 'indexes/general_knowledge.jsonl',
    'model2path': {
        'e5': 'intfloat/e5-base-v2',
        'llama3-8B-instruct': 'meta-llama/Meta-Llama-3-8B-Instruct'
    },
    'generator_model': 'llama3-8B-instruct',
    'retrieval_method': 'e5',
    'metrics': ['em', 'f1', 'acc'],
    'retrieval_topk': 5,
    'save_intermediate_data': True,
    'gpu_id': 0,
    'seed': 2025
}

# Initialize configuration (dict overrides take precedence over file)
config = Config(
    config_file_path='my_config.yaml',
    config_dict=config_dict
)

# Access configuration values
print(config['retrieval_method'])  # 'e5'
print(config.generator_model)      # 'llama3-8B-instruct'
```

--------------------------------

### Build Dense Retrieval Index with Sentence Transformers

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Builds an index for dense retrieval using models compatible with the sentence transformers library. This command is similar to the E5 builder but includes the `--sentence_transformer` flag and omits the explicit `--pooling_method`.

```bash
python -m flashrag.retriever.index_builder \
  --retrieval_method e5 \
  --model_path /model/e5-base-v2/ \
  --corpus_path indexes/sample_corpus.jsonl \
  --save_dir indexes/ \
  --use_fp16 \
  --max_length 512 \
  --batch_size 256 \
  --pooling_method mean \
  --sentence_transformer \
  --faiss_type Flat
```

--------------------------------

### Configure FlashRAG Evaluation Settings

Source: https://github.com/ruc-nlpir/flashrag/blob/main/docs/original_docs/configuration.md

Sets up parameters for model evaluation, including the list of metrics to use (e.g., 'em', 'f1', 'acc'), specific settings for metrics like retrieval recall, and whether to save the metric scores. Supported metrics are detailed in the project's metric script.

```yaml
# Metrics to evaluate the result
metrics: ['em','f1','acc','precision','recall'] 
# Specify setting for metric, will be called within certain metrics
metric_setting: 
  retrieval_recall_topk: 5
save_metric_score: True
```

--------------------------------

### Build Dense Retrieval Index with E5 Model

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Builds an index for dense retrieval using the E5 model. Requires specifying the model path, corpus path, and save directory. Optional parameters include FP16 usage, max length, batch size, pooling method, and FAISS type.

```bash
python -m flashrag.retriever.index_builder \
  --retrieval_method e5 \
  --model_path /model/e5-base-v2/ \
  --corpus_path indexes/sample_corpus.jsonl \
  --save_dir indexes/ \
  --use_fp16 \
  --max_length 512 \
  --batch_size 256 \
  --pooling_method mean \
  --faiss_type Flat
```

--------------------------------

### Load Pre-processed RAG Datasets

Source: https://context7.com/ruc-nlpir/flashrag/llms.txt

Load and access RAG benchmark datasets in JSONL, JSON, or Parquet format. Supports configuring dataset name, splits, sampling options, and iterating over dataset items with questions, answers, and metadata. Useful for train/dev/test dataset preparation.

```python
from flashrag.utils import get_dataset
from flashrag.config import Config

# Configure dataset path and splits
config = Config(config_dict={
    'data_dir': 'dataset/',
    'dataset_name': 'nq',
    'split': ['train', 'dev', 'test'],
    'test_sample_num': 100,
    'random_sample': False
})

# Load all dataset splits
all_splits = get_dataset(config)
train_data = all_splits['train']
test_data = all_splits['test']

# Access dataset attributes
print(f"Dataset size: {len(test_data)}")
print(f"First question: {test_data.question[0]}")
print(f"Golden answers: {test_data.golden_answers[0]}")

# Iterate over dataset items
for item in test_data:
    question = item.question
    answers = item.golden_answers
    metadata = item.metadata
    print(f"Q: {question}\nA: {answers}")
    break
```

--------------------------------

### Build Sparse Retrieval Index with BM25s Backend

Source: https://github.com/ruc-nlpir/flashrag/blob/main/README.md

Builds an index for sparse retrieval using the BM25 algorithm with the 'bm25s' backend. This command requires the corpus path and save directory. The `model_path` is not needed for BM25 retrieval.

```bash
python -m flashrag.retriever.index_builder \
  --retrieval_method bm25 \
  --corpus_path indexes/sample_corpus.jsonl \
  --bm25_backend bm25s \
  --save_dir indexes/
```