DOCSEARCHbyAlgolia
Submit Docs

NodeRAG Documentation

repository·main·Indexed 19 days ago

https://github.com/terry-xu-666/noderag

NodeRAG is a heterogeneous graph-based Retrieval-Augmented Generation (RAG) framework (v0.1.0) designed to improve retrieval precision and explainability. It utilizes functionally distinct nodes to integrate graph-based methodologies into RAG workflows, featuring fine-grained retrieval, incremental graph updates, and a dedicated Web UI for managing configurations and visualizing graph structures. The system includes the NodeRag orchestration class, NodeSearch for querying, and a CLI for interacting with the search engine.

Tokens
2.2K
Snippets
8
Records
12
Agent score
65%

What's inside NodeRAG

  1. Overview of NodeRAG features

    main

    NodeRAG is a heterogeneous graph-based generation and retrieval RAG system. Key capabilities include:

    • Heterogeneous Graph Structure: Strengthens the foundation of graph-based RAG by using functionally distinct nodes.
    • Fine-Grained & Explainable Retrieval: Uses HeteroGraphs to ensure precise, context-aware, and interpretable retrieval.
    • Unified Information Retrieval: Integrates extracted insights and raw data as interconnected nodes in a single seamless system.
    • Optimized Performance: Features faster graph construction and retrieval speeds via unified algorithms.
    • Incremental Graph Updates: Supports updating heterogeneous graphs using graph connectivity mechanisms.
    • Visualization & UI: Includes a visualization system and a Web UI for exploring and managing graph structures.

  2. Install NodeRAG

    main

    You can install NodeRAG using standard pip or the faster uv package manager. It is recommended to use a virtual environment like Conda to manage dependencies.

    Using Conda (Recommended Setup)

    First, create and activate a dedicated environment:

    conda create -n NodeRAG python=3.10
conda activate NodeRAG

    Using uv for Faster Installation (Optional)

    To optimize installation speed, you can use uv:

    pip install uv
uv pip install NodeRAG

    Standard Installation

    If not using uv, install via pip:

    pip install NodeRAG
    conda create -n NodeRAG python=3.10
conda activate NodeRAG
pip install uv
uv pip install NodeRAG

  3. Configure NodeRAG connection settings in Node_config.yaml

    main

    The CLI reads connection parameters from a Node_config.yaml file located within the directory specified by the --folder (or -f) argument. The configuration must contain a top-level config key.

    Supported keys under config:

    • url: The hostname or IP address of the NodeRAG service (defaults to 127.0.0.1).
    • port: The port number the service is running on (defaults to 5000).
    config:
  url: "127.0.0.1"
  port: 5000

  4. Configure Model and Embedding providers

    main

    The Web UI manages credentials and model selection for both the LLM and the embedding engine.

    Model Settings

    • service_provider: Choose between openai or gemini.
    • model_name: Specific model (e.g., gpt-4o, gemini-2.0-flash-lite-preview-02-05).
    • api_keys: The API key for the selected provider.
    • temperature: Generation randomness (0.0 to 1.0).
    • max_tokens: Maximum output tokens.
    • rate_limit: Number of concurrent requests allowed.

    Embedding Settings

    • service_provider: Choose between openai_embedding or gemini_embedding.
    • embedding_model_name: Specific model (e.g., text-embedding-3-small, text-embedding-004).
    • api_keys: The API key for the embedding provider.
    • rate_limit: Requests per second.

  5. Configure RAG and Search parameters

    main

    The Web UI allows fine-grained control over the RAG engine through several parameter groups. These settings are applied when the search engine is initialized or reloaded.

    RAG Settings

    • main_folder: The root directory for NodeRAG data.
    • language: Processing language (English, Chinese).
    • docu_type: Document types to process (mixed, md, txt, docx).
    • chunk_size: Size of text chunks (800-2000).
    • embedding_batch_size: Number of embeddings per batch.

    HNSW Index Settings

    • dim: Embedding dimension.
    • m: Max connections per layer.
    • ef: Size of dynamic candidate list.
    • m0: Number of bi-directional links.

    Search & Graph Settings

    • Hcluster_size: Size of high-level element clusters.
    • cross_node: Number of cross nodes.
    • Enode: Number of entity nodes.
    • Rnode: Number of relation nodes.
    • Hnode: Number of high-level nodes.
    • HNSW_results: Number of top results to return.
    • ppr_alpha: Alpha for Personalized PageRank (PPR).
    • ppr_max_iter: Maximum PPR iterations.
    • similarity_weight / accuracy_weight: Weights for retrieval scoring.

  6. Manage NodeRAG configuration via Web UI

    main

    The Web UI provides functions to load, retrieve, and save configurations stored in YAML files. The configuration is split into three main parts: config, model_config, and embedding_config.

    • load_config(path): Loads the configuration from a specified YAML file into the Streamlit session state.
    • all_config(): Returns a dictionary containing the current config, model_config, and embedding_config from the session state.
    • save_config(path): Persists the current session state configuration to the specified YAML file.

    By default, the application looks for Node_config.yaml and web_ui_config.yaml within the specified main_folder.

    # Example of how configuration is structured internally
# load_config(path) will populate:
# st.session_state.config
# st.session_state.model_config
# st.session_state.embedding_config

  7. Reference: NodeRAG CLI arguments

    main

    The following command-line arguments are available for the NodeRAG CLI:

    FlagLong FlagTypeDescription
    -q--questionstrThe question to ask the search engine
    -f--folderstrThe main folder of the project (must contain Node_config.yaml)
    -r--retrievalboolWhether to return the retrieval data
    -a--answerboolWhether to return the answer

    Behavior Logic:

    • If neither -a nor -r are provided: Returns only the answer.
    • If only -a is provided: Returns only the answer.
    • If only -r is provided: Returns only the retrieval.
    • If both -a and -r are provided: Returns a JSON object containing both answer and retrieval.

  8. Use the NodeRAG CLI to query the search engine

    main

    The NodeRAG CLI allows you to interact with the running NodeRAG service by sending questions. It requires a project folder containing a Node_config.yaml file to determine the service's connection details (URL and port).

    You can control the output format using flags to request just the answer, just the retrieval data, or both.

    # Example: Ask a question and get both the answer and retrieval data
python -m NodeRAG --question "What is NodeRAG?" --folder ./my_project --answer --retrieval

# Example: Ask a question and get only the answer
python -m NodeRAG -q "How does it work?" -f ./my_project -a

# Example: Ask a question and get only the retrieval information
python -m NodeRAG -q "Show me sources" -f ./my_project -r

  9. Use NodeRag for graph-based RAG orchestration

    main

    The NodeRag class is the primary entrypoint for orchestrating graph-based Retrieval-Augmented Generation (RAG) using heterogeneous nodes. It manages the construction and execution of the RAG workflow.

    from NodeRAG import NodeRag

  11. Use State_Observer to monitor building status

    main

    The State_Observer class is used to provide visual feedback during the NodeRAG building process (e.g., document processing, graph processing). It can be attached to a NodeRAG controller to observe and report progress.

    • __init__(build_status): Initializes the observer with a build_status object (typically a Streamlit status placeholder).
    • update(state): Updates the status display with the current building state.
    • reset(total_tasks, desc=""): Resets the status display, showing a description and a list of tasks to be completed.
    • close(): Clears the status display once the process is finished.
    # Usage pattern for monitoring a build process
state_observer = State_Observer(Build_Status_Placeholder)
state_observer.reset(
    total_tasks=["1. Document Processing", "2. Text Processing", "3. Graph Processing"],
    desc="Building the NodeRAG"
)
# ... inside the build loop ...
state_observer.update("Graph Processing")
# ... after completion ...
state_observer.close()