How HugeGraph AI Implements Graph-Enhanced RAG: Architecture and Pipeline Deep Dive

HugeGraph AI implements Graph-Enhanced RAG by orchestrating modular pipeline nodes—including vector retrieval, Gremlin-based graph queries, and intelligent reranking—through a singleton scheduler that supports pure vector, pure graph, and hybrid retrieval strategies.

Apache HugeGraph AI delivers enterprise-grade Graph-Enhanced RAG capabilities through a flow-based architecture that unifies semantic vector search with property graph traversal. The implementation resides in the apache/incubator-hugegraph-ai repository, specifically within the hugegraph-llm module, where a pipeline-driven workflow connects Large Language Models with HugeGraph's distributed graph database. This architecture cleanly separates retrieval operators from orchestration logic, enabling flexible combinations of knowledge sources.

Core Architecture of Graph-Enhanced RAG

The Scheduler and Pipeline Pool

The orchestration backbone resides in hugegraph-llm/src/hugegraph_llm/flows/scheduler.py, where the SchedulerSingleton maintains a pipeline pool and exposes the primary entry point schedule_flow(flow_key, **kwargs). This singleton pattern ensures that pipeline instances are reused across requests while maintaining thread-safe state isolation.

When invoked, the scheduler instantiates a pycgraph.GPipeline object—a directed acyclic graph of operations—and binds it to a specific flow configuration. The scheduler handles the complete lifecycle from node registration through execution to result extraction.

Flow Registration and Flow Keys

Flow definitions are centralized in hugegraph_llm/flows/__init__.py through the FlowName enumeration. The system recognizes four distinct Graph-Enhanced RAG strategies:

• RAG_GRAPH_ONLY: Pure knowledge graph retrieval without vector search
• RAG_GRAPH_VECTOR: Hybrid retrieval combining vector similarity and graph traversal
• RAG_VECTOR_ONLY: Traditional vector RAG fallback
• RAG_RAW: Direct LLM inference without retrieval augmentation

Each flow key maps to a concrete class in the hugegraph_llm/flows/ directory that registers a specific sequence of operator nodes.

The Four Graph-Enhanced RAG Flows

RAGGraphOnlyFlow (Graph-Only Retrieval)

Purpose: Answers queries using only the knowledge graph structure, bypassing vector indices entirely.

Node Pipeline: KeywordExtractNode → SemanticIdQueryNode → SchemaNode → GraphQueryNode → MergeRerankNode → AnswerSynthesizeNode

Source: hugegraph-llm/src/hugegraph_llm/flows/rag_flow_graph_only.py

This flow extracts keywords from the user query, loads the graph schema via SchemaNode, generates Gremlin queries in GraphQueryNode, and synthesizes answers from subgraph results.

RAGGraphVectorFlow (Hybrid Retrieval)

Purpose: Combines semantic vector search with graph traversal for comprehensive context retrieval.

Node Pipeline: VectorQueryNode → KeywordExtractNode → SemanticIdQueryNode → SchemaNode → GraphQueryNode → MergeRerankNode → AnswerSynthesizeNode

Source: hugegraph-llm/src/hugegraph_llm/flows/rag_flow_graph_vector.py

This hybrid approach executes vector retrieval first to identify relevant entity IDs, then uses those IDs to seed graph traversals, enabling precise multi-hop reasoning over related entities.

RAGVectorOnlyFlow (Vector Fallback)

Purpose: Provides traditional vector RAG when graph data is unavailable or unnecessary.

Node Pipeline: VectorQueryNode → MergeRerankNode → AnswerSynthesizeNode

Source: hugegraph-llm/src/hugegraph_llm/flows/rag_flow_vector_only.py

RAGRawFlow (Direct LLM)

Purpose: Baseline direct inference without retrieval.

Node Pipeline: AnswerSynthesizeNode

Source: hugegraph-llm/src/hugegraph_llm/flows/rag_flow_raw.py

Step-by-Step Data Flow in Graph-Enhanced RAG

The pipeline execution follows a strict eight-phase sequence orchestrated by BaseFlow subclasses:

1. Input Preparation: BaseFlow.prepare constructs a WkFlowInput object containing the user query, boolean flags (graph_search, vector_search), and ratio parameters. This object is stored as a G-parameter wkflow_input accessible to all nodes.

2. Keyword Extraction: KeywordExtractNode analyzes the natural language query to identify salient terms for both vector indexing and graph property matching.

3. Semantic Vector Search: SemanticIdQueryNode (or VectorQueryNode in hybrid mode) queries the configured vector index specified by index_settings.cur_vector_index. The implementation uses the embedding model from hugegraph_llm.models.embeddings.init_embedding.Embeddings to retrieve top-k document IDs, storing results in vector_result.

4. Graph Schema Loading: SchemaNode fetches the current graph schema from the HugeGraph server via PyHugeClient, making vertex labels, edge labels, and property keys available for Gremlin query generation.

5. Graph Query Execution: GraphQueryNode constructs and executes Gremlin queries based on extracted keywords or matched vertex IDs. The raw traversal results are serialized to JSON strings and stored as graph_result.

6. Merge and Rerank: MergeRerankNode receives both vector_result and graph_result, applying configurable ranking algorithms. The node supports bleu scoring for n-gram overlap or a learned reranker model for semantic relevance scoring.

7. Answer Synthesis: AnswerSynthesizeNode formats the final LLM prompt using templates from prompt.answer_prompt, injecting the retrieved context (vector, graph, or hybrid) to generate the grounded response.

8. Post-Processing: BaseFlow.post_deal extracts structured fields from wkflow_state, returning a standardized dictionary containing raw_answer, vector_only_answer, graph_only_answer, and graph_vector_answer.

Configuration and Extensibility

Global Settings

Runtime behavior is controlled through hugegraph_llm/config/huge_settings.py, which specifies:

• max_graph_items: Maximum entities to retrieve from graph traversals
• graph_name: Target HugeGraph database instance
• vector_dis_threshold: Similarity cutoff for vector retrieval

Vector index configuration resides in hugegraph_llm/config/index_settings.py, supporting pluggable backends including FAISS, Milvus, and Qdrant.

Extending the Pipeline

New retrieval operators can be implemented under hugegraph_llm/operators/ and registered as nodes without modifying core flow logic. The fixed-flow design documented in spec/hugegraph-llm/fixed_flow/design.md decouples node lifecycle management from flow orchestration, enabling parallel execution and pipeline reuse across different queries.

Implementing Graph-Enhanced RAG in Practice

Invoking Graph-Only Retrieval

from hugegraph_llm.flows.scheduler import SchedulerSingleton, FlowName

scheduler = SchedulerSingleton.get_instance()
result = scheduler.schedule_flow(
    FlowName.RAG_GRAPH_ONLY,
    query="How many patents does Alice hold?",
    graph_search=True,
    vector_search=False,
)

print(result["graph_only_answer"])

Source: hugegraph_llm/demo/rag_demo/rag_block.py

Executing Hybrid Graph + Vector Retrieval

from hugegraph_llm.flows.scheduler import SchedulerSingleton, FlowName

scheduler = SchedulerSingleton.get_instance()
answer = scheduler.schedule_flow(
    FlowName.RAG_GRAPH_VECTOR,
    query="Explain the relationship between Company X and its subsidiaries.",
    graph_search=True,
    vector_search=True,
    graph_ratio=0.6,  # 60% weight on graph results

)

print(answer["graph_vector_answer"])

Source: hugegraph_llm/demo/rag_demo/vector_graph_block.py

Configuring the Rerank Method

result = scheduler.schedule_flow(
    FlowName.RAG_GRAPH_VECTOR,
    query="What products are sold by store 42?",
    rerank_method="reranker",  # Alternative to "bleu"

)

Direct Pipeline Construction

For advanced use cases requiring manual control:

from hugegraph_llm.flows.rag_flow_graph_vector import RAGGraphVectorFlow

flow = RAGGraphVectorFlow()
pipeline = flow.build_flow(
    query="Describe the supply chain for product Y.",
    vector_search=True,
    graph_search=True,
)

pipeline.run()
state = pipeline.getGParamWithNoEmpty("wkflow_state").to_json()
print(state["graph_vector_answer"])

Summary

• Pipeline Architecture: Graph-Enhanced RAG in HugeGraph AI uses a singleton scheduler to manage reusable pycgraph.GPipeline instances composed of specialized operator nodes.
• Four Retrieval Modes: The system supports graph-only, vector-only, hybrid, and raw LLM flows, selectable via FlowName enums in the scheduler.
• Unified Data Flow: All flows follow a standardized eight-phase pipeline from keyword extraction through Gremlin query execution to final answer synthesis.
• Configurable Backends: Vector indices (FAISS, Milvus, Qdrant) and graph settings are externalized in huge_settings.py and index_settings.py.
• Extensible Design: New retrieval operators integrate cleanly into the node-based architecture without disrupting existing flow definitions.

Frequently Asked Questions

What is the difference between RAGGraphOnlyFlow and RAGGraphVectorFlow?

RAGGraphOnlyFlow executes retrieval exclusively against the HugeGraph database using Gremlin queries generated from extracted keywords, while RAGGraphVectorFlow performs a two-stage retrieval: first executing semantic vector search to identify relevant entity IDs, then using those IDs to seed graph traversals. The hybrid approach in RAGGraphVectorFlow enables precise multi-hop reasoning by combining semantic similarity with structural graph relationships.

How does HugeGraph AI combine results from vector and graph retrieval?

The MergeRerankNode (hugegraph_llm/nodes/common_node/merge_rerank_node.py) receives both vector_result and graph_result from upstream nodes, then applies configurable ranking strategies. Users can select bleu scoring for lexical overlap or a learned reranker model via the rerank_method parameter. The node produces a unified ranking that respects the graph_ratio weighting parameter specified during flow invocation.

Can I customize the embedding model used for vector retrieval?

Yes. The embedding implementation is configured through hugegraph_llm/models/embeddings/init_embedding.Embeddings, which is referenced by SemanticIdQueryNode and VectorQueryNode. The specific vector index implementation (FAISS, Milvus, or Qdrant) is determined by index_settings.cur_vector_index in hugegraph_llm/config/index_settings.py, allowing pluggable replacement of both embedding models and vector storage backends.

What query language does HugeGraph AI use for graph retrieval?

HugeGraph AI generates and executes Gremlin queries through the GraphQueryNode (hugegraph_llm/nodes/hugegraph_node/graph_query_node.py). The node uses PyHugeClient to communicate with the HugeGraph server, constructing traversals based on the extracted keywords and schema information loaded by SchemaNode. The raw Gremlin results are serialized to JSON for downstream processing by the merge and synthesis nodes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}