简体中文  |  English

Latest News 🔥

• [2026.01.23] 🎉 UltraRAG 3.0 Released: Say no to "black box" development—make every line of reasoning logic clearly visible 👉 📖 Blog
• [2026.01.20] 🎉 AgentCPM-Report Model Released! DeepResearch is finally localized: 8B on-device writing agent AgentCPM-Report is open-sourced 👉 🤗 Model

UltraRAG is the first lightweight RAG development framework based on the Model Context Protocol (MCP) architecture design, jointly launched by THUNLP at Tsinghua University, NEUIR at Northeastern University, OpenBMB, and AI9stars.

Designed for research exploration and industrial prototyping, UltraRAG standardizes core RAG components (Retriever, Generation, etc.) as independent MCP Servers, combined with the powerful workflow orchestration capabilities of the MCP Client. Developers can achieve precise orchestration of complex control structures such as conditional branches and loops simply through YAML configuration.

UltraRAG UI transcends the boundaries of traditional chat interfaces, evolving into a visual RAG Integrated Development Environment (IDE) that combines orchestration, debugging, and demonstration.

The system features a powerful built-in Pipeline Builder that supports bidirectional real-time synchronization between "Canvas Construction" and "Code Editing," allowing for granular online adjustments of pipeline parameters and prompts. Furthermore, it introduces an Intelligent AI Assistant to empower the entire development lifecycle, from pipeline structural design to parameter tuning and prompt generation. Once constructed, logic flows can be converted into interactive dialogue systems with a single click. The system seamlessly integrates Knowledge Base Management components, enabling users to build custom knowledge bases for document Q&A. This truly realizes a one-stop closed loop, spanning from underlying logic construction and data governance to final application deployment.

We provide two installation methods: local source code installation (recommended using uv for package management) and Docker container deployment

We strongly recommend using uv to manage Python environments and dependencies, as it can greatly improve installation speed.

Prepare Environment

If you haven't installed uv yet, please execute:

## Direct installation
pip install uv
## Download
curl -LsSf https://astral.sh/uv/install.sh | sh

Download Source Code

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

Install Dependencies

Choose one of the following modes to install dependencies based on your use case:

A: Create a New Environment Use uv sync to automatically create a virtual environment and synchronize dependencies:

• Core dependencies: If you only need to run basic core functions, such as only using UltraRAG UI:

  uv sync

• Full installation: If you want to fully experience UltraRAG's retrieval, generation, corpus processing, and evaluation functions, please run:

  uv sync --all-extras

• On-demand installation: If you only need to run specific modules, keep the corresponding --extra as needed, for example:

  uv sync --extra retriever   # Retrieval module only
  uv sync --extra generation  # Generation module only

Once installed, activate the virtual environment:

# Windows CMD
.venv\Scripts\activate.bat

# Windows Powershell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

B: Install into an Existing Environment To install UltraRAG into your currently active Python environment, use uv pip:

# Core dependencies
uv pip install -e .

# Full installation
uv pip install -e ".[all]"

# On-demand installation
uv pip install -e ".[retriever]"

If you prefer not to configure a local Python environment, you can deploy using Docker.

Get Code and Images

# 1. Clone the repository
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG

# 2. Prepare the image (choose one)
# Option A: Pull from Docker Hub
docker pull hdxin2002/ultrarag:v0.3.0-base-cpu # Base version (CPU)
docker pull hdxin2002/ultrarag:v0.3.0-base-gpu # Base version (GPU)
docker pull hdxin2002/ultrarag:v0.3.0          # Full version (GPU)

# Option B: Build locally
docker build -t ultrarag:v0.3.0 .

# 3. Start container (port 5050 is automatically mapped)
docker run -it --gpus all -p 5050:5050 <docker_image_name>

Start the Container

# Start the container (Port 5050 is mapped by default)
docker run -it --gpus all -p 5050:5050 <docker_image_name>

Note: After the container starts, UltraRAG UI will run automatically. You can directly access http://localhost:5050 in your browser to use it.

After installation, run the following example command to check if the environment is normal:

ultrarag run examples/experiments/sayhello.yaml

If you see the following output, the installation is successful:

Hello, UltraRAG v3!

We provide complete tutorial examples from beginner to advanced. Whether you are conducting academic research or building industrial applications, you can find guidance here. Welcome to visit the Documentation for more details.

Designed for researchers, providing data, experimental workflows, and visualization analysis tools.

• Getting Started: Learn how to quickly run standard RAG experimental workflows based on UltraRAG.
• Evaluation Data: Download the most commonly used public evaluation datasets in the RAG field and large-scale retrieval corpora, directly for research benchmark testing.
• Case Analysis: Provides a visual Case Study interface to deeply track each intermediate output of the workflow, assisting in analysis and error attribution.
• Code Integration: Learn how to directly call UltraRAG components in Python code to achieve more flexible customized development.

Designed for developers and end users, providing complete UI interaction and complex application cases.

• Quick Start: Learn how to start UltraRAG UI and familiarize yourself with various advanced configurations in administrator mode.
• Deployment Guide: Detailed production environment deployment tutorials, covering the setup of Retriever, Generation models (LLM), and Milvus vector database.
• Deep Research: Flagship case, deploy a Deep Research Pipeline. Combined with the AgentCPM-Report model, it can automatically perform multi-step retrieval and integration to generate tens of thousands of words of survey reports.

Thanks to the following contributors for their code submissions and testing. We also welcome new members to join us in collectively building a comprehensive RAG ecosystem!

You can contribute by following the standard process: Fork this repository → Submit Issues → Create Pull Requests (PRs).

If you find this repository helpful for your research, please consider giving us a ⭐ to show your support.

• For technical issues and feature requests, please use GitHub Issues.
• For questions about usage, feedback, or any discussions related to RAG technologies, you are welcome to join our WeChat group, Feishu group, and Discord to exchange ideas with us.
• If you have any questions, feedback, or would like to get in touch, please feel free to reach out to us via email at yanyk.thu@gmail.com

WeChat Group

Feishu Group

📖 Publications Papers Shi Yu, Chaoyue Tang, Bokai Xu, Junbo Cui, Junhao Ran, Yukun Yan, Zhenghao Liu, Shuo Wang, Xu Han, Zhiyuan Liu, Maosong Sun. (2025) VisRAG: Vision-based Retrieval-augmented Generation on Multi-modality Documents. arXiv:2410.10594 and In Proceedings of the Thirteenth International Conference on Learning Representations (ICLR 2025). Xinze Li, Sen Mei, Zhenghao Liu, Yukun Yan, Shuo Wang, Shi Yu, Zheni Zeng, Hao Chen, Ge Yu, Zhiyuan Liu, Maosong Sun, Chenyan Xiong. (2025) RAG-DDR: Optimizing Retrieval-Augmented Generation Using Differentiable Data Rewards. arXiv:2410.13509 and In Proceedings of the Thirteenth International Conference on Learning Representations (ICLR 2025). Kunlun Zhu, Yifan Luo, Dingling Xu, Yukun Yan, Zhenghao Liu, Shi Yu, Ruobing Wang, Shuo Wang, Yishan Li, Nan Zhang, Xu Han, Zhiyuan Liu, Maosong Sun. (2025) RAGEval: Scenario Specific RAG Evaluation Dataset Generation Framework. arXiv:2408.01262 and In Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (ACL 2025). Ruobing Wang, Qingfei Zhao, Yukun Yan, Daren Zha, Yuxuan Chen, Shi Yu, Zhenghao Liu, Yixuan Wang, Shuo Wang, Xu Han, Zhiyuan Liu, Maosong Sun. (2025) DeepNote: Note-Centric Deep Retrieval-Augmented Generation. arXiv:2410.08821 and In Findings of the Association for Computational Linguistics: EMNLP 2025. Models Yishan Li, Wentong Chen, Yukun Yan, Mingwei Li, Sen Mei, Xiaorong Wang, Kunpeng Liu, Xin Cong, Shuo Wang, Zhong Zhang, Yaxi Lu, Zhenghao Liu, Yankai Lin, Zhiyuan Liu, Maosong Sun. (2026) AgentCPM-Report: Interleaving Drafting and Deepening for Open-Ended Deep Research. arXiv:2602.06540. OpenBMB. MiniCPM-Embedding-Light. Hugging Face Model Card. Release History Version Changes Urgency Date v0.3.0.2 Release date: 2026.4.9 ## Highlights This release delivers a major end-to-end memory upgrade for UltraRAG, introducing persistent user memory, project memory retrieval, and a dedicated memory-aware RAG demo. It also makes the demo experience significantly more stateful and personalized with SQLite-backed authentication, persistent chat sessions, nickname and model settings management, and knowledge base visibility controls supporting public, private, and shared access. The frontend is s High 4/9/2026 v0.3.0.1 Release date: 2026.3.10 ## Highlights This release introduces expanded document parsing for `.doc `and `.wps` formats, alongside new web search capabilities for the demo environment. We have significantly enhanced the chat experience by adding `DOCX` and `markdown` export functionality, downloadable text actions, and a streamlined flow for session creation and interruption handling. The citation system has been further optimized with automatic renumbering and improved source sorting for be Medium 3/10/2026 v0.3.0 Release date: 2026.1.23 ## Highlights Introducing UltraRAG 3.0: Reject "Black Box" Development. Make Every Line of Inference Logic Visible! UltraRAG 3.0 solves the "Last Mile" problem in RAG development, developed by THUNLP, NEUIR, OpenBMB & AI9Stars. This release represents a significant milestone with **129 pull requests** merged, bringing major enhancements to functionality, UI/UX, and system stability. * WYSIWYG Pipeline Builder: From logic to prototype in seconds. Our dual-mode bui Low 1/26/2026 v0.2.1.3 Release date: 2026.1.12 ## Highlights This release focuses on improving system stability and core logic. We have addressed a path indexing bug in the generation server to ensure reliable image rendering. Additionally, the search-o1 pipeline has been completely reimplemented, resolving previous implementation flaws. ## What's Changed 1. Fixed index reference for image paths in generation server. by @xhd0728 #146 2. Reimplemented the search-o1 pipeline by @mssssss123 @lifelsl #158 Low 1/12/2026 v0.2.1.2 Release date: 2025.11.25 ## Highlights This release introduces a refreshed UltraRAG front-end UI, fixes several logical issues, and adds new ToolCall and PipelineCall capabilities for directly invoking UltraRAG tools or pipelines from your own code. The retriever server has been further optimized to support full deployment without repeated corpus/index initialization, significantly improving experimental efficiency. We also refine the GPU/CPU configuration logic for more stable and flexibl Low 11/25/2025 v0.2.1.1 Release date: 2025.11.13 ## Highlights This release improves the stability and flexibility of UltraRAG. Retriever and index are now fully decoupled, with added support for Milvus and Faiss. The VisRAG 2.0 pipeline is newly supported, and compatibility with chonkie 1.4.0+ has been updated. Several pipelines, including Search-o1 and WebNote, have been fixed. User experience is improved through progress-bar support during document parsing, a script for saving retrieval results, and zoom-in s Low 11/13/2025 v0.2.1 **Release date:** 2025.10.22 ## Highlights 1. Comprehensive Multimodal Upgrade: Both the Retriever and Generation Servers now support multimodal inputs, enabling a complete end-to-end multimodal workflow from retrieval to generation. 2. Corpus Parsing and Chunking Redesign: The Corpus Server adds multi-format file parsing with deep MinerU integration, supporting token-level, sentence-level, and customizable chunking strategies to flexibly adapt to diverse corpus structures. 3. Unified Low 10/22/2025 v0.2.0 **Release date:** 2025.08.28 ## Highlights UltraRAG 2.0 introduces a complete redesign of the system architecture, fully adopting the MCP-based modular structure. This release significantly improves flexibility, extensibility, and developer experience, enabling researchers and engineers to rapidly build, customize, and reproduce complex RAG pipelines with minimal overhead. The core of UltraRAG 2.0 is the new MCP Server–Client workflow, providing a clean separation between functional c Low 10/21/2025 Dependencies & License Audit Loading dependencies... Similar Packages solon-aiJava AI application development framework (supports LLM-tool,skill; RAG; MCP; Agent-ReAct,Team-Agent). Compatible with java8 ~ java25. It can also be embedded in SpringBoot, jFinal, Vert.x, Quarkus, av3.10.6 synaptic-memoryBrain-inspired knowledge graph: spreading activation, Hebbian learning, memory consolidation.v0.16.0 mcp-rag-agent🔍 Build a production-ready RAG system that combines LangGraph and MCP integration for precise, context-aware AI-driven question answering.main@2026-06-06 claude-code-proxyMonitor and visualize your Claude Code API interactions with Claude Code Proxy. Easily set up a transparent proxy and live dashboard. 🛠️🚀main@2026-06-06 AstrBotAgentic IM Chatbot infrastructure that integrates lots of IM platforms, LLMs, plugins and AI feature, and can be your openclaw alternative. ✨v4.25.3 More in MCP Servers AstrBotAgentic IM Chatbot infrastructure that integrates lots of IM platforms, LLMs, plugins and AI feature, and can be your openclaw alternative. ✨ agentscopeBuild and run agents you can see, understand and trust. claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins. langchain4jLangChain4j is an open-source Java library that simplifies the integration of LLMs into Java applications through a unified API, providing access to popular LLMs and vector databases. It makes impleme