Install and Get Started: RAG and Context Engineering
===============================

To install RapidFire AI for RAG and context engineering on your local machine or remote/cloud instance, follow the steps below.

Note that if you only plan to use OpenAI APIs and not self-hosted models, you do not need GPUs on your machine. But you must 
provide a valid OpenAI API key via a config argument as shown in the tutorial notebooks.


.. note::
  An example notebook for RapidFire AI RAG fully on Google Colab is coming soon. Watch this space for updates.


Step 1: Install dependencies and package
-----------------------

Obtain the RapidFire AI OSS package from pypi (includes all dependencies) and ensure it is installed correctly.

.. important::

  Requires Python 3.12+. Ensure that ``python3`` resolves to Python 3.12 before creating the venv.

.. code-block:: bash

   python3 --version  # must be 3.12.x
   python3 -m venv .venv
   source .venv/bin/activate

   pip install rapidfireai

   rapidfireai --version
   # Verify it prints the following:
   # RapidFire AI 0.12.3

   # Due to current issue: https://github.com/huggingface/xet-core/issues/527
   pip uninstall -y hf-xet


The tutorial notebooks for RAG evals do not use any gated models from Hugging Face.
If you want to access gated models, provide your Hugging Face account token.
For more details on that, :doc:`see Step 1 here</walkthroughft>`.


Step 2: Initialize RapidFire AI
------------

Run the following command to initialize rapidfireai to use the correct dependencies for RAG evals:

.. code-block:: bash

   rapidfireai init --evals
   # It will install specific dependencies and initialize rapidfireai for RAG evals

.. note::
  You need to run init *only once* for a new venv or when switching GPU(s) on your machine. You do NOT need to run it after a reboot or for a new terminal tab.



Step 3: Open the tutorial notebooks
------------

After completing Step 2, open one of the tutorial notebooks via Jupyter (explained further here: :doc:`Example Use Case Tutorials</tutorials>`), say the the FiQA RAG Q&A chabtot use case. 
You can see the files under the "tutorial_notebooks" folder in the directory where you initialized rapidfireai.

* FiQA: RAG for Financial Opinion Q&A Chatbot: `View on GitHub <https://github.com/RapidFireAI/rapidfireai/blob/main/tutorial_notebooks/evals/rf-tutorial-rag-fiqa.ipynb>`__

* GSM8K: Context Engineering for Math Reasoning: `View on GitHub <https://github.com/RapidFireAI/rapidfireai/blob/main/tutorial_notebooks/evals/rf-tutorial-gsm8k-fewshot.ipynb>`__

* SciFact: RAG for Scientific Claim Verification: `View on GitHub <https://github.com/RapidFireAI/rapidfireai/blob/main/tutorial_notebooks/evals/rf-tutorial-scifact-full-evaluation.ipynb>`__




Quickstart Video (3.5min)
^^^^^^^^^^^^^^^

.. raw:: html

    <div style="position: relative; width: 100%; height: 0; padding-bottom: 45%;">
        <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" 
                src="https://www.youtube.com/embed/Md7zw8wqaIU?si=-CUs4pH5hIXz65ri" 
                title="RapidFire AI RAG: Quickstart" 
                frameborder="0" 
                allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
                referrerpolicy="strict-origin-when-cross-origin" 
                allowfullscreen>
        </iframe>
    </div>

|

Full Usage Walkthrough Video (13.5min)
^^^^^^^^^^^^^^^

.. raw:: html

    <div style="position: relative; width: 100%; height: 0; padding-bottom: 45%;">
        <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" 
                src="https://www.youtube.com/embed/hOJ6C_HGHew?si=EGfFYzK64hwCLfhR" 
                title="RapidFire AI RAG: Usage Walkthrough" 
                frameborder="0" 
                allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
                referrerpolicy="strict-origin-when-cross-origin" 
                allowfullscreen>
        </iframe>
    </div>

|


Step 4: Run the notebook cells
-------

Run the cells *one by one* as shown in the above videos. Wait for a cell to finish before running the next.

* Imports

* Load datasets 

* Create named RF experiment 

* Define RF RAG spec that wraps LangChain classes

* Define data preprocessing and post processing functions

* Define eval metrics functions per batch and for accumulation

* Define RF generator spec that wraps vLLM or OpenAI classes

* Define rest of multi-config knob dictionary and generate config group

* Launch multi-config evals; adjust :code:`num_shards` as per desired concurrency (see `Run Evals <experiment.html#run-evals>`__ for details)



Step 5: Monitor online aggregation of eval metrics on in-notebook table
--------

.. raw:: html

    <img src="_static/evals-table.png" alt="Monitor runs table and online aggregation of eval metrics" 
         style="cursor: zoom-in; max-width: 100%;" onclick="this.requestFullscreen()">

    <img src="_static/evals-online.png" alt="Monitor runs table and online aggregation of eval metrics" 
         style="cursor: zoom-in; max-width: 100%;" onclick="this.requestFullscreen()">



Step 6: Interactive Control (IC) Ops: Stop, Clone-Modify; check their results 
-----

.. raw:: html

    <img src="_static/evals-icop-stop.png" alt="IC Op: Stop" 
         style="cursor: zoom-in; max-width: 100%;" onclick="this.requestFullscreen()">


.. raw:: html

    <img src="_static/evals-icop-clone.png" alt="IC Op: Clone-Modify" 
         style="cursor: zoom-in; max-width: 100%;" onclick="this.requestFullscreen()">


.. raw:: html

    <img src="_static/evals-icop-results.png" alt="IC Op results on table" 
         style="cursor: zoom-in; max-width: 100%;" onclick="this.requestFullscreen()">



Step 7: Inspect results, end experiment, and check logs.
------

Run the cell to print some entries of the evals results. End the expeirment after you are done with it.


You can then move on to another (named) experiment in the same session. 
Run as many experiments as you like; each will have its metrics apppear on its own table under the :func:`run_evals()` cell. 
All experiment artifacts (metrics files, logs, checkpoints, etc.) are *persistent* on 
your machine in the experiments path specified in the constructor.

When you are done overall, just close the notebook. RapidFire AI for evals does not maintain any running server processes.


Step 8: Venture Beyond!
-----

After trying out the tutorial notebooks, explore the rest of this docs website, 
especially the API pages for RAG and context engineering. 
Play around more with IC Ops and/or run more experiments as you wish, including 
changing the prompt schemes, generator models and its knobs, chunking / reranking / retrieval knobs, 
and eval metrics definitions.

You are now up to speed! Enjoy the power of rapid AI customization with RapidFire AI!