OpenViSTAI · Agents · Blockchain · Crypto
Submit a project
Menu
RAG & Knowledge Systems

Universalrag

UniversalRAG is an open-source Python framework for retrieval-augmented generation across corpora with different modalities and granularities. Its modality-aware router selects a suitable corpus for each query and supports both trained routers and a training-free option, alongside scripts for dataset preparation, embedding preprocessing and evaluation.

Explore the practical guide ↓

Independent OpenViST project profile, based on linked sources.

Universalrag — OpenViST project profile in RAG & Knowledge Systems.
OpenViST project illustration. See the linked sources for product details.
Understand the project

Practical overview

When it fits

Use it when a RAG workflow needs to select among corpora that differ in modality or granularity, or when you need a documented pipeline for experimenting with query routers and evaluating results.

Who it is for

  • Developers building retrieval-augmented knowledge assistants over multimodal corpora.
  • Researchers comparing trained and training-free query-routing approaches.
  • Teams exploring retrieval across corpora indexed at different levels of granularity.

Documented uses

  • Route a query to a suitable modality-specific corpus.
  • Prepare datasets and extract embeddings for queries and corpora.
  • Train a supported routing model or use the listed training-free router.
  • Evaluate routed queries against a target dataset.
Before you choose

Requirements & limits

The repository is public and licensed under Apache-2.0. The README specifies Python 3.12 or later and recommends uv for dependency setup.

  • The documented workflow downloads and preprocesses large datasets.
  • Embedding preprocessing has a CUDA_DEVICES setting that should match available GPUs.
  • T5Gemma 2 requires Transformers v5 or later.
  • The README lists GPT-5 as a training-free router but does not specify external access or credential requirements.

Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.

Source-based practical guide

Set up the UniversalRAG environment and prepare datasets

Install the repository dependencies and run its documented dataset download and preprocessing stages.

Before you start

  • Python 3.12 or later.
  • The repository recommends uv; dependencies are specified in pyproject.toml and pinned in uv.lock.
  • Dataset download and preprocessing may take a while because the datasets are large.

Steps

  1. Clone https://github.com/wgcyeo/UniversalRAG and change into the repository directory.

  2. Run the command below, then activate the environment with source .venv/bin/activate.

    Documented command
    uv sync

  3. Run the command below to download and preprocess datasets.

    Documented command
    bash script/0_dataset.sh

  4. Run the command below to extract embeddings; set CUDA_DEVICES to match the GPUs available on your system.

    Documented command
    bash script/1_preprocess.sh

Expected outcome

The documented environment and dataset/embedding preparation stages are completed.

Guide limitations

  • The dataset stage may take a while due to large downloads and preprocessing.
  • The README asks users to match CUDA_DEVICES to available GPUs; it does not specify a universal hardware configuration.
Documentation 1 ↗
Source-based practical guide

Run the documented routing and evaluation stages

Use a listed router for query routing and pass its results into the repository's evaluation script.

Before you start

  • A prepared environment and embeddings from the repository workflow.
  • For training-based routing, select qwen3-vl-2b, internvl3_5-1b or t5gemma-270m.
  • For T5Gemma 2, install Transformers v5 or later.
  • Evaluation requires a model path or identifier, router model name and target dataset.

Steps

  1. For a training-based router, run the command below with one of the listed supported names.

    Documented command
    bash script/2_train.sh {model-name}

  2. Route queries with the command below; the documented options include the training-based routers and training-free gpt-5.

    Documented command
    bash script/3_route.sh {model-name}

  3. Run the command below, substituting the values for the selected model, router and dataset.

    Documented command
    bash script/4_eval.sh --model-path {model-path} --router-model {router-model} --target {target}

Expected outcome

The documented routing stage is followed by generation of evaluation results for the selected target.

Guide limitations

  • The README does not specify external access or credential requirements for GPT-5.
  • The evaluation example uses Qwen/Qwen3-VL-8B-Instruct and the mmlu target; other choices depend on the supplied model and dataset.
Documentation 1 ↗
COMPARE OPTIONS

Compare options for Retrieval-augmented applications

These projects document a common task and share a project role. This is a source-based comparison, not an execution benchmark or a guarantee of interchangeability.

ProjectDocumented purposePlatformAccess and requirements
UniversalragRoute a query to a suitable modality-specific corpus.CLI, Linux, Self-hostedThe repository is public and licensed under Apache-2.0. The README specifies Python 3.12 or later and recommends uv for dependency setup.
LangsearchCrawl website or local data for a knowledge base.CLI, Self-hosted, Server
Hybrid Search RagCombine document retrieval and language-model generation in a configurable workflow.
Evidence and transparency

Sources & review

Official repository ↗
Source record details
Source availability
Active
Sources checked
14 October 2026
Original website title
wgcyeo/UniversalRAG · Official homepage title · retained in its source language
How we review sourcesSuggest a correction