Overview
nano-graphrag is a simple, easy-to-modify implementation of GraphRAG. The project author points out that although GraphRAG is powerful, the official implementation is difficult to read and modify, so this project provides a smaller, faster, and clearer version while retaining the core functionality. Excluding tests and prompts, nano-graphrag is about 1100 lines of code.
Key Features
- Lightweight and portable: supports faiss, neo4j, ollama, etc.
- Asynchronous with complete type annotations
- Supports incremental insertion, avoiding recomputation and duplicate data addition
- Supports both naive RAG insertion and querying
- Replaceable LLM, embedding model, and storage components
- Customizable prompts and chunking methods
- Uses content MD5 hash as the key to avoid duplicate chunking
Installation and Configuration
Installing from source is recommended, and installation from PyPi is also possible. You need to set the OpenAI API key:export OPENAI_API_KEY="sk-...".
If you use the Azure OpenAI API, you can refer to .env.example for setup, and enable it via GraphRAG(...,using_azure_openai=True,...) . If you use the Amazon Bedrock API, you first need to configure credentials via aws configure , etc., and then enable it as in the example.
If you do not have a key, you can refer to the examples using transformers and ollama. If you need to use another LLM or embedding model, you can refer to the Advances section.
Usage
Download a copy of Charles Dickens' "A Christmas Carol" and initialize it using the example Python snippet. The next time you initialize GraphRAG from the same working_dir, all context will be automatically reloaded.
nano-graphrag supports incremental insertion and will not recompute or add data repeatedly. On each insertion, the graph's communities are recomputed, and community reports are regenerated.
For each method NAME(...), there is a corresponding asynchronous method aNAME(...).
GraphRAG and QueryParam are dataclasses in Python; you can use help(GraphRAG) and help(QueryParam) to view all available parameters.
Components and Integrations
Built-in components indicate that nano-graphrag already has an internal implementation, and examples indicate that an implementation is available in the tutorials in the examples folder. You can look at examples/benchmarks to understand comparisons between components.
Using GraphRAG(...,always_create_working_dir=False,...) can skip the directory creation step, which is suitable when all components are switched to non-file storage.
graph_func.query returns the final answer and does not perform streaming output. If you need to integrate nano-graphrag into a project, you can use param=QueryParam(..., only_need_context=True,...), which returns only the context retrieved from the graph, so that it can be integrated into a custom prompt.
Prompt Customization
nano-graphrag uses the prompts in the nano_graphrag.prompt.PROMPTS dictionary, and any of these prompts can be replaced. Important prompts include: entity_extraction (extract entities and relationships from text chunks), community_report (organize and summarize graph cluster descriptions), local_rag_response (the system prompt template generated by local search), global_reduce_rag_response (the system prompt template generated by global search), and fail_response (the fallback response when there is no relevant content for the user query).
LLM and Embedding
nano-graphrag requires two kinds of LLMs: a powerful one and a cheap one. The former is used for planning and responses, and the latter is used for summarization. By default, the powerful one is gpt-4o, and the cheap one is gpt-4o-mini. You can implement your own LLM function to replace them. You can refer to the examples using deepseek-chat or ollama as the LLM model.
nano-graphrag uses best_model_func to output JSON, with the parameter "response_format": {"type": "json_object"}. Some open-source models may produce unstable JSON, so a post-processing interface is introduced to convert the response into JSON, passed in via GraphRAG(...convert_response_to_json_func=YOUR_STRING_TO_JSON_FUNC,...) as a custom function. For example, you can refer to json_repair to repair the JSON string returned by the LLM.
Any _utils.EmbedddingFunc Instance replaces the default embedding function. By default, the OpenAI embedding API is used. You can refer to the example of using sentence-transformer to compute embeddings locally.
Storage Backends
nano-graphrag mainly uses three types of storage: base.BaseKVStorage is used to store key-value JSON data, and by default uses disk file storage; base.BaseVectorStorage is used to index embeddings, and by default uses nano-vectordb, and also has built-in hnswlib storage, and you can also refer to the example implementation of milvus-lite (not available on Windows); base.BaseGraphStorage is used to store the knowledge graph, and by default uses networkx, and also has built-in Neo4jStorage. It can be replaced via GraphRAG(.., key_string_value_json_storage_cls=YOURS,...)、GraphRAG(.., vector_db_storage_cls=YOURS,...)、GraphRAG(.., graph_storage_cls=YOURS,...) .
Benchmarks and Related Projects
The project provides English benchmarks, Chinese benchmarks, and an evaluation notebook for a multi-hop RAG task. Projects using nano-graphrag include: Medical Graph RAG, LightRAG, fast-graphrag, HiRAG.
Limitations
nano-graphrag does not implement GraphRAG's covariates feature. Its global search implementation differs from the original version: the original version uses a map-reduce-like approach to fill all communities into the context, whereas nano-graphrag only uses the top-K important and central communities (controllable via QueryParam.global_max_consider_community, defaulting to 512 communities).
Contributions
nano-graphrag welcomes all kinds of contributions; please read the relevant instructions before contributing.
