How gusye1234/nano-graphrag works
Below are step-by-step instructions that incorporate the project’s structure and purpose:
Project Type and Purpose
• The README and file structure reveal that this is a GraphRAG library – a retrieval-augmented generation solution that uses graph structures to combine entity extraction with LLM and embedding functionalities.
• The project emphasizes using different storage backends (e.g., neo4j, networkx for graphs, hnswlib and nano-vectordb for vector search, and JSON file storage for key-value pairs) and multiple LLM providers (built-in support for OpenAI, Amazon Bedrock, DeepSeek, ollama, etc.). It is designed to be “small, faster, and cleaner” than other implementations.
• Users insert text documents (or batches), which are processed to extract entities and relationships, then stored and later retrieved via different query modes (global, local, naive).
Analyzing the File Structure
• The top-level directories (docs, examples, tests, and the core package directory “nano_graphrag”) show:
• Configuration and deployment scripts (.github, .env.example, etc.)
• Documentation (docs folder)
• Example usage and benchmarks (examples folder)
• Core implementation within the “nano_graphrag” directory that contains modules for LLM, operations, splitting/chunking, and various storage implementations under “_storage”
• Tests that cover entity extraction, chunking, graph storage, and integration with external APIs.
• The presence of “entity_extraction”, “_llm”, “_storage”, and others signals a modular architecture where each aspect (LLM integration, text processing, storage) is encapsulated in its own component.
Key Components to Capture
a. Main Components:
• Client / User Scripts:
• Represented by the example scripts and notebooks (under examples) that call the GraphRAG API.
• GraphRAG Core Module:
• The central class (in nano_graphrag/graphrag.py) that coordinates operations (insertion, querying, etc.).
• Chunker/Text Splitter:
• Located in nano_graphrag/_splitter.py (and referenced in _op.py) for breaking text into manageable chunks.
• Entity Extraction Module:
• Found in nano_graphrag/entity_extraction/ which extracts entities and relationships from text.
• Storage Components:
• Key-Value Storage: Handles mapping of chunk hashes to content.
• Vector Storage: Manages embeddings (using nano-vectordb, hnswlib, or examples with milvus-lite, faiss).
• Graph Storage: Implements the knowledge graph (using networkx by default, with neo4j as an alternative).
• Embedding and LLM Integration:
• Embedding functions (either built-in using OpenAI or an alternative like sentence-transformers as seen in the examples).
• LLM functions: “best_model_func” and “cheap_model_func” for high-quality and summary responses.
• Prompt Management:
• The prompt templates used to drive entity extraction, community reporting, and responses.
b. Relationships and Interactions:
• The GraphRAG class receives text from the client. It then:
• Uses the chunker to break text into portions.
• Calls the entity extraction module to parse out entities and their relationships.
• Obtains embeddings for chunks using the embedding function.
• Persists these chunks and embedding vectors into appropriate storage (KV, vector, graph storages).
• When a query is issued:
• The system (using QueryParam) decides on the mode (local, global, or naive).
• The vector storage is queried, and the knowledge graph is traversed (via networkx or neo4j) to collect context.
• The LLM is then invoked (using either the “best” high-quality model or a cheaper model) to generate the final answer.
• Responses are post-processed (for instance, converting string outputs into JSON when needed).
c. Architectural Patterns and Design Principles:
• Modularity: Each functionality (chunking, extraction, storage, LLM, embedding) is isolated in its module, enabling easy swapping-out or extension.
• Asynchronous Design: Both synchronous and async methods are provided (method naming convention “a<method_name>”) to improve performance.
• Configurability: Many components (embedding function, storage classes, LLM functions) are injectable into GraphRAG when initializing.
• Extensibility: The architecture supports adding additional storage backends or LLM providers (as seen by examples and the separation between built-in and “examples” implementations).
Specific Elements
• Labels for every component (e.g., “Text Chunker”, “Entity Extractor”, “Embedding Service”, “Graph Storage (NetworkX/Neo4j)”, “LLM Interface”).
• From “Client” to “GraphRAG Core”
• From “GraphRAG” to “Text Chunker” and then “Entity Extraction”
• From generated chunks to the “KV Storage”, “Vector Storage”, and “Graph Storage”
• From “Query Service” to both storage modules and then to the “LLM” for final answer generation
• Internal processing components
• Storage systems (persistent layers)
• External integrations (LLM APIs, embedding providers)
• Annotations highlighting that many of these components support asynchronous operations.
• Chunking/Preprocessing
• Entity Extraction & Prompt Preparation
• Embedding Function
• Next, branch out to three storage components:
• Vector Storage: for embedding indexing (annotate with “nano-vectordb / hnswlib / faiss”)
• Graph Storage: for the relationship network (show alternatives: networkx by default, neo4j optionally)
• Finally, include the “LLM Interface” block that handles query generation using both “best” and “cheap” LLM functions.