RAPTOR RAG Endpoints Overview

RAPTOR RAG nodes are advanced hierarchical RAG components that construct multi-level tree structures from documents using sophisticated clustering algorithms and recursive abstraction. These nodes implement the RAPTOR (Recursive Abstractive Processing for Tree-Organized Retrieval) methodology.

Benefits of RAPTOR RAG Nodes

Hierarchical Document Abstraction

RAPTOR RAG nodes excel at creating multi-level semantic hierarchies from document collections, using Gaussian Mixture Model clustering to group semantically similar content and LLM-powered summarization to create abstract representations at each tree level.

Advanced Tree Construction

Unlike traditional flat retrieval systems, RAPTOR nodes build recursive tree structures where each level represents a different granularity of abstraction, enabling queries to traverse from specific details to high-level concepts seamlessly.

Multi-Level Retrieval Strategy

RAPTOR trees support intelligent traversal strategies that can retrieve relevant content from multiple abstraction levels simultaneously, providing both detailed information and contextual understanding.

Available Endpoints

List RAPTOR RAG Nodes

GET /{flow_name}/raptor-rag Retrieve all RAPTOR RAG nodes with hierarchical tree metrics, clustering statistics, and multi-level performance data.

Update RAPTOR RAG Configuration

PATCH /{flow_name}/raptor-rag/{node_id} Configure hierarchical tree parameters including retrieval depth and maximum tree levels for optimal abstraction.

Core Concepts

RAPTOR RAG Node Structure

{
  "id": "raptor-rag-1748287628685",
  "type": "raptor-rag",
  "data": {
    "name": "Hierarchical RAPTOR RAG",
    "config": {
      "topK": 25,
      "max_level": 4
    },
    "result": {
      "updated": true,
      "tree_levels": 4,
      "total_clusters": 65,
      "total_summaries": 45,
      "total_processed": 1850,
      "total_chunks": 520,
      "total_retrieved": 80
    }
  }
}

Configuration Parameters

Parameter	Type	Range	Description
`topK`	integer \| null	1-100 or null	Number of top results to retrieve from hierarchical tree traversal
`max_level`	integer	2-8	Maximum depth of tree hierarchy for recursive abstraction

Hierarchical Tree Metrics

Metric	Description	Optimization Impact
`tree_levels`	Actual levels built in the hierarchy	Higher levels = richer abstractions
`total_clusters`	Clusters created across all tree levels	More clusters = finer granularity
`total_summaries`	Summary nodes generated through abstraction	More summaries = better hierarchy quality
`clustering_ratio`	clusters/chunks ratio	Optimal range: 0.5-0.8 for balanced structure
`summarization_ratio`	summaries/clusters ratio	Higher ratios indicate effective abstraction
`tree_density`	summaries per level	Balanced density ensures traversal efficiency

RAPTOR Tree Strategies

1. Precision-Focused Strategy

Optimal for: High-accuracy applications requiring focused hierarchical retrieval

{
  "config": {
    "topK": 10,
    "max_level": 3
  }
}

Characteristics:

Tree Depth: Standard 3-level hierarchy
Retrieval Scope: Highly selective with 10 top results
Processing Speed: Fast tree construction and traversal
Memory Usage: Low (~240MB estimated)

Best Use Cases:

Legal document analysis with precise precedent matching
Medical research requiring accurate diagnostic information
Technical specification lookup with exact parameter matching

2. Balanced Hierarchy Strategy

Optimal for: General-purpose applications requiring comprehensive coverage

{
  "config": {
    "topK": 25,
    "max_level": 4
  }
}

Characteristics:

Tree Depth: Extended 4-level hierarchy for richer abstractions
Retrieval Scope: Balanced coverage with 25 results
Processing Speed: Moderate construction time with good traversal efficiency
Memory Usage: Medium (~385MB estimated)

Best Use Cases:

Knowledge management systems with diverse content types
Research paper analysis across multiple domains
Documentation systems requiring hierarchical navigation

3. Comprehensive Coverage Strategy

Optimal for: Exploratory analysis requiring extensive hierarchical insights

{
  "config": {
    "topK": 50,
    "max_level": 5
  }
}

Characteristics:

Tree Depth: Deep 5-level hierarchy with maximum abstraction layers
Retrieval Scope: Extensive coverage with 50 results
Processing Speed: Longer construction time with comprehensive traversal
Memory Usage: High (~620MB estimated)

Best Use Cases:

Literature review systems requiring exhaustive topic coverage
Discovery research with broad conceptual exploration
Comprehensive content analysis across large corpora

4. Unlimited Exploration Strategy

Optimal for: Research applications requiring complete hierarchical coverage

{
  "config": {
    "topK": null,
    "max_level": 6
  }
}

Characteristics:

Tree Depth: Maximum 6-level hierarchy with deepest abstractions
Retrieval Scope: Unlimited results from complete tree traversal
Processing Speed: Resource-intensive with comprehensive coverage
Memory Usage: Very High (~1000MB+ estimated)

Best Use Cases:

Academic research requiring exhaustive literature analysis
Comprehensive surveys across multiple research domains
Advanced knowledge exploration systems

Strategy Selection Matrix

Use Case Type	Document Count	Complexity	Recommended Strategy	Top K	Max Level
Legal Analysis	100-500	High	Precision-Focused	10	3
Medical Research	200-800	High	Precision-Focused	15	3
Knowledge Base	500-2000	Medium	Balanced Hierarchy	25	4
Research Papers	800-3000	Medium	Balanced Hierarchy	30	4
Literature Review	1000-5000	High	Comprehensive Coverage	50	5
Discovery Research	2000+	Very High	Comprehensive Coverage	60	5
Academic Survey	3000+	Very High	Unlimited Exploration	null	6
Multi-Domain Analysis	5000+	Very High	Unlimited Exploration	null	6

Basic Integration Example

JavaScript RAPTOR RAG Configuration

class RaptorRagManager {
  constructor(flowName, apiToken) {
    this.flowName = flowName;
    this.apiToken = apiToken;
    this.baseUrl = `https://${flowName}.flows.graphorlm.com`;
  }

  async updateRaptorConfiguration(nodeId, config) {
    const response = await fetch(`${this.baseUrl}/raptor-rag/${nodeId}`, {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${this.apiToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ config }),
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  }

  async listRaptorNodes() {
    const response = await fetch(`${this.baseUrl}/raptor-rag`, {
      headers: { Authorization: `Bearer ${this.apiToken}` },
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  }
}

// Usage Example
const raptorManager = new RaptorRagManager("my-rag-pipeline", "YOUR_API_TOKEN");

// Configure RAPTOR RAG node
raptorManager
  .updateRaptorConfiguration("raptor-rag-1748287628685", {
    topK: 25,
    max_level: 4,
  })
  .then((result) => {
    console.log("✅ RAPTOR configuration updated successfully");
    console.log(`Node ID: ${result.node_id}`);
  })
  .catch((error) => console.error("❌ Configuration update failed:", error));

Best Practices

Hierarchical Tree Design

Document Collection Analysis: Always analyze document characteristics before selecting RAPTOR configuration
Strategy Selection: Choose strategies based on use case requirements, not arbitrary preferences
Tree Depth Optimization: Balance abstraction richness with processing performance for optimal results
Clustering Quality: Monitor clustering ratios to ensure effective semantic grouping across tree levels

Performance Optimization

Memory Management: Plan memory allocation for deep hierarchical trees, especially with large document collections
Processing Efficiency: Use document-aware configuration to optimize tree construction time
Retrieval Strategy: Balance Top K values with traversal efficiency for optimal query performance
Resource Monitoring: Continuously monitor tree construction and retrieval performance metrics

Configuration Management

Dynamic Optimization: Adjust configurations based on actual performance metrics and user feedback
Strategy Evolution: Evolve from precision-focused to comprehensive strategies as document collections grow
Quality Assessment: Regularly evaluate clustering and summarization quality across tree levels
Performance Tracking: Maintain historical performance data to identify optimization trends

Troubleshooting

Tree Construction Failures

Problem: RAPTOR tree construction fails or produces poor hierarchical structureSolutions:

Verify document collection has sufficient semantic diversity for meaningful clustering
Check memory allocation - deep trees require significant memory resources
Reduce max_level for large document collections (>3000 documents)
Ensure documents have adequate length for effective clustering (>200 words recommended)
Monitor clustering algorithm convergence during Gaussian Mixture Model fitting

High Memory Usage

Problem: RAPTOR tree construction consumes excessive memory Solutions:

Reduce max_level to decrease tree complexity (try max_level=3 or 4) - Process large document collections in smaller batches - Monitor base chunking size - smaller chunks reduce memory pressure - Use precision-focused strategy for memory-constrained environments - Implement memory monitoring during tree construction phases

Slow Hierarchical Retrieval

Problem: RAPTOR tree traversal and retrieval is slower than expected Solutions: - Reduce Top K to focus retrieval on most relevant results - Optimize tree structure by adjusting max_level based on document collection - Check for inefficient tree structure from poor clustering quality - Implement parallel processing for multiple simultaneous queries - Monitor tree density - overly dense trees slow traversal

Configuration Conflicts

Problem: RAPTOR configuration updates fail or produce unexpected resultsSolutions:

Verify Top K is within valid range (1-100 or null) for unlimited retrieval
Ensure max_level is between 2-8 for optimal tree performance
Check that configuration changes are compatible with existing tree structure
Rebuild tree structure when making significant configuration changes
Validate JSON payload structure matches expected RAPTOR schema

Next Steps

Explore advanced RAPTOR RAG capabilities and integration patterns:

List RAPTOR RAG Nodes

Retrieve detailed hierarchical tree metrics and clustering statistics for performance analysis

Update RAPTOR RAG Configuration

Configure hierarchical tree parameters with advanced optimization strategies

Flow Management

Integrate RAPTOR RAG nodes into comprehensive RAG pipeline architectures

Dataset Integration

Connect document sources to RAPTOR RAG hierarchical processing pipelines

Get Started

Sources

Flows

RAPTOR RAG Endpoints Overview

Benefits of RAPTOR RAG Nodes

Hierarchical Document Abstraction

Advanced Tree Construction

Multi-Level Retrieval Strategy

Available Endpoints

List RAPTOR RAG Nodes

Update RAPTOR RAG Configuration

Core Concepts

RAPTOR RAG Node Structure

Configuration Parameters

Hierarchical Tree Metrics

RAPTOR Tree Strategies

1. Precision-Focused Strategy

2. Balanced Hierarchy Strategy

3. Comprehensive Coverage Strategy

4. Unlimited Exploration Strategy

Strategy Selection Matrix

Basic Integration Example

JavaScript RAPTOR RAG Configuration

Best Practices

Hierarchical Tree Design

Performance Optimization

Configuration Management

Troubleshooting

Next Steps

List RAPTOR RAG Nodes

Update RAPTOR RAG Configuration

Flow Management

Dataset Integration

Get Started

Sources

Flows

​Benefits of RAPTOR RAG Nodes

​Hierarchical Document Abstraction

​Advanced Tree Construction

​Multi-Level Retrieval Strategy

​Available Endpoints

List RAPTOR RAG Nodes

Update RAPTOR RAG Configuration

​Core Concepts

​RAPTOR RAG Node Structure

​Configuration Parameters

​Hierarchical Tree Metrics

​RAPTOR Tree Strategies

​1. Precision-Focused Strategy

​2. Balanced Hierarchy Strategy

​3. Comprehensive Coverage Strategy

​4. Unlimited Exploration Strategy

​Strategy Selection Matrix

​Basic Integration Example

​JavaScript RAPTOR RAG Configuration

​Best Practices

​Hierarchical Tree Design

​Performance Optimization

​Configuration Management

​Troubleshooting

​Next Steps

List RAPTOR RAG Nodes

Update RAPTOR RAG Configuration

Flow Management

Dataset Integration

Benefits of RAPTOR RAG Nodes

Hierarchical Document Abstraction

Advanced Tree Construction

Multi-Level Retrieval Strategy

Available Endpoints

Core Concepts

RAPTOR RAG Node Structure

Configuration Parameters

Hierarchical Tree Metrics

RAPTOR Tree Strategies

1. Precision-Focused Strategy

2. Balanced Hierarchy Strategy

3. Comprehensive Coverage Strategy

4. Unlimited Exploration Strategy

Strategy Selection Matrix

Basic Integration Example

JavaScript RAPTOR RAG Configuration

Best Practices

Hierarchical Tree Design

Performance Optimization

Configuration Management

Troubleshooting

Next Steps