{"id":14959597,"url":"https://github.com/renumics/renumics-rag","last_synced_at":"2025-04-04T09:09:52.626Z","repository":{"id":220560318,"uuid":"747372577","full_name":"Renumics/renumics-rag","owner":"Renumics","description":"Visualization for a Retrieval-Augmented Generation (RAG) Assistant  🤖❤️📚","archived":false,"fork":false,"pushed_at":"2024-12-17T08:58:18.000Z","size":18169,"stargazers_count":185,"open_issues_count":2,"forks_count":43,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-04T09:09:36.422Z","etag":null,"topics":["huggingface","langchain","large-language-models","llm","machine-learning","openai","rag","retrieval-augmented","retrieval-augmented-generation","streamlit","umap","visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Renumics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-23T19:53:11.000Z","updated_at":"2025-03-02T17:43:52.000Z","dependencies_parsed_at":"2024-02-27T12:31:12.751Z","dependency_job_id":"c53ba22d-aaf8-43ae-bef6-997521653217","html_url":"https://github.com/Renumics/renumics-rag","commit_stats":{"total_commits":111,"total_committers":4,"mean_commits":27.75,"dds":"0.15315315315315314","last_synced_commit":"39369ac75ace0d01d43d860a609066654772f59d"},"previous_names":["renumics/rag-demo","renumics/renumics-rag"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Renumics%2Frenumics-rag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Renumics%2Frenumics-rag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Renumics%2Frenumics-rag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Renumics%2Frenumics-rag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Renumics","download_url":"https://codeload.github.com/Renumics/renumics-rag/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149505,"owners_count":20891954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["huggingface","langchain","large-language-models","llm","machine-learning","openai","rag","retrieval-augmented","retrieval-augmented-generation","streamlit","umap","visualization"],"created_at":"2024-09-24T13:20:11.483Z","updated_at":"2025-04-04T09:09:52.608Z","avatar_url":"https://github.com/Renumics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Renumics RAG: Explore and Visualize RAG Data\n\nRetrieval-augmented generation assistant demo using [LangChain](https://github.com/langchain-ai/langchain) and [Streamlit](https://github.com/streamlit/streamlit).\n\n## 🛠️ Installation\n\nSetup a virtual environment in the project directory:\n\n```shell\npython3.8 -m venv .venv\nsource .venv/bin/activate  # Linux/MacOS\n# .\\.venv\\Scripts\\activate.bat  # Windows CMD\n# .\\.venv\\Scripts\\activate.ps1  # PowerShell\npip install -IU pip setuptools wheel\n```\n\nInstall the RAG demo package and some extra dependencies:\n\n```shell\n# For GPU support\npip install renumics-rag[all]@git+https://github.com/Renumics/renumics-rag.git torch torchvision sentence-transformers accelerate\n# For CPU support\n# pip install renumics-rag[all]@git+https://github.com/Renumics/renumics-rag.git torch torchvision sentence-transformers accelerate --extra-index-url https://download.pytorch.org/whl/cpu\n```\n\n## ⚒️ Local Setup\n\nIf you intend to edit, not simply use, this project, clone the entire repository:\n\n```shell\ngit clone git@github.com:Renumics/renumics-rag.git\n```\n\nThen install it in editable mode.\n\n### Via `pip`\n\nSetup virtual environment in the project folder:\n\n```shell\npython3.8 -m venv .venv\nsource .venv/bin/activate  # Linux/MacOS\n# .\\.venv\\Scripts\\activate.bat  # Windows CMD\n# .\\.venv\\Scripts\\activate.ps1  # PowerShell\npip install -IU pip setuptools wheel\n```\n\nInstall the RAG demo package and some extra dependencies:\n\n```shell\npip install -e .[all]\n# For GPU support\npip install pandas torch torchvision sentence-transformers accelerate\n# For CPU support\n# pip install pandas torch torchvision sentence-transformers accelerate --extra-index-url https://download.pytorch.org/whl/cpu\n```\n\n### Via `poetry`\n\nInstall the RAG demo and some extra dependencies:\n\n```shell\npoetry install --all-extras\n# Torch with GPU support\npip install pandas torch torchvision sentence-transformers accelerate\n# Torch with CPU support\n# pip install pandas torch torchvision sentence-transformers accelerate --extra-index-url https://download.pytorch.org/whl/cpu\n```\n\nActivate the environment (otherwise, prexis all subsequent commands with `poetry run`):\n\n```shell\npoetry shell\n```\n\n\u003e Note: If you have [Direnv](https://direnv.net/) installed, you can avoid prefixing python commands with `poetry run` by executing `direnv allow` in the project directory. It will activate environment each time you enter the project directory.\n\n### ⚙️ Configuration\n\nIf you plan to use OpenAI models, create a `.env` file with the following content:\n\n```bash\nOPENAI_API_KEY=\"Your OpenAI API key\"\n```\n\nIf you plan to use OpenAI models via Azure, create `.env` with the following content:\n\n```shell\nOPENAI_API_TYPE=\"azure\"\nOPENAI_API_VERSION=\"2023-08-01-preview\"\nAZURE_OPENAI_API_KEY=\"Your Azure OpenAI API key\"\nAZURE_OPENAI_ENDPOINT=\"Your Azure OpenAI endpoint\"\n```\n\nIf you are using Hugging Face models, a .env file is not necessary. You can configure the embeddings model, retriever and the LLM in the config file (settings.yaml). The default settings (taken from [settings file](./settings.yaml) are:\n\n```shell\nllm_type: 'openai'       # 'openai', 'hf' or 'azure'\nllm_name: 'gpt-3.5-turbo'\n\nrelevance_score_fn: 'l2'\nk: 20\nsearch_type: 'similarity'\nscore_threshold: 0.5\nfetch_k: 20\nlambda_mult: 0.5\n\nembeddings_model_type: 'openai'     # 'openai', 'hf' or 'azure'\nembeddings_model_name: 'text-embedding-ada-002'\n```\n\nYou can adapt it without cloning the repository by setting up an environment variable `RAG_SETTINGS` pointing to your local config file. You can also configure it from the GUI during the question and answering sessions. But it's important to choose the desired embeddings model because the indexing is done beforehand.\n\n## 🚀 Usage: Indexing\n\nYou can skip this section [download the demo database with embeddings of a Formula One Dataset](https://spotlightpublic.blob.core.windows.net/docs-data/rag_demo/docs-db.zip). This dataset is based on articles from Wikipedia and is licensed under the Creative Commons Attribution-ShareAlike License. The original articles and a list of authors can be found on the respective Wikipedia pages.\nTo use your own data create a new data/docs directory within the project and place your documents in there (recursive directories are supported).\n\n\u003e Note: at the moment, only HTML files can be indexed but it can be adjusted in the [create-db](assistant/cli/create_db.py) script, this requires the [⚒️ Local Setup](#⚒️-local-setup)\n\nBegin the process by indexing your documents. Execute the following command:\n\n```shell\ncreate-db\n```\n\nThis will create a `db-docs` directory within the project consisting of indexed documents. To index additional documents, use the `--exist-ok` and `--on-match` flags (refer to `create-db --help` for more information).\n\n## 🚀 Usage: Questioning\n\nNow, you can leverage the indexed documents to answer questions.\n\nTo only retrieve relevant documents via command line interface:\n\n```shell\nretrieve \"Your question here\"\n# QUESTION: ...\n# SOURCES: ...\n```\n\nTo answer a question based on the indexed documents:\n\n```shell\nanswer \"Your question here\"\n# QUESTION: ...\n# ANSWER: ...\n# SOURCES: ...\n```\n\nTo start a web application (See `app --help` for available application options):\n\n```shell\napp\n```\n\nThis will open a new browser window:\n![RAG-demo-gui](assets/img/RAG-demo-gui.png)\n\nYou can enter your questions to get them answered by the RAG System. Each answer contains an expandable 'Sources' section that includes the text and filename for each snippet used to generate the answer. \nThe Settings section on the left allows you to choose different LLMs from OpenAI or Hugging Face. In the advanced settings, you can adjust the retrieval settings like the choice of relevance score function, the number of retrieved snippets, and search type. You can also change the embeddings model. \nNote: Changing the embeddings model requires creating a new database with the new embeddings.\n\n## 🔎 Interactive exploration\n\nAfter submitting some questions, you can explore them using [Renumics Spotlight](https://github.com/Renumics/spotlight) by clicking the red explore button on the left:\n![RAG-Demo-Explore](assets/img/RAG-Demo-Explore.png)\n\nIt will open a new browser tab:\n![RAG-Demo-Spotlight](assets/img/RAG-Demo-Spotlight.png)\n\nYou can see a table of all questions and all document snippets on the top left side. Using the 'visible columns' button, you can control which columns are shown in the table.\n\nOn the right side is the similarity map; it shows the questions and documents based on the embeddings. You can customize it by clicking the settings button and apply coloring by 'used_by_num_question' to color the snippets by the number of questions where the retriever loaded this snippet.\n\nYou can select snippets in the similarity map or in the table to display them in the details view at the bottom. To customize the detail view, you can remove rows by clicking the 'x' and add views with the 'Add View' button. A good setup here is to display the document, used_by_num_question and type.\n\n![Rag_demo_Spotlight-adjusted](assets/img/Rag_demo_Spotlight-adjusted.png)\n\nExploring the exemplary F1 Dataset and over 500 questions from our [RAG evaluation article](https://towardsdatascience.com/visualize-your-rag-data-evaluate-your-retrieval-augmented-generation-system-with-ragas-fc2486308557) can reveal interesting clusters. Document clusters of race statistics, racing techniques and strategies, and team details are frequently referenced by at least one question. Others, like Television Rights or specific race track details, are retrieved less often.\n\n## 🔎 Tutorials and References\n\nTo learn more about visulization for RAG, check out our articles:\n\n- [ITNext: Visualize your RAG Data - EDA for Retrieval-Augmented Generation](https://itnext.io/visualize-your-rag-data-eda-for-retrieval-augmented-generation-0701ee98768f): visualization of single questions, answers, and related documents shows large potential for RAG. Dimensionality reduction techniques can make the embedding space accessible for users and developers\n  ![UMAP dimensionality reduction of the embeddings of document snippets, colored by to their relevance to the question “Who built the Nürburgring?”](assets/img/rag1_ani.gif)\n\n- [Towards Data Science: Visualize your RAG Data - Evaluate your Retrieval-Augmented Generation System with Ragas](https://towardsdatascience.com/visualize-your-rag-data-evaluate-your-retrieval-augmented-generation-system-with-ragas-fc2486308557): Utilizing UMAP-based visualization offers an interesting approach to delve deeper than just analyzing global metrics for evaluations in RAG.\n  ![Animation of the iterations of a UMAP [3] dimensionality reduction for Wikipedia Formula One articles in the embedding space with manually labeled clusters](assets/img/rag2_ani.gif)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenumics%2Frenumics-rag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frenumics%2Frenumics-rag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenumics%2Frenumics-rag/lists"}