Walkthrough

This guide shows how to use R2R to:

1. Ingest files into R2R
2. Search over ingested files
3. Use your data as input to RAG (Retrieval-Augmented Generation)
4. Extract entities and relationships from your data to create a graph.
5. Perform basic user auth
6. 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:

1
from r2r import R2RClient
2
3
client = R2RClient("http://localhost:7272")
4
5
with open("test.txt", "w") as file:
6
    file.write("John is a person that works at Google.")
7
8
client.documents.create(file_path="test.txt")
9
10
# Call RAG directly
11
rag_response = client.retrieval.rag(
12
    query="Who is john",
13
    rag_generation_config={"model": "openai/gpt-4o-mini", "temperature": 0.0},
14
)
15
results = rag_response["results"]
16
17
print(f"Search Results:\n{results['search_results']}")
18
# {'chunk_search_results': [{'chunk_id': 'b9f40dbd-2c8e-5c0a-8454-027ac45cb0ed', 'document_id': '7c319fbe-ca61-5770-bae2-c3d0eaa8f45c', 'user_id': '2acb499e-8428-543b-bd85-0d9098718220', 'collection_ids': ['122fdf6a-e116-546b-a8f6-e4cb2e2c0a09'], 'score': 0.6847735847465275, 'text': 'John is a person that works at Google.', 'metadata': {'version': 'v0', 'chunk_order': 0, 'document_type': 'txt', 'associated_query': 'Who is john'}}], 'kg_search_results': []}
19
20
print(f"Completion:\n{results['completion']}")
21
# {'id': 'chatcmpl-AV1Sc9DORfHvq7yrmukxfJPDV5dCB', 'choices': [{'finish_reason': 'stop', 'index': 0, 'logprobs': None, 'message': {'content': 'John is a person that works at Google [1].', 'refusal': None, 'role': 'assistant', 'audio': None, 'function_call': None, 'tool_calls': None}}], 'created': 1731957146, 'model': 'gpt-4o-mini', 'object': 'chat.completion', 'service_tier': None, 'system_fingerprint': 'fp_04751d0b65', 'usage': {'completion_tokens': 11, 'prompt_tokens': 145, 'total_tokens': 156, 'completion_tokens_details': None, 'prompt_tokens_details': None}}

Configuring R2R

R2R is highly configurable. To customize your R2R deployment:

1. Create a local configuration file named r2r.toml.
2. In this file, override default settings as needed.

For example:

1
[completion]
2
provider = "litellm"
3
concurrent_request_limit = 16
4
5
  [completion.generation_config]
6
  model = "openai/gpt-4o"
7
  temperature = 0.5
8
9
[ingestion]
10
provider = "r2r"
11
chunking_strategy = "recursive"
12
chunk_size = 1_024
13
chunk_overlap = 512
14
excluded_parsers = ["mp4"]

Then, use the config-path argument to specify your custom configuration when launching R2R:

$
r2r serve --docker --config-path=r2r.toml

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 corresponding id, created for each ingested file or context, which contains the downstream Chunks and Entities & Relationships.
• User and Collection 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:

1
r2r retrieval search --query="What was Uber's profit in 2020?"

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:

1
r2r retrieval search --query="What was Uber's profit in 2020?" --use-hybrid-search=True

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

1. Graph Synchronization

   • Always pull before attempting to list or work with entities
   • Keep track of which documents have been added to the graph

2. Community Management

   • Build communities after significant changes to the graph
   • Use community information to enhance search results

3. 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.

These observability and analytics features provide valuable insights into your R2R application’s performance and usage, enabling data-driven optimization and decision-making.