OpenRag is a lightweight, modular and extensible Retrieval-Augmented Generation (RAG) framework designed to explore and test advanced RAG techniques — 100% open source and focused on experimentation, not lock-in.
Built by the Linagora, OpenRag offers a sovereign-by-design alternative to mainstream RAG stacks.
- 🦫 OpenRag — The Open RAG Experimentation Playground
- Table of Contents
- 🎯 Goals
- ✨ Key Features
- 🚧 Coming Soon
- 🚀 Installation
- 🔧 Troubleshooting
- 🤝 Support and Contributing
- 📜 License
- Experiment with advanced RAG techniques
- Develop evaluation metrics for RAG applications
- Collaborate with the community to innovate and push the boundaries of RAG applications
OpenRag supports a comprehensive range of file formats for seamless document ingestion:
- Text Files:
txt,md - Document Files:
pdf,docx,doc,pptx- Advanced PDF parsing with OCR support and Office document processing - Audio Files:
wav,mp3,mp4,ogg,flv,wma,aac- Audio transcription and content extraction - Images:
png,jpeg,jpg,svg- Vision Language Model (VLM) powered image captioning and analysis
All files are intelligently converted to Markdown format with images replaced by AI-generated captions, ensuring consistent processing across all document types.
Experience intuitive document management through our built-in web interface.
Indexer UI Features
- Drag-and-drop file upload with batch processing capabilities
- Real-time indexing progress monitoring and status updates
- Admin Dashbord to monitore RAG components (Indexer, VectorDB, TaskStateManager, etc)
- Partition management - organize documents into logical collections
- Visual document preview and metadata inspection
- Search and filtering capabilities for indexed content
Organize your knowledge base with flexible partition management:
- Multi-tenant support - isolate different document collections
Engage with your documents through our sophisticated chat interface:
Chat UI Features
- Chainlit-powered UI - modern, responsive chat experience
- Source transparency - every response includes relevant document references
OpenRag API is tailored to be compatible with the OpenAI format (see the openai-compatibility section for more details), enabling seamless integration of your deployed RAG into popular frontends and workflows such as OpenWebUI, LangChain, N8N, and more. This ensures flexibility and ease of adoption without requiring custom adapters.
Summary of features
- Drop-in replacement for OpenAI API endpoints
- Compatible with popular frontends like OpenWebUI, LangChain, N8N, and more
- Authentication support - secure your API with token-based auth
Scale your RAG pipeline across multiple machines and GPUs.
Distributed Ray Deployment
- Horizontal scaling - distribute processing across worker nodes
- GPU acceleration - optimize inference across available hardware
- Resource management - intelligent allocation of compute resources
- Monitoring dashboard - real-time cluster health and performance metrics
See the section on distributed deployment in a ray cluster for more details
OpenRag Leverages state-of-the-art retrieval techniques for superior accuracy.
Implemented advanced retrieval techniques
- Hybrid search - combines semantic similarity with BM25 keyword matching
- Contextual retrieval - Anthropic's technique for enhanced chunk relevance
- Multilingual reranking - using
Alibaba-NLP/gte-multilingual-reranker-base
For more details, see this file
- 📂 Expanded Format Support: Future updates will introduce compatibility with additional formats such as
csv,odt,html, and other widely used open-source document types. - 🔄 Unified Markdown Conversion: All files will continue to be converted to markdown using a consistent chunker. Format-specific chunkers (e.g., for CSV, HTML) are planned for enhanced processing.
- 🤖 Advanced Features: Upcoming releases will include Tool Calling, Agentic RAG, and MCP to elevate your RAG workflows.
- Enhanced Security: Ensures data encryption both during transit and at rest.
- Python 3.12 or higher recommended
- Docker and Docker Compose
- For GPU capable machines, ensure you have the NVIDIA Container Toolkit installed. Refer to the NVIDIA documentation for installation instructions.
git clone --recurse-submodules [email protected]:linagora/openrag.git
cd openrag
git checkout main # or a given releaseCreate a .env file at the root of the project, mirroring the structure of .env.example, to configure your environment and supply blank environment variables.
cp .env.example .envAll supported file format parsers are pre-configured. For PDF processing, MarkerLoader serves as the default parser, offering comprehensive support for OCR-scanned documents, complex layouts, tables, and embedded images. MarkerLoader operates efficiently on both GPU and CPU environments.
For more PDF options
For CPU-only deployments or lightweight testing scenarios, you can consider switching to PyMuPDF4LLMLoader or PyMuPDFLoader. To change the loader, set the PDFLoader variable like this PDFLoader=PyMuPDF4LLMLoader.
⚠️ Important: These alternative loaders have limitations - they cannot process non-searchable (image-based) PDFs and do not extract or handle embedded images.
Important
In case Indexer UI (A Web interface for intuitive document ingestion, indexing, and management.) is not configured already in your .env, follow this dedicated guide:
➡ Deploy with Indexer UI
You can run the application with either GPU or CPU support, depending on your system:
# Start with GPU (recommended for better performance)
docker compose up --build -d # Use 'down' to stop
# Start with CPU
docker compose --profile cpu up --build -d # Use '--profile cpu down' to stop it properlyWarning
The initial launch is longer due to the installation of required dependencies.
Once the app is up and running, visit http://localhost:APP_PORT or http:X.X.X.X:APP_PORT to access via:
-
/docs– FastAPI’s full API documentation. See this detailed overview of our api for more details on the endpoints. -
/chainlit– Chainlit chat UI to chat with your partitions. To disable it (e.g., for backend-only use), setWITH_CHAINLIT_UI=False.
Note
Chainlit UI has no authentication by default. To enable it, follow the dedicated guide. The same goes for chat data persistancy, enable it with this guide
http://localhost:INDEXERUI_PORTto access the indexer ui for easy document ingestion, indexing, and management
To scale OpenRag in a distributed environment using Ray, follow the dedicated guide: ➡ Deploy OpenRag in a Ray cluster
Troubleshooting
After running uv sync, if you have this error:
error: Distribution `ray==2.43.0 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform
hint: You're using CPython 3.13 (`cp313`), but `ray` (v2.43.0) only has wheels with the following Python ABI tag: `cp312`
This means your uv installation relies on cpython 3.13 while you are using python 3.12.
To solve it, please run:
uv venv --python=3.12
uv syncWhile executing OpenRag, if you encounter a problem that prevents you from downloading the models' weights locally, then you just need to create the needed folder and authorize it to be written and executed
sudo mkdir /app/model_weights
sudo chmod 775 /app/model_weightsWe ❤️ your contributions!
We encourage you to contribute to OpenRag! Here's how you can get involved:
- Fork this repository.
- Create a new branch for your feature or fix.
- Submit a pull request for review.
Feel free to ask questions, suggest features, or report bugs via the GitHub Issues page. Your feedback helps us improve!
OpenRag is licensed under the AGPL-3.0. You are free to use, modify, and distribute this software in compliance with the terms of the license.
For more details, refer to the LICENSE file in the repository.