Walkthrough
A detailed step-by-step cookbook of the core features provided by R2R.
This guide shows how to use R2R to:
- Ingest files into R2R
- Search over ingested files
- Use your data as input to RAG (Retrieval-Augmented Generation)
- Extract entities and relationships from your data to create a graph.
- Perform basic user auth
- Observe and analyze an R2R deployment
Be sure to complete the installation instructions before continuing with this guide.
Introduction
R2R is an engine for building user-facing Retrieval-Augmented Generation (RAG) applications. At its core, R2R provides this service through an architecture of providers, services, and an integrated RESTful API. This cookbook provides a detailed walkthrough of how to interact with R2R. Refer here for a deeper dive on the R2R system architecture.
R2R Application Lifecycle
The following diagram illustrates how R2R assembles a user-facing application:
Hello R2R
R2R gives developers configurable vector search and RAG right out of the box, as well as direct method calls instead of the client-server architecture seen throughout the docs:
Configuring R2R
R2R is highly configurable. To customize your R2R deployment:
- Create a local configuration file named
r2r.toml
. - In this file, override default settings as needed.
For example:
Then, use the config-path
argument to specify your custom configuration when launching R2R:
You can read more about configuration here.
Document Ingestion and Management
R2R efficiently handles diverse document types using Postgres with pgvector, combining relational data management with vector search capabilities. This approach enables seamless ingestion, storage, and retrieval of multimodal data, while supporting flexible document management and user permissions.
Key features include:
- Unique
Document
, with correspondingid
, created for each ingested file or context, which contains the downstreamChunks
andEntities
&Relationships
. User
andCollection
objects for comprehensive document permissions.Knowledge Graph
, construction and maintenance.- Flexible document deletion and update mechanisms at global document and chunk levels.
For more advanced document management techniques and user authentication details, refer to the user auth cookbook.
AI Powered Search
R2R offers powerful and highly configurable search capabilities, including vector search, hybrid search, and knowledge graph-enhanced search. These features allow for more accurate and contextually relevant information retrieval.
Vector Search
Vector search parameters inside of R2R can be fine-tuned at runtime for optimal results. Here’s how to perform a basic vector search:
CLI
Python
JavaScript
Curl
Key configurable parameters for vector search can be inferred from the retrieval API reference.
Hybrid Search
R2R supports hybrid search, which combines traditional keyword-based search with vector search for improved results. Here’s how to perform a hybrid search:
CLI
Python
JavaScript
Curl
Retrieval-Augmented Generation (RAG)
R2R is built around a comprehensive Retrieval-Augmented Generation (RAG) engine, allowing you to generate contextually relevant responses based on your ingested documents. The RAG process combines all the search functionality shown above with Large Language Models to produce more accurate and informative answers.
Behind the scenes, R2R’s RetrievalService handles RAG requests, combining the power of vector search, optional knowledge graph integration, and language model generation. The flexible architecture allows for easy customization and extension of the RAG pipeline to meet diverse requirements.
Graphs in R2R
R2R implements a Git-like model for knowledge graphs, where each collection has a corresponding graph that can diverge and be independently managed. This approach allows for flexible knowledge management while maintaining data consistency.
Graph-Collection Relationship
- Each collection has an associated graph that acts similar to a Git branch
- Graphs can diverge from their underlying collections through independent updates
- The
pull
operation syncs the graph with its collection, similar to a Git pull - This model enables experimental graph modifications without affecting the base collection
Knowledge Graph Workflow
Best Practices
-
Graph Synchronization
- Always
pull
before attempting to list or work with entities - Keep track of which documents have been added to the graph
- Always
-
Community Management
- Build communities after significant changes to the graph
- Use community information to enhance search results
-
Version Control
- Treat graphs like Git branches - experiment freely
- Use
reset
to start fresh if needed - Maintain documentation of graph modifications
This Git-like model provides a flexible framework for knowledge management while maintaining data consistency and enabling experimental modifications.
User Management
R2R provides robust user auth and management capabilities. This section briefly covers user authentication features and how they relate to document management.
These authentication features ensure that users can only access and manage their own documents. When performing operations like search, RAG, or document management, the results are automatically filtered based on the authenticated user’s permissions.
Remember to replace YOUR_ACCESS_TOKEN
and YOUR_REFRESH_TOKEN
with actual tokens obtained during the login process.
Observability and Analytics
R2R provides robust observability and analytics features, allowing superusers to monitor system performance, track usage patterns, and gain insights into the RAG application’s behavior. These advanced features are crucial for maintaining and optimizing your R2R deployment.
Observability and analytics features are restricted to superusers only. By default, R2R is configured to treat unauthenticated users as superusers for quick testing and development. In a production environment, you should disable this setting and properly manage superuser access.
These observability and analytics features provide valuable insights into your R2R application’s performance and usage, enabling data-driven optimization and decision-making.