How microsoft/graphrag works
1. Repository shape
- This is a Python monorepo centered on the graphrag package, with smaller reusable packages (graphrag-llm, graphrag-input, graphrag-storage, graphrag-vectors, graphrag-chunking, graphrag-cache, graphrag-common) and one consumer app (unified-search-app).
- The repo is organized around a GraphRAG pipeline: ingest documents, build graph-structured knowledge, persist intermediate/final artifacts, then query that knowledge with LLM-backed search modes.
2. Primary orchestration layer: packages/graphrag
- This is the main product package and CLI entrypoint.
- It owns the top-level APIs, command-line commands, configuration loading, logging, prompt tuning, indexing, querying, and data-model definitions.
- If you draw a diagram, this package is the hub connecting input, LLM, storage, vector retrieval, and query/search subsystems.
3. Input ingestion boundary
- graphrag-input handles reading source documents from multiple formats: text, CSV, JSON, JSONL, Parquet, and HTML/markitdown-based conversion.
- The core repo’s data_model package defines the canonical entities that move through the system: documents, text units, entities, relationships, communities, covariates, and reports.
- The input stage converts heterogeneous raw files into normalized document objects before indexing starts.
4. Indexing pipeline
- The indexing flow is implemented in graphrag/index using workflows and operations.
- Major phases include loading documents, splitting into text units, extracting graph structure, extracting covariates/claims, generating embeddings, clustering the graph into communities, summarizing communities, pruning/finalizing the graph, and writing snapshots.
- There is also explicit support for incremental updates, so indexing is not just a one-shot batch pipeline.
5. LLM and model execution layer
- graphrag-llm abstracts model access: completion, embedding, tokenization, templating, retries, rate limiting, caching, metrics, and threaded/batched execution.
- It uses provider adapters such as LiteLLM and mock implementations for testing.
- This package is the boundary between GraphRAG logic and external model APIs; all LLM/embedding calls pass through here rather than being embedded directly in business logic.
6. Graph extraction and summarization mechanics
- Within indexing, graph extraction is split into dedicated operations for noun-graph building, entity/relationship extraction, claim/covariate extraction, and summarization.
- Community summarization builds report artifacts from graph context and text-unit context.
- Prompt templates live under graphrag/prompts and graphrag/prompt_tune, so prompt assets are part of the architecture, not just configuration.
7. Storage and persistence
- graphrag-storage provides abstract storage plus concrete backends for file, memory, Azure Blob Storage, and Azure Cosmos DB.
- It also defines table abstractions and table providers for CSV, Parquet, and Cosmos-backed tables.
- The indexing pipeline persists its artifacts through these storage abstractions, which is why the system can run locally with files or scale to cloud storage.
8. Vector retrieval layer
- graphrag-vectors manages vector-store integrations, including LanceDB, Azure AI Search, and Cosmos DB.
- This layer is used for embedding-backed retrieval of text units and related content during query-time search.
- It forms the retrieval index boundary between generated embeddings and downstream search algorithms.
9. Query subsystem
- graphrag/query implements multiple search modes: basic search, local search, global search, and drift search.
- Query-time context builders assemble the inputs for each mode from stored graph artifacts, retrieved text units, community reports, and conversation/history context.
- There is a question-generation path as well, which suggests the system can both answer and generate follow-up questions.
10. Search data flow at query time
- Query processing generally flows from user question → retrieval/context builder → structured search strategy → LLM completion → response.
- Local search emphasizes nearby entities/text units, global search uses community-level summaries, and drift search tracks iterative state.
- The query/input/retrieval and query/context_builder directories show that retrieval and context assembly are first-class architectural stages.
11. Reusable support packages
- graphrag-chunking isolates sentence/token chunking strategies.
- graphrag-cache provides cache implementations and key generation for expensive operations.
- graphrag-common contains shared config loading, factory helpers, and hashing utilities used across packages.
- These packages reduce coupling so the core pipeline can swap implementations without changing orchestration code.
12. Unified search application
- unified-search-app is a separate downstream application that consumes GraphRAG outputs.
- It has its own app logic, UI components, state management, knowledge loading, and RAG-specific helpers.
- It appears to support multiple knowledge sources, including local files and blob-backed sources, and is packaged as a deployable container.
13. Docs, examples, and notebooks as part of the product surface
- The repository includes extensive docs, example notebooks, and fixture datasets for indexing and query scenarios.
- These are not just samples; they encode expected data shapes, pipeline stages, and output artifacts, which is useful when drawing the system boundary and lifecycle.
- The notebooks also demonstrate how consumers are expected to interact with each subsystem.
14. Testing and delivery model
- There is a broad test matrix: unit, integration, notebook, smoke, and verb-level tests, plus CI workflows for checks, publishing, and semantic versioning.
- The presence of cloud-specific integration tests for Azure storage and vector services indicates the architecture is designed to run in both local and managed cloud environments.
- A diagram should reflect that the repo is a platform/library stack with strong test coverage and multiple runtime backends, not a single deployable service.
Main entry points: run_pipeline.py Indexing · search.py Query engine · completion.py LLM runtime · storage.py Storage layer
Components 20
Core GraphRAG
Primary package that orchestrates indexing, querying, prompt tuning, and CLI entrypoints.
- CLI entry · Main entrypoint for the GraphRAG command-line surface.
packages/graphrag/graphrag/__main__.py - Public API · Top-level programmatic APIs for indexing, querying, and prompt tuning.
packages/graphrag/graphrag/api/index.py - Indexing · Coordinates document loading, graph extraction, embedding, clustering, summarization, pruning, and snapshots.
packages/graphrag/graphrag/index/run/run_pipeline.py - Query engine · Implements basic, local, global, drift, and question-generation search modes.
packages/graphrag/graphrag/query/structured_search/basic_search/search.py - Prompt tuning · Generates and manages prompts used by indexing and query workflows.
packages/graphrag/graphrag/prompt_tune/generator/extract_graph_prompt.py - Data model · Canonical entities and records that move through indexing and query flows.
packages/graphrag/graphrag/data_model/document.py - Context builders · Builds retrieval context from graph artifacts, text units, communities, and conversation state.
packages/graphrag/graphrag/query/context_builder/builders.py - Query retrieval · Loads stored entities, relationships, covariates, text units, and reports for search-time use.
packages/graphrag/graphrag/query/input/retrieval/text_units.py
Reusable Packages
Shared runtime packages for input normalization, model access, storage, retrieval, chunking, caching, and common helpers.
- Input readers · Normalizes text, CSV, JSON, JSONL, Parquet, and HTML inputs into documents.
packages/graphrag-input/graphrag_input/input_reader.py - LLM runtime · Completion, embedding, retries, rate limiting, caching, templating, metrics, and provider adapters.
packages/graphrag-llm/graphrag_llm/completion/completion.py - Storage layer · File, memory, Azure Blob, and Cosmos-backed storage plus table providers.
packages/graphrag-storage/graphrag_storage/storage.py - Vector store · Vector-store integrations for LanceDB, Azure AI Search, and Cosmos DB.
packages/graphrag-vectors/graphrag_vectors/vector_store.py - Chunking · Sentence and token chunking strategies used before extraction and embedding.
packages/graphrag-chunking/graphrag_chunking/chunker.py - Cache · Reusable cache implementations and cache-key generation for expensive operations.
packages/graphrag-cache/graphrag_cache/cache.py - Common utils · Shared config loading, factory helpers, and hashing utilities.
packages/graphrag-common/graphrag_common/config/load_config.py
Consumer App
Downstream unified search application built on GraphRAG outputs.
- Search app · Unified search application that consumes GraphRAG outputs.
unified-search-app/app/app_logic.py - Knowledge loader · Prepares local and blob-backed knowledge sources for the app.
unified-search-app/app/knowledge_loader/data_prep.py - App RAG · RAG-specific typing and helpers used by the consumer application.
unified-search-app/app/rag/typing.py - App state · Session and query state managed by the application UI.
unified-search-app/app/state/session_variables.py
Docs & CI
Documentation, notebooks, fixtures, tests, and automation that define and validate the platform.
- Docs & tests · Documentation, notebooks, fixtures, tests, and CI workflows that validate the platform.
README.md
Connections 31
- CLI entry → Public API: exposes · The CLI delegates into the public API surface.
- Public API → Indexing: runs · API calls launch indexing workflows.
- Public API → Query engine: runs · API calls launch query/search workflows.
- Public API → Prompt tuning: tunes · API exposes prompt tuning operations.
- Indexing → Input readers: loads · Indexing starts from normalized input documents.
- Indexing → Chunking: splits · Documents are chunked into text units before extraction.
- Indexing → LLM runtime: calls · Extraction, summarization, and embedding use the LLM boundary.
- Indexing → Storage layer: persists · Intermediate and final artifacts are written through storage abstractions.
- Indexing → Vector store: indexes · Embeddings are stored in vector backends for retrieval.
- Indexing → Data model: produces · Indexing materializes canonical graph and document entities.
- Indexing → Common utils: shares · Indexing reuses config, factory, and hashing helpers.
- Query engine → Context builders: builds · Search modes assemble structured context before generation.
- Query engine → Query retrieval: retrieves · Query execution loads graph artifacts and text units.
- Query engine → LLM runtime: generates · Final answers and question generation use model calls.
- Query engine → Storage layer: reads · Querying consumes persisted index artifacts.
- Query engine → Vector store: searches · Embedding-backed retrieval supports local and related search flows.
- Prompt tuning → LLM runtime: proposes · Prompt tuning depends on model execution and templating support.
- Prompt tuning → Common utils: loads · Prompt assets are loaded via shared helpers.
- Input readers → Data model: normalizes · Readers convert heterogeneous files into canonical document objects.
- LLM runtime → Cache: caches · Model calls can be wrapped with caching middleware.
- LLM runtime → Common utils: configures · Shared utilities help configure model factories and hashing.
- Storage layer → Common utils: builds · Storage backends reuse shared config and factory helpers.
- Vector store → Storage layer: depends on · Vector integrations rely on persisted tables and storage patterns.
- Search app → Knowledge loader: loads · The app prepares knowledge sources before interaction.
- Search app → App RAG: uses · Application logic depends on RAG helpers and types.
- Search app → App state: tracks · User interaction is coordinated through session state.
- Knowledge loader → Storage layer: reads · Knowledge sources can be file- or blob-backed.
- Knowledge loader → Vector store: consumes · Loaded knowledge can include vector-backed artifacts.
- Docs & tests → Indexing: exercises · Docs, notebooks, and tests demonstrate indexing behavior.
- Docs & tests → Query engine: exercises · Query notebooks and tests document search modes.
- Docs & tests → LLM runtime: verifies · Integration and notebook tests cover model execution behavior.