UltraRAG Documentation

UltraRAG is a lightweight RAG (Retrieval-Augmented Generation) development framework based on the Model Context Protocol (MCP) architecture.

Core Concepts

• MCP Servers: Standardized core RAG components (Retriever, Generation, etc.) act as independent servers.
• MCP Client: Orchestrates workflows using the components.
• Low-Code Orchestration: Complex control structures like sequential execution, loops, and conditional branches are implemented via YAML configuration files.

Key Capabilities

• Modular Extension: New features can be registered as function-level Tools to integrate into workflows.
• UltraRAG UI: A visual RAG IDE featuring a Pipeline Builder for bidirectional synchronization between canvas construction and code editing, and an Intelligent AI Assistant for parameter tuning.
• Rapid Prototyping: Pipeline logic can be converted into interactive conversational Web UIs with a single command.
• Unified Evaluation: Built-in standardized evaluation workflows and mainstream research benchmarks.

UltraRAG provides specialized workflows for two primary user groups:

For Researchers

• Standard RAG Workflows: Quickly run experimental workflows.
• Evaluation Datasets: Access public evaluation datasets and large-scale retrieval corpora for benchmark testing.
• Case Analysis: Use the visual Case Study interface to track intermediate outputs and perform error attribution.
• Structured Debugging: Troubleshoot across four layers: input & retrieval, reasoning & planning, state & context, and deployment & runtime.
• Code Integration: Call UltraRAG components directly in Python for customized development.

For Developers and End Users

• UltraRAG UI: Start the UI and configure advanced settings in administrator mode.
• Production Deployment: Set up Retriever, Generation models (LLM), and Milvus vector databases.
• Deep Research Pipeline: Deploy a flagship case using the AgentCPM-Report model to automate multi-step retrieval and generate long-form survey reports.

When encountering issues like suspicious answers, drifting multi-step workflows, or inconsistent deployment results, use the structured four-layer troubleshooting method to isolate the root cause before applying fixes.

Troubleshooting Principles

1. Locate the layer before modifying implementation: Identify if the issue is in Input/Retrieval, Reasoning/Planning, State/Context, or Deployment/Runtime. Only modify the suspected layer.
2. Prioritize intermediate outputs: Do not just look at the final answer. Check if the user input was parsed correctly, if the query was rewritten accurately, if retrieved chunks support the question, and if intermediate states were lost.
3. Apply minimal fixes: Change only one parameter or prompt at a time to confirm exactly what fixed the issue.
4. Treat "model issues" as "workflow issues" first: Many errors are caused by retrieval, prompt construction, state inheritance, or deployment configuration rather than the model's inherent capability.

The recommended way to install UltraRAG is using uv for Python environment and dependency management.

1. Prepare Environment

Install uv first:

pip install uv
# OR
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Download Source

git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG

3. Install Dependencies

Choose one of the following modes:

Option A: Create a new environment (using uv sync)

• Core dependencies only (e.g., for UltraRAG UI):

  uv sync

• Full installation (Retrieval, Generation, Corpus processing, and Evaluation):

  uv sync --all-extras

• On-demand installation (specific modules):

  uv sync --extra retriever   # retriever module
  uv sync --extra generation  # generation module

After installation, activate the virtual environment:

• Windows CMD: .venv\Scripts\activate.bat
• Windows Powershell: .venv\Scripts\Activate.ps1
• macOS / Linux: source .venv/bin/activate

Option B: Install into an existing environment (using uv pip)

• Core: uv pip install -e .
• Full: uv pip install -e ".[all]"
• On-demand: uv pip install -e ".[retriever]"

# Example: Full installation with uv sync
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG
uv sync --all-extras
source .venv/bin/activate

When applying mobile-only optimizations to the UltraRAG frontend, use this baseline to ensure that desktop UX remains unchanged. This baseline covers the /chat route and specific UI components.

Scope of Testing

• Route: /chat
• Main Page: ui/frontend/src/pages/ChatPage.tsx
• Desktop Layout Styles: ui/frontend/public/theme/style.css
• Dialog and Shared UI Styles: ui/frontend/src/app/styles/globals.css

Desktop Regression Checklist

Ensure the following behaviors remain intact after mobile optimizations:

• Sidebar: Collapse/expand functionality and session list interactions (open, rename, delete).
• Header: Pipeline selector layout/dropdown and Status badge (Ready / Loading / Failed) positioning.
• Chat Area: Message list spacing, scroll behavior, input container layout, send/stop button positions, and KB selector behavior.
• Menus & Dialogs: Settings dropdown, language submenu, Auth dialog, and Account settings dialog (dimensions and scrolling).
• Detail Panel: Reference detail sidebar open/close behavior.
• Chat Flow: Citation click and detail panel interaction.