{"id":14062328,"url":"https://github.com/gusye1234/nano-graphrag","last_synced_at":"2025-07-29T14:31:03.992Z","repository":{"id":251233019,"uuid":"833512367","full_name":"gusye1234/nano-graphrag","owner":"gusye1234","description":"A simple, easy-to-hack GraphRAG implementation","archived":false,"fork":false,"pushed_at":"2025-07-23T06:52:54.000Z","size":1360,"stargazers_count":3136,"open_issues_count":78,"forks_count":322,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-07-23T08:38:05.209Z","etag":null,"topics":["gpt","gpt-4o","graphrag","learning-by-doing","llm","rag"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gusye1234.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-25T07:53:58.000Z","updated_at":"2025-07-23T06:52:54.000Z","dependencies_parsed_at":"2024-08-26T10:10:42.740Z","dependency_job_id":"aeb95aa6-79a6-4ef2-88bb-76b06841f89c","html_url":"https://github.com/gusye1234/nano-graphrag","commit_stats":null,"previous_names":["gusye1234/nano-graphrag"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/gusye1234/nano-graphrag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gusye1234%2Fnano-graphrag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gusye1234%2Fnano-graphrag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gusye1234%2Fnano-graphrag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gusye1234%2Fnano-graphrag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gusye1234","download_url":"https://codeload.github.com/gusye1234/nano-graphrag/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gusye1234%2Fnano-graphrag/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267702876,"owners_count":24130463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gpt","gpt-4o","graphrag","learning-by-doing","llm","rag"],"created_at":"2024-08-13T07:01:11.540Z","updated_at":"2025-07-29T14:31:03.980Z","avatar_url":"https://github.com/gusye1234.png","language":"Python","funding_links":[],"categories":["Software","Python","Retrieval \u0026 Reranking","知识库 RAG","A01_文本生成_文本对话","RAG","2024.07","GraphRAG","Open Source Tools"],"sub_categories":["RAG","Frameworks","大语言对话模型及数据","Nano-GraphRAG【轻装上阵】","GraphRAG-Related Projects"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/gusye1234/nano-graphrag\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://assets.memodb.io/nano-graphrag-dark.png\"\u003e\n      \u003cimg alt=\"Shows the MemoDB logo\" src=\"https://assets.memodb.io/nano-graphrag.png\" width=\"512\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u003cp\u003e\u003cstrong\u003eA simple, easy-to-hack GraphRAG implementation\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e\n    \u003cimg src=\"https://img.shields.io/badge/python-\u003e=3.9.11-blue\"\u003e\n    \u003ca href=\"https://pypi.org/project/nano-graphrag/\"\u003e\n      \u003cimg src=\"https://img.shields.io/pypi/v/nano-graphrag.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codecov.io/github/gusye1234/nano-graphrag\" \u003e \n     \u003cimg src=\"https://codecov.io/github/gusye1234/nano-graphrag/graph/badge.svg?token=YFPMj9uQo7\"/\u003e \n \t\t\u003c/a\u003e\n    \u003ca href=\"https://pepy.tech/project/nano-graphrag\"\u003e\n      \u003cimg src=\"https://static.pepy.tech/badge/nano-graphrag/month\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n  \t\u003ca href=\"https://discord.gg/sqCVzAhUY6\"\u003e\n      \u003cimg src=\"https://dcbadge.limes.pink/api/server/sqCVzAhUY6?style=flat\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/gusye1234/nano-graphrag/issues/8\"\u003e\n       \u003cimg src=\"https://img.shields.io/badge/群聊-wechat-green\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n\n\n\n\n\n\n😭 [GraphRAG](https://arxiv.org/pdf/2404.16130) is good and powerful, but the official [implementation](https://github.com/microsoft/graphrag/tree/main) is difficult/painful to **read or hack**.\n\n😊 This project provides a **smaller, faster, cleaner GraphRAG**, while remaining the core functionality(see [benchmark](#benchmark) and [issues](#Issues) ).\n\n🎁 Excluding `tests` and prompts,  `nano-graphrag` is about **1100 lines of code**.\n\n👌 Small yet [**portable**](#Components)(faiss, neo4j, ollama...), [**asynchronous**](#Async) and fully typed.\n\n\n\n\u003e If you're looking for a multi-user RAG solution for long-term user memory, have a look at this project: [memobase](https://github.com/memodb-io/memobase) :)\n\n## Install\n\n**Install from source** (recommend)\n\n```shell\n# clone this repo first\ncd nano-graphrag\npip install -e .\n```\n\n**Install from PyPi**\n\n```shell\npip install nano-graphrag\n```\n\n\n\n## Quick Start\n\n\u003e [!TIP]\n\u003e\n\u003e **Please set OpenAI API key in environment: `export OPENAI_API_KEY=\"sk-...\"`.** \n\n\u003e [!TIP]\n\u003e If you're using Azure OpenAI API, refer to the [.env.example](./.env.example.azure) to set your azure openai. Then pass `GraphRAG(...,using_azure_openai=True,...)` to enable.\n\n\u003e [!TIP]\n\u003e If you're using Amazon Bedrock API, please ensure your credentials are properly set through commands like `aws configure`. Then enable it by configuring like this: `GraphRAG(...,using_amazon_bedrock=True, best_model_id=\"us.anthropic.claude-3-sonnet-20240229-v1:0\", cheap_model_id=\"us.anthropic.claude-3-haiku-20240307-v1:0\",...)`. Refer to an [example script](./examples/using_amazon_bedrock.py).\n\n\u003e [!TIP]\n\u003e\n\u003e If you don't have any key, check out this [example](./examples/no_openai_key_at_all.py) that using `transformers` and `ollama` . If you like to use another LLM or Embedding Model, check [Advances](#Advances).\n\ndownload a copy of A Christmas Carol by Charles Dickens:\n\n```shell\ncurl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt \u003e ./book.txt\n```\n\nUse the below python snippet:\n\n```python\nfrom nano_graphrag import GraphRAG, QueryParam\n\ngraph_func = GraphRAG(working_dir=\"./dickens\")\n\nwith open(\"./book.txt\") as f:\n    graph_func.insert(f.read())\n\n# Perform global graphrag search\nprint(graph_func.query(\"What are the top themes in this story?\"))\n\n# Perform local graphrag search (I think is better and more scalable one)\nprint(graph_func.query(\"What are the top themes in this story?\", param=QueryParam(mode=\"local\")))\n```\n\nNext time you initialize a `GraphRAG` from the same `working_dir`, it will reload all the contexts automatically.\n\n#### Batch Insert\n\n```python\ngraph_func.insert([\"TEXT1\", \"TEXT2\",...])\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e Incremental Insert\u003c/summary\u003e\n\n`nano-graphrag` supports incremental insert, no duplicated computation or data will be added:\n\n```python\nwith open(\"./book.txt\") as f:\n    book = f.read()\n    half_len = len(book) // 2\n    graph_func.insert(book[:half_len])\n    graph_func.insert(book[half_len:])\n```\n\n\u003e `nano-graphrag` use md5-hash of the content as the key, so there is no duplicated chunk.\n\u003e\n\u003e However, each time you insert, the communities of graph will be re-computed and the community reports will be re-generated\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e Naive RAG\u003c/summary\u003e\n\n`nano-graphrag` supports naive RAG insert and query as well:\n\n```python\ngraph_func = GraphRAG(working_dir=\"./dickens\", enable_naive_rag=True)\n...\n# Query\nprint(rag.query(\n      \"What are the top themes in this story?\",\n      param=QueryParam(mode=\"naive\")\n)\n```\n\u003c/details\u003e\n\n\n### Async\n\nFor each method `NAME(...)` , there is a corresponding async method `aNAME(...)`\n\n```python\nawait graph_func.ainsert(...)\nawait graph_func.aquery(...)\n...\n```\n\n### Available Parameters\n\n`GraphRAG` and `QueryParam` are `dataclass` in Python. Use `help(GraphRAG)` and `help(QueryParam)` to see all available parameters!  Or check out the [Advances](#Advances) section to see some options.\n\n\n\n## Components\n\nBelow are the components you can use:\n\n| Type            |                             What                             |                       Where                       |\n| :-------------- | :----------------------------------------------------------: | :-----------------------------------------------: |\n| LLM             |                            OpenAI                            |                     Built-in                      |\n|                 |                        Amazon Bedrock                        |                     Built-in                      |\n|                 |                           DeepSeek                           |              [examples](./examples)               |\n|                 |                           `ollama`                           |              [examples](./examples)               |\n| Embedding       |                            OpenAI                            |                     Built-in                      |\n|                 |                        Amazon Bedrock                        |                     Built-in                      |\n|                 |                    Sentence-transformers                     |              [examples](./examples)               |\n| Vector DataBase | [`nano-vectordb`](https://github.com/gusye1234/nano-vectordb) |                     Built-in                      |\n|                 |        [`hnswlib`](https://github.com/nmslib/hnswlib)        |         Built-in, [examples](./examples)          |\n|                 |  [`milvus-lite`](https://github.com/milvus-io/milvus-lite)   |              [examples](./examples)               |\n|                 | [faiss](https://github.com/facebookresearch/faiss?tab=readme-ov-file) |              [examples](./examples)               |\n| Graph Storage   | [`networkx`](https://networkx.org/documentation/stable/index.html) |                     Built-in                      |\n|                 |                [`neo4j`](https://neo4j.com/)                 | Built-in([doc](./docs/use_neo4j_for_graphrag.md)) |\n| Visualization   |                           graphml                            |              [examples](./examples)               |\n| Chunking        |                        by token size                         |                     Built-in                      |\n|                 |                       by text splitter                       |                     Built-in                      |\n\n- `Built-in` means we have that implementation inside `nano-graphrag`. `examples` means we have that implementation inside an tutorial under [examples](./examples) folder.\n\n- Check [examples/benchmarks](./examples/benchmarks) to see few comparisons between components.\n- **Always welcome to contribute more components.**\n\n## Advances\n\n\n\n\u003cdetails\u003e\n\u003csummary\u003eSome setup options\u003c/summary\u003e\n\n- `GraphRAG(...,always_create_working_dir=False,...)` will skip the dir-creating step. Use it if you switch all your components to non-file storages.\n\n\u003c/details\u003e\n\n\n\n\u003cdetails\u003e\n\u003csummary\u003eOnly query the related context\u003c/summary\u003e\n\n`graph_func.query` return the final answer without streaming. \n\nIf you like to interagte `nano-graphrag` in your project, you can use `param=QueryParam(..., only_need_context=True,...)`, which will only return the retrieved context from graph, something like:\n\n````\n# Local mode\n-----Reports-----\n```csv\nid,\tcontent\n0,\t# FOX News and Key Figures in Media and Politics...\n1, ...\n```\n...\n\n# Global mode\n----Analyst 3----\nImportance Score: 100\nDonald J. Trump: Frequently discussed in relation to his political activities...\n...\n````\n\nYou can integrate that context into your customized prompt.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePrompt\u003c/summary\u003e\n\n`nano-graphrag` use prompts from `nano_graphrag.prompt.PROMPTS` dict object. You can play with it and replace any prompt inside.\n\nSome important prompts:\n\n- `PROMPTS[\"entity_extraction\"]` is used to extract the entities and relations from a text chunk.\n- `PROMPTS[\"community_report\"]` is used to organize and summary the graph cluster's description.\n- `PROMPTS[\"local_rag_response\"]` is the system prompt template of the local search generation.\n- `PROMPTS[\"global_reduce_rag_response\"]` is the system prompt template of the global search generation.\n- `PROMPTS[\"fail_response\"]` is the fallback response when nothing is related to the user query.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCustomize Chunking\u003c/summary\u003e\n\n\n`nano-graphrag` allow you to customize your own chunking method, check out the [example](./examples/using_custom_chunking_method.py).\n\nSwitch to the built-in text splitter chunking method:\n\n```python\nfrom nano_graphrag._op import chunking_by_seperators\n\nGraphRAG(...,chunk_func=chunking_by_seperators,...)\n```\n\n\u003c/details\u003e\n\n\n\n\u003cdetails\u003e\n\u003csummary\u003eLLM Function\u003c/summary\u003e\n\nIn `nano-graphrag`, we requires two types of LLM, a great one and a cheap one. The former is used to plan and respond, the latter is used to summary. By default, the great one is `gpt-4o` and the cheap one is `gpt-4o-mini`\n\nYou can implement your own LLM function (refer to `_llm.gpt_4o_complete`):\n\n```python\nasync def my_llm_complete(\n    prompt, system_prompt=None, history_messages=[], **kwargs\n) -\u003e str:\n  # pop cache KV database if any\n  hashing_kv: BaseKVStorage = kwargs.pop(\"hashing_kv\", None)\n  # the rest kwargs are for calling LLM, for example, `max_tokens=xxx`\n\t...\n  # YOUR LLM calling\n  response = await call_your_LLM(messages, **kwargs)\n  return response\n```\n\nReplace the default one with:\n\n```python\n# Adjust the max token size or the max async requests if needed\nGraphRAG(best_model_func=my_llm_complete, best_model_max_token_size=..., best_model_max_async=...)\nGraphRAG(cheap_model_func=my_llm_complete, cheap_model_max_token_size=..., cheap_model_max_async=...)\n```\n\nYou can refer to this [example](./examples/using_deepseek_as_llm.py) that use [`deepseek-chat`](https://platform.deepseek.com/api-docs/) as the LLM model\n\nYou can refer to this [example](./examples/using_ollama_as_llm.py) that use [`ollama`](https://github.com/ollama/ollama) as the LLM model\n\n#### Json Output\n\n`nano-graphrag` will use `best_model_func` to output JSON with params `\"response_format\": {\"type\": \"json_object\"}`. However there are some open-source model maybe produce unstable JSON. \n\n`nano-graphrag` introduces a post-process interface for you to convert the response to JSON. This func's signature is below:\n\n```python\ndef YOUR_STRING_TO_JSON_FUNC(response: str) -\u003e dict:\n  \"Convert the string response to JSON\"\n  ...\n```\n\nAnd pass your own func by `GraphRAG(...convert_response_to_json_func=YOUR_STRING_TO_JSON_FUNC,...)`.\n\nFor example, you can refer to [json_repair](https://github.com/mangiucugna/json_repair) to repair the JSON string returned by LLM. \n\u003c/details\u003e\n\n\n\n\u003cdetails\u003e\n\u003csummary\u003eEmbedding Function\u003c/summary\u003e\n\nYou can replace the default embedding functions with any `_utils.EmbedddingFunc` instance.\n\nFor example, the default one is using OpenAI embedding API:\n\n```python\n@wrap_embedding_func_with_attrs(embedding_dim=1536, max_token_size=8192)\nasync def openai_embedding(texts: list[str]) -\u003e np.ndarray:\n    openai_async_client = AsyncOpenAI()\n    response = await openai_async_client.embeddings.create(\n        model=\"text-embedding-3-small\", input=texts, encoding_format=\"float\"\n    )\n    return np.array([dp.embedding for dp in response.data])\n```\n\nReplace default embedding function with:\n\n```python\nGraphRAG(embedding_func=your_embed_func, embedding_batch_num=..., embedding_func_max_async=...)\n```\n\nYou can refer to an [example](./examples/using_local_embedding_model.py) that use `sentence-transformer` to locally compute embeddings.\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eStorage Component\u003c/summary\u003e\n\nYou can replace all storage-related components to your own implementation, `nano-graphrag` mainly uses three kinds of storage:\n\n**`base.BaseKVStorage` for storing key-json pairs of data** \n\n- By default we use disk file storage as the backend. \n- `GraphRAG(.., key_string_value_json_storage_cls=YOURS,...)`\n\n**`base.BaseVectorStorage` for indexing embeddings**\n\n- By default we use [`nano-vectordb`](https://github.com/gusye1234/nano-vectordb) as the backend.\n- We have a built-in [`hnswlib`](https://github.com/nmslib/hnswlib) storage also, check out this [example](./examples/using_hnsw_as_vectorDB.py).\n- Check out this [example](./examples/using_milvus_as_vectorDB.py) that implements [`milvus-lite`](https://github.com/milvus-io/milvus-lite) as the backend (not available in Windows).\n- `GraphRAG(.., vector_db_storage_cls=YOURS,...)`\n\n**`base.BaseGraphStorage` for storing knowledge graph**\n\n- By default we use [`networkx`](https://github.com/networkx/networkx) as the backend.\n- We have a built-in `Neo4jStorage` for graph, check out this [tutorial](./docs/use_neo4j_for_graphrag.md).\n- `GraphRAG(.., graph_storage_cls=YOURS,...)`\n\nYou can refer to `nano_graphrag.base` to see detailed interfaces for each components.\n\u003c/details\u003e\n\n\n\n## FQA\n\nCheck [FQA](./docs/FAQ.md).\n\n\n\n## Roadmap\n\nSee [ROADMAP.md](./docs/ROADMAP.md)\n\n\n\n## Contribute\n\n`nano-graphrag` is open to any kind of contribution. Read [this](./docs/CONTRIBUTING.md) before you contribute.\n\n\n\n\n## Benchmark\n\n- [benchmark for English](./docs/benchmark-en.md)\n- [benchmark for Chinese](./docs/benchmark-zh.md)\n- [An evaluation](./examples/benchmarks/eval_naive_graphrag_on_multi_hop.ipynb) notebook on a [multi-hop RAG task](https://github.com/yixuantt/MultiHop-RAG)\n\n\n\n## Projects that used `nano-graphrag`\n\n- [Medical Graph RAG](https://github.com/MedicineToken/Medical-Graph-RAG): Graph RAG for the Medical Data\n- [LightRAG](https://github.com/HKUDS/LightRAG): Simple and Fast Retrieval-Augmented Generation\n- [fast-graphrag](https://github.com/circlemind-ai/fast-graphrag): RAG that intelligently adapts to your use case, data, and queries\n- [HiRAG](https://github.com/hhy-huang/HiRAG): Retrieval-Augmented Generation with Hierarchical Knowledge\n\n\u003e Welcome to pull requests if your project uses `nano-graphrag`, it will help others to trust this repo❤️\n\n\n\n## Issues\n\n- `nano-graphrag` didn't implement the `covariates` feature of `GraphRAG`\n- `nano-graphrag` implements the global search different from the original. The original use a map-reduce-like style to fill all the communities into context, while `nano-graphrag` only use the top-K important and central communites (use `QueryParam.global_max_consider_community` to control, default to 512 communities).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgusye1234%2Fnano-graphrag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgusye1234%2Fnano-graphrag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgusye1234%2Fnano-graphrag/lists"}