GraphRAG

https://microsoft.github.io/graphrag
Admin
GraphRAG is a structured, hierarchical approach to unlocking LLM discovery on narrative private...
Tokens:25,335
Snippets:383
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start Azurite for Local Azure Emulation

Source: https://microsoft.github.io/graphrag/developing

Starts the Azurite service, which emulates Azure storage resources for local development and testing. This script is part of the local development setup.

```bash
./scripts/start-azurite.sh
```

--------------------------------

### Install Python Dependencies with uv

Source: https://microsoft.github.io/graphrag/developing

Installs all necessary Python packages for the project using uv. Ensure uv is installed and configured.

```bash
uv sync --all-packages
```

--------------------------------

### Configure LLM

Source: https://microsoft.github.io/graphrag/examples_notebooks/global_search

Setup the model configuration and tokenizer using environment variables.

```python
api_key = os.environ["GRAPHRAG_API_KEY"]

config = ModelConfig(
    type="litellm",
    model_provider="openai",
    model="gpt-4.1",
    api_key=api_key,
)
model = create_completion(config)

tokenizer = get_tokenizer(config)

```

--------------------------------

### Install GraphRAG

Source: https://microsoft.github.io/graphrag/get_started

Installs the GraphRAG library using pip within your activated virtual environment.

```bash
python -m pip install graphrag
```

--------------------------------

### Install LLVM and Configure llvm-config for uv

Source: https://microsoft.github.io/graphrag/developing

Troubleshoots the 'RuntimeError: llvm-config failed executing' error when running `uv install`. Installs LLVM 9 and sets the LLVM_CONFIG environment variable.

```bash
sudo apt-get install llvm-9 llvm-9-dev
```

```bash
export LLVM_CONFIG=/usr/bin/llvm-config-9
```

--------------------------------

### CSV Source Data Example

Source: https://microsoft.github.io/graphrag/index/inputs

Example content for a software.csv file used as a data source.

```csv
text,title,tag
My first program,Hello World,tutorial
An early space shooter game,Space Invaders,arcade
```

--------------------------------

### Graphrag CLI Options

Source: https://microsoft.github.io/graphrag/cli

Global options for the graphrag CLI, such as installing shell completions.

```bash
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or
                        customize the installation.
```

--------------------------------

### Install SpaCy Models

Source: https://microsoft.github.io/graphrag/index/methods

Manually installs required SpaCy models for FastGraphRAG functionality.

```bash
python -m spacy download <model_name>
```

```bash
python -m spacy download en_core_web_md
```

--------------------------------

### Handle LocalSearch Initialization Errors

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Example of a NameError traceback occurring when required components like context_builder are not defined before initialization.

```python
search_engine = LocalSearch( model=chat_model, context_builder=context_builder, tokenizer=tokenizer, model_params=model_params, context_builder_params=local_context_params, response_type="multiple paragraphs", # free form text describing the response type and format, can be anything, e.g. prioritized list, single paragraph, multiple paragraphs, multiple-page report )
```
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[12], line 3
      1 search_engine = LocalSearch(
      2     model=chat_model,
----> 3     context_builder=context_builder,
      4     tokenizer=tokenizer,
      5     model_params=model_params,
      6     context_builder_params=local_context_params,

NameError: name 'context_builder' is not defined
```

--------------------------------

### Define JSON input structure

Source: https://microsoft.github.io/graphrag/index/inputs

Example of a JSON file containing headline and content fields for ingestion.

```json
{
    "headline": "NY lawmakers begin debating budget 1 month after due date",
    "content": "ALBANY, N.Y. (AP) New York lawmakers began voting Monday on a $229 billion state budget due a month ago that would raise the minimum wage, crack down on illicit pot shops and ban gas stoves and furnaces in new buildings. Negotiations among Gov. Kathy Hochul and her fellow Democrats in control of the Legislature dragged on past the April 1 budget deadline, largely because of disagreements over changes to the bail law and other policy proposals included in the spending plan. Floor debates on some budget bills began Monday. State Senate Majority Leader Andrea Stewart-Cousins said she expected voting to be wrapped up Tuesday for a budget she said contains \"significant wins\" for New Yorkers. \"I would have liked to have done this sooner. I think we would all agree to that,\" Cousins told reporters before voting began. \"This has been a very policy-laden budget and a lot of the policies had to parsed through.\" Hochul was able to push through a change to the bail law that will eliminate the standard that requires judges to prescribe the \"least restrictive\" means to ensure defendants return to court. Hochul said judges needed the extra discretion. Some liberal lawmakers argued that it would undercut the sweeping bail reforms approved in 2019 and result in more people with low incomes and people of color in pretrial detention. Here are some other policy provisions that will be included in the budget, according to state officials. The minimum wage would be raised to $17 in New York City and some of its suburbs and $16 in the rest of the state by 2026. That's up from $15 in the city and $14.20 upstate."
}
```

--------------------------------

### Configure Azure OpenAI Chat Model

Source: https://microsoft.github.io/graphrag/get_started

Example configuration for using Azure OpenAI as the chat model provider, including deployment name and API base.

```yaml
type: chat
model_provider: azure
model: gpt-4.1
azure_deployment_name: <AZURE_DEPLOYMENT_NAME>
api_base: https://<instance>.openai.azure.com
api_version: 2024-02-15-preview # You can customize this for other versions
```

--------------------------------

### Configure Vector Store Settings

Source: https://microsoft.github.io/graphrag/config/yaml

Example configuration for a LanceDB vector store with custom index schema definitions for specific embedding types.

```yaml
vector_store:
  type: lancedb
  db_uri: output/lancedb
  index_schema:
    text_unit_text:
      index_name: "text-unit-embeddings"
      id_field: "id_custom"
      vector_field: "vector_custom"
      vector_size: 3072
    entity_description:
      id_field: "id_custom"
```

--------------------------------

### Index Data with GraphRAG

Source: https://microsoft.github.io/graphrag/get_started

Starts the GraphRAG indexing process to process text files in the input directory and generate output files.

```bash
graphrag index
```

--------------------------------

### Initialize GraphRAG Configuration

Source: https://microsoft.github.io/graphrag/config/init

Use the 'init' command to create default .env and settings.yaml files. Specify a root directory with --root PATH. Use --force to overwrite existing files.

```bash
graphrag init [--root PATH] [--force, --no-force]
```

```bash
graphrag init --root ./ragtest
```

--------------------------------

### Initialize DRIFTSearch Components

Source: https://microsoft.github.io/graphrag/examples_notebooks/drift_search

Configures the search parameters and builds the context required for the DRIFTSearch engine.

```python
drift_params = DRIFTSearchConfig(
    primer_folds=1,
    drift_k_followups=3,
    n_depth=3,
)

context_builder = DRIFTSearchContextBuilder(
    model=chat_model,
    text_embedder=text_embedder,
    entities=entities,
    relationships=relationships,
    reports=reports,
    entity_text_embeddings=description_embedding_store,
    text_units=text_units,
    tokenizer=tokenizer,
    config=drift_params,
)

search = DRIFTSearch(
    model=chat_model, context_builder=context_builder, tokenizer=tokenizer
)
```

--------------------------------

### CLI Command: init

Source: https://microsoft.github.io/graphrag/cli

Generates a default configuration file for a new GraphRAG project.

```APIDOC
## init

### Description
Generate a default configuration file.

### Options
- **-r, --root** (DIRECTORY) - Optional - The project root directory. Default: /home/runner/work/graphrag/graphrag
- **-m, --model** (TEXT) - Optional - The model to use. Default: gpt-4.1
- **-e, --embedding** (TEXT) - Optional - The embedding model to use. Default: text-embedding-3-large
- **-f, --force** (flag) - Optional - Force initialization even if the project already exists.
```

--------------------------------

### Graphrag Init Command Options

Source: https://microsoft.github.io/graphrag/cli

Options for the 'init' command, such as specifying the project root, model, and embedding model. Use '--force' to overwrite existing configurations.

```bash
  -r, --root DIRECTORY  The project root directory.  [default:
                        /home/runner/work/graphrag/graphrag]
  -m, --model TEXT      [default: gpt-4.1]
  -e, --embedding TEXT  [default: text-embedding-3-large]
  -f, --force           Force initialization even if the project already
                        exists.
```

--------------------------------

### Initialize LLM and embedding models

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Configures and creates completion and embedding models along with a tokenizer for local search tasks.

```python
from graphrag.tokenizer.get_tokenizer import get_tokenizer
from graphrag_llm.completion import create_completion
from graphrag_llm.config import ModelConfig
from graphrag_llm.embedding import create_embedding

api_key = os.environ["GRAPHRAG_API_KEY"]

chat_config = ModelConfig(
    type="litellm",
    model_provider="openai",
    model="gpt-4.1",
    api_key=api_key,
)
chat_model = create_completion(chat_config)

embedding_config = ModelConfig(
    type="litellm",
    model_provider="openai",
    model="text-embedding-3-small",
    api_key=api_key,
)

text_embedder = create_embedding(embedding_config)

tokenizer = get_tokenizer(chat_config)
```

--------------------------------

### Run Prompt Tuning via CLI

Source: https://microsoft.github.io/graphrag/prompt_tuning/auto_prompt_tuning

Execute the prompt tuning script using command-line arguments to configure domain, selection methods, and token limits.

```bash
graphrag prompt-tune [--root ROOT] [--domain DOMAIN]  [--selection-method METHOD] [--limit LIMIT] [--language LANGUAGE] \
[--max-tokens MAX_TOKENS] [--chunk-size CHUNK_SIZE] [--n-subset-max N_SUBSET_MAX] [--k K] \
[--min-examples-required MIN_EXAMPLES_REQUIRED] [--discover-entity-types] [--output OUTPUT]
```

```bash
python -m graphrag prompt-tune --root /path/to/project --domain "environmental news" \
--selection-method random --limit 10 --language English --max-tokens 2048 --chunk-size 256 --min-examples-required 3 \
--no-discover-entity-types --output /path/to/output
```

```bash
python -m graphrag prompt-tune --root /path/to/project --no-discover-entity-types
```

--------------------------------

### CLI Command: index

Source: https://microsoft.github.io/graphrag/cli

Builds a knowledge graph index using the specified configuration and methods.

```APIDOC
## index

### Description
Build a knowledge graph index.

### Options
- **-r, --root** (DIRECTORY) - Optional - The project root directory. Default: /home/runner/work/graphrag/graphrag
- **-m, --method** (standard|fast|standard-update|fast-update) - Optional - The indexing method to use. Default: standard
- **-v, --verbose** (flag) - Optional - Run the indexing pipeline with verbose logging
- **--dry-run** (flag) - Optional - Run the indexing pipeline without executing any steps to inspect and validate the configuration.
- **--cache / --no-cache** (flag) - Optional - Use LLM cache. Default: cache
- **--skip-validation** (flag) - Optional - Skip any preflight validation.
```

--------------------------------

### Define JSON article structure

Source: https://microsoft.github.io/graphrag/index/inputs

Example of a single article formatted as a JSON object with headline and content fields.

```json
{
    "headline": "US to lift most federal COVID-19 vaccine mandates",
    "content": "WASHINGTON (AP) The Biden administration will end most of the last remaining federal COVID-19 vaccine requirements next week when the national public health emergency for the coronavirus ends, the White House said Monday. Vaccine requirements for federal workers and federal contractors, as well as foreign air travelers to the U.S., will end May 11. The government is also beginning the process of lifting shot requirements for Head Start educators, healthcare workers, and noncitizens at U.S. land borders. The requirements are among the last vestiges of some of the more coercive measures taken by the federal government to promote vaccination as the deadly virus raged, and their end marks the latest display of how President Joe Biden's administration is moving to treat COVID-19 as a routine, endemic illness. \"While I believe that these vaccine mandates had a tremendous beneficial impact, we are now at a point where we think that it makes a lot of sense to pull these requirements down,\" White House COVID-19 coordinator Dr. Ashish Jha told The Associated Press on Monday."
}
```

--------------------------------

### Load GraphRAG Configuration

Source: https://microsoft.github.io/graphrag/examples_notebooks/api_overview

Initializes the configuration by pointing to a directory containing settings.yaml. Ensure the PROJECT_DIRECTORY variable is set to a valid path to avoid FileNotFoundError.

```python
# note that we expect this to fail on the deployed docs because the PROJECT_DIRECTORY is not set to a real location.
# if you run this notebook locally, make sure to point at a location containing your settings.yaml
graphrag_config = load_config(Path(PROJECT_DIRECTORY))
```

--------------------------------

### Initialize GlobalCommunityContext

Source: https://microsoft.github.io/graphrag/examples_notebooks/global_search

Configures the context builder with reports, communities, entities, and a tokenizer for global search.

```python
context_builder = GlobalCommunityContext(
    community_reports=reports,
    communities=communities,
    entities=entities,  # default to None if you don't want to use community weights for ranking
    tokenizer=tokenizer,
)
```

--------------------------------

### Initialize GraphRAG Workspace

Source: https://microsoft.github.io/graphrag/get_started

Initializes the GraphRAG workspace, creating configuration files (.env, settings.yaml) and an input directory.

```bash
graphrag init
```

--------------------------------

### Enable GraphML Snapshots in settings.yaml

Source: https://microsoft.github.io/graphrag/visualization_guide

Configure the indexing pipeline to generate GraphML files for visualization.

```yaml
snapshots:
  graphml: true

```

--------------------------------

### Initialize LocalSearch Engine

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Instantiate the LocalSearch class with the required model, tokenizer, and context builder parameters.

```python
search_engine = LocalSearch(
    model=chat_model,
    context_builder=context_builder,
    tokenizer=tokenizer,
    model_params=model_params,
    context_builder_params=local_context_params,
    response_type="multiple paragraphs",  # free form text describing the response type and format, can be anything, e.g. prioritized list, single paragraph, multiple paragraphs, multiple-page report
)
```

--------------------------------

### Configure LLM and Embedding Models

Source: https://microsoft.github.io/graphrag/examples_notebooks/drift_search

Initializes the chat completion and text embedding models using environment variables and configuration objects.

```python
api_key = os.environ["GRAPHRAG_API_KEY"]

chat_config = ModelConfig(
    type="litellm",
    model_provider="openai",
    model="gpt-4.1",
    api_key=api_key,
)
chat_model = create_completion(chat_config)

tokenizer = get_tokenizer(chat_config)

embedding_config = ModelConfig(
    type="litellm",
    model_provider="openai",
    model="text-embedding-3-large",
    api_key=api_key,
)

text_embedder = create_embedding(embedding_config)
```

--------------------------------

### Configure Environment Variables and YAML Settings

Source: https://microsoft.github.io/graphrag/config/yaml

Use a .env file to define variables and reference them in settings.yml using ${ENV_VAR} syntax.

```yaml
# .env
GRAPHRAG_API_KEY=some_api_key

# settings.yml
default_chat_model:
  api_key: ${GRAPHRAG_API_KEY}
```

--------------------------------

### Initialize GlobalSearch Engine

Source: https://microsoft.github.io/graphrag/examples_notebooks/global_search

Instantiate the GlobalSearch class with the previously defined parameters and model components.

```python
search_engine = GlobalSearch(
    model=model,
    context_builder=context_builder,
    tokenizer=tokenizer,
    max_data_tokens=12_000,  # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 5000)
    map_llm_params=dict(map_llm_params),
    reduce_llm_params=dict(reduce_llm_params),
    allow_general_knowledge=False,  # set this to True will add instruction to encourage the LLM to incorporate general knowledge in the response, which may increase hallucinations, but could be useful in some use cases.
    json_mode=False,
    context_builder_params=context_builder_params,
    concurrent_coroutines=32,
    response_type="multiple paragraphs",  # free form text describing the response type and format, can be anything, e.g. prioritized list, single paragraph, multiple paragraphs, multiple-page report
)
```

--------------------------------

### Graphrag Init Command Usage

Source: https://microsoft.github.io/graphrag/cli

Generate a default configuration file for graphrag using the 'init' command.

```bash
 init [OPTIONS]
```

--------------------------------

### Define Input Paths and Parameters

Source: https://microsoft.github.io/graphrag/examples_notebooks/global_search

Set the input directory and table names for loading GraphRAG parquet files.

```python
# parquet files generated from indexing pipeline
INPUT_DIR = "./inputs/operation dulce"
COMMUNITY_TABLE = "communities"
COMMUNITY_REPORT_TABLE = "community_reports"
ENTITY_TABLE = "entities"

# community level in the Leiden community hierarchy from which we will load the community reports
# higher value means we use reports from more fine-grained communities (at the cost of higher computation cost)
COMMUNITY_LEVEL = 2

```

--------------------------------

### Download Sample Text Data

Source: https://microsoft.github.io/graphrag/get_started

Downloads a sample text file ('A Christmas Carol') and saves it to the input directory for processing.

```bash
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt
```

--------------------------------

### Initialize LocalSearchMixedContext

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Configures the context builder for local search using community reports, text units, entities, and relationships.

```python
context_builder = LocalSearchMixedContext(
    community_reports=reports,
    text_units=text_units,
    entities=entities,
    relationships=relationships,
    # if you did not run covariates during indexing, set this to None
    covariates=covariates,
    entity_text_embeddings=description_embedding_store,
    embedding_vectorstore_key=EntityVectorStoreKey.ID,  # if the vectorstore uses entity title as ids, set this to EntityVectorStoreKey.TITLE
    text_embedder=text_embedder,
    tokenizer=tokenizer,
)
```

--------------------------------

### Configure Global Search Parameters

Source: https://microsoft.github.io/graphrag/examples_notebooks/global_search

Define the dictionary parameters for context building, map LLM, and reduce LLM settings required for the global search engine.

```python
context_builder_params = {
    "use_community_summary": False,  # False means using full community reports. True means using community short summaries.
    "shuffle_data": True,
    "include_community_rank": True,
    "min_community_rank": 0,
    "community_rank_name": "rank",
    "include_community_weight": True,
    "community_weight_name": "occurrence weight",
    "normalize_community_weight": True,
    "max_tokens": 12_000,  # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 5000)
    "context_name": "Reports",
}

map_llm_params = {
    "max_tokens": 1000,
    "temperature": 0.0,
}

reduce_llm_params = {
    "max_tokens": 2000,  # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 1000-1500)
    "temperature": 0.0,
}
```

--------------------------------

### Load GraphRAG Configuration

Source: https://microsoft.github.io/graphrag/examples_notebooks/api_overview

Instantiates a GraphRagConfig object from the specified project directory. Ensure the directory contains a valid settings.yaml file.

```python
# note that we expect this to fail on the deployed docs because the PROJECT_DIRECTORY is not set to a real location.
# if you run this notebook locally, make sure to point at a location containing your settings.yaml
graphrag_config = load_config(Path(PROJECT_DIRECTORY))

```

--------------------------------

### Create Project Space and Virtual Environment

Source: https://microsoft.github.io/graphrag/get_started

Sets up a new directory for your GraphRAG project and creates a Python virtual environment.

```bash
mkdir graphrag_quickstart
cd graphrag_quickstart
python -m venv .venv
```

--------------------------------

### Chunking Configuration for Metadata Prepending

Source: https://microsoft.github.io/graphrag/index/inputs

YAML configuration to enable metadata prepending for specific fields.

```yaml
chunking:
    prepend_metadata: [title,tag]
```

--------------------------------

### Define Input Directories and Table Names

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Sets the base directory and table names for loading indexed parquet files.

```python
INPUT_DIR = "./inputs/operation dulce"
LANCEDB_URI = f"{INPUT_DIR}/lancedb"

COMMUNITY_REPORT_TABLE = "community_reports"
ENTITY_TABLE = "entities"
COMMUNITY_TABLE = "communities"
RELATIONSHIP_TABLE = "relationships"
COVARIATE_TABLE = "covariates"
TEXT_UNIT_TABLE = "text_units"
COMMUNITY_LEVEL = 2
```

--------------------------------

### Configure Minimal Workflows for Global Search

Source: https://microsoft.github.io/graphrag/index/byog

Use this configuration in settings.yaml to perform only the essential graph summarization and community report generation.

```yaml
workflows: [create_communities, create_community_reports]
```

--------------------------------

### Configure Local Search Parameters

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Define the dictionary for local context and model parameters to control token limits, entity retrieval, and context window composition.

```python
local_context_params = { "text_unit_prop": 0.5, "community_prop": 0.1, "conversation_history_max_turns": 5, "conversation_history_user_turns_only": True, "top_k_mapped_entities": 10, "top_k_relationships": 10, "include_entity_rank": True, "include_relationship_weight": True, "include_community_rank": False, "return_candidate_context": False, "embedding_vectorstore_key": EntityVectorStoreKey.ID, # set this to EntityVectorStoreKey.TITLE if the vectorstore uses entity title as ids "max_tokens": 12_000, # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 5000) } model_params = { "max_tokens": 2_000, # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 1000=1500) "temperature": 0.0, }
```

--------------------------------

### Graphrag CLI Usage

Source: https://microsoft.github.io/graphrag/cli

The main entry point for the graphrag CLI. Use this to access subcommands like 'index', 'init', and 'prompt-tune'.

```bash
 graphrag
 [OPTIONS] COMMAND [ARGS]...
```

--------------------------------

### Read Entities and Initialize Vector Store

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Loads entity and community data from parquet files and initializes the LanceDB vector store for entity descriptions.

```python
# read nodes table to get community and degree data
entity_df = pd.read_parquet(f"{INPUT_DIR}/{ENTITY_TABLE}.parquet")
community_df = pd.read_parquet(f"{INPUT_DIR}/{COMMUNITY_TABLE}.parquet")

entities = read_indexer_entities(entity_df, community_df, COMMUNITY_LEVEL)

# load description embeddings to an in-memory lancedb vectorstore
# to connect to a remote db, specify url and port values.
description_embedding_store = LanceDBVectorStore(
    index_schema=IndexSchema(index_name="default-entity-description")
)
description_embedding_store.connect(db_uri=LANCEDB_URI)

print(f"Entity count: {len(entity_df)}")
entity_df.head()
```

--------------------------------

### Execute Global Search Query

Source: https://microsoft.github.io/graphrag/examples_notebooks/global_search

Perform an asynchronous search query using the initialized search engine and print the resulting response.

```python
result = await search_engine.search("What is operation dulce?")

print(result.response)
```

--------------------------------

### Initialize LocalQuestionGen

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Instantiates the LocalQuestionGen class with required model, tokenizer, and context builder parameters.

```python
question_generator = LocalQuestionGen(
    model=chat_model,
    context_builder=context_builder,
    tokenizer=tokenizer,
    model_params=model_params,
    context_builder_params=local_context_params,
)
```

--------------------------------

### Configure input settings

Source: https://microsoft.github.io/graphrag/index/inputs

YAML configuration for defining input type, column mapping, and chunking parameters.

```yaml
input:
    type: json
    title_column: headline
    text_column: content

chunks:
    size: 100
    overlap: 10
```

--------------------------------

### Execute local search queries

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Perform a search query using the search engine instance and print the response.

```python
result = await search_engine.search("Tell me about Agent Mercer")
print(result.response)
```

```python
question = "Tell me about Dr. Jordan Hayes"
result = await search_engine.search(question)
print(result.response)
```

--------------------------------

### Registering a Custom Completion Model

Source: https://microsoft.github.io/graphrag/config/models

Implement the LLMCompletion protocol and register the class using the register_completion factory.

```python
from graphrag_llm.completion import LLMCompletion, register_completion

class MyCustomCompletionModel(LLMCompletion):
    ...
    # implementation

# elsewhere...
register_completion("my-custom-completion-model", MyCustomCompletionModel)
```

--------------------------------

### Generate Candidate Questions

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Uses the agenerate method to produce a list of candidate questions based on a history of previous queries.

```python
question_history = [
    "Tell me about Agent Mercer",
    "What happens in Dulce military base?",
]
candidate_questions = await question_generator.agenerate(
    question_history=question_history, context_data=None, question_count=5
)
print(candidate_questions.response)
```

--------------------------------

### Run Standard GraphRAG Indexing

Source: https://microsoft.github.io/graphrag/index/methods

Executes the default indexing pipeline using LLM-based reasoning.

```bash
graphrag index --method standard
```

--------------------------------

### Run GraphRAG Indexing via CLI

Source: https://microsoft.github.io/graphrag/index/overview

Executes the indexing pipeline using the default configuration mode.

```bash
uv run poe index --root <data_root> # default config mode
```

--------------------------------

### Graphrag Index Command Options

Source: https://microsoft.github.io/graphrag/cli

Options for the 'index' command, including specifying the project root, indexing method, and logging verbosity.

```bash
  -r, --root DIRECTORY            The project root directory.  [default:
                                  /home/runner/work/graphrag/graphrag]
  -m, --method [standard|fast|standard-update|fast-update]
                                  The indexing method to use.  [default:
                                  standard]
  -v, --verbose                   Run the indexing pipeline with verbose
                                  logging
  --dry-run                       Run the indexing pipeline without executing
                                  any steps to inspect and validate the
                                  configuration.
  --cache / --no-cache            Use LLM cache.  [default: cache]
  --skip-validation               Skip any preflight validation. Useful when
                                  running no LLM steps.
```

--------------------------------

### Import Dependencies

Source: https://microsoft.github.io/graphrag/examples_notebooks/drift_search

Imports necessary modules for DRIFT search configuration, data adapters, and vector storage.

```python
import os

import pandas as pd
from graphrag.config.models.drift_search_config import DRIFTSearchConfig
from graphrag.query.indexer_adapters import (
    read_indexer_entities,
    read_indexer_relationships,
    read_indexer_reports,
    read_indexer_text_units,
)
from graphrag.query.structured_search.drift_search.drift_context import (
    DRIFTSearchContextBuilder,
)
from graphrag.query.structured_search.drift_search.search import DRIFTSearch
from graphrag.tokenizer.get_tokenizer import get_tokenizer
from graphrag_llm.completion import create_completion
from graphrag_llm.config import ModelConfig
from graphrag_llm.embedding import create_embedding
from graphrag_vectors import IndexSchema, LanceDBVectorStore
```

--------------------------------

### Load Entity and Community Data

Source: https://microsoft.github.io/graphrag/examples_notebooks/local_search

Reads entity and community tables from Parquet files and initializes the vector store for entity descriptions.

```python
entity_df = pd.read_parquet(f"{INPUT_DIR}/{ENTITY_TABLE}.parquet")
community_df = pd.read_parquet(f"{INPUT_DIR}/{COMMUNITY_TABLE}.parquet")
entities = read_indexer_entities(entity_df, community_df, COMMUNITY_LEVEL)

# load description embeddings to an in-memory lancedb vectorstore
# to connect to a remote db, specify url and port values.
description_embedding_store = LanceDBVectorStore(
    index_schema=IndexSchema(index_name="default-entity-description")
)
description_embedding_store.connect(db_uri=LANCEDB_URI)
print(f"Entity count: {len(entity_df)}")
entity_df.head()
```

--------------------------------

### Define Project Directory

Source: https://microsoft.github.io/graphrag/examples_notebooks/api_overview

Placeholder variable for the target project directory path.

```python
PROJECT_DIRECTORY = "<your project directory>"

```

--------------------------------

### Copyright Header

Source: https://microsoft.github.io/graphrag/examples_notebooks/drift_search

Standard license header for the source file.

```python
# Copyright (c) 2024 Microsoft Corporation.
# Licensed under the MIT License.
```

--------------------------------

### Inspect query context

Source: https://microsoft.github.io/graphrag/examples_notebooks/api_overview

Uses pprint to display granular metadata about the data sources and text chunks used in the query.

```python
pprint(context)  # noqa: T203
```

--------------------------------

### Execute GraphRAG Indexing

Source: https://microsoft.github.io/graphrag/index/byog

Run the indexing command after placing your parquet files in the output folder and updating the configuration.

```bash
graphrag index --root <your_project_root>
```

--------------------------------

### Load Indexer Data and Connect Vector Store

Source: https://microsoft.github.io/graphrag/examples_notebooks/drift_search

Reads parquet files from the input directory and connects to the LanceDB vector store for entity descriptions.

```python
# parquet files generated from indexing pipeline
INPUT_DIR = "./inputs/operation dulce"
LANCEDB_URI = "./lancedb"
COMMUNITY_TABLE = "communities"
COMMUNITY_REPORT_TABLE = "community_reports"
ENTITY_TABLE = "entities"
RELATIONSHIP_TABLE = "relationships"
TEXT_UNIT_TABLE = "text_units"
COMMUNITY_LEVEL = 2

community_df = pd.read_parquet(f"{INPUT_DIR}/{COMMUNITY_TABLE}.parquet")
report_df = pd.read_parquet(f"{INPUT_DIR}/{COMMUNITY_REPORT_TABLE}.parquet")
entity_df = pd.read_parquet(f"{INPUT_DIR}/{ENTITY_TABLE}.parquet")
relationship_df = pd.read_parquet(f"{INPUT_DIR}/{RELATIONSHIP_TABLE}.parquet")
text_unit_df = pd.read_parquet(f"{INPUT_DIR}/{TEXT_UNIT_TABLE}.parquet")

reports = read_indexer_reports(report_df, community_df, COMMUNITY_LEVEL)
entities = read_indexer_entities(entity_df, community_df, COMMUNITY_LEVEL)
relationships = read_indexer_relationships(relationship_df)
text_units = read_indexer_text_units(text_unit_df)

# Connect to the existing GraphRAG vector index for entity-description embeddings.
description_embedding_store = LanceDBVectorStore(
    index_schema=IndexSchema(index_name="default-entity-description")
)
description_embedding_store.connect(db_uri=LANCEDB_URI)

print(
    f"Loaded reports={len(reports)}, entities={len(entities)}, relationships={len(relationships)}, text_units={len(text_units)}"
)
```

--------------------------------

### Update Configuration for Generated Prompts

Source: https://microsoft.github.io/graphrag/prompt_tuning/auto_prompt_tuning

Update the settings.yaml file to point to the newly generated prompt files after running the tuning process.

```yaml
extract_graph:
  prompt: "prompts/extract_graph.txt"

summarize_descriptions:
  prompt: "prompts/summarize_descriptions.txt"

community_reports:
  prompt: "prompts/community_report.txt"
```

--------------------------------

### Graphrag Index Command Usage

Source: https://microsoft.github.io/graphrag/cli

Build a knowledge graph index using the 'index' command. Specify options to control the indexing process.

```bash
 index [OPTIONS]
```

--------------------------------

### Activate Python Virtual Environment - Windows

Source: https://microsoft.github.io/graphrag/get_started

Activates the Python virtual environment on Windows systems.

```bash
.venv\Scripts\activate
```

--------------------------------

### Import Dependencies

Source: https://microsoft.github.io/graphrag/examples_notebooks/global_search

Required imports for data loading, context management, and LLM interaction.

```python
import os

import pandas as pd
from graphrag.query.indexer_adapters import (
    read_indexer_communities,
    read_indexer_entities,
    read_indexer_reports,
)
from graphrag.query.structured_search.global_search.community_context import (
    GlobalCommunityContext,
)
from graphrag.query.structured_search.global_search.search import GlobalSearch
from graphrag.tokenizer.get_tokenizer import get_tokenizer
from graphrag_llm.completion import create_completion
from graphrag_llm.config import ModelConfig

```

--------------------------------

### CLI Command: prompt-tune

Source: https://microsoft.github.io/graphrag/cli

Generates custom GraphRAG prompts using auto-templating based on provided data.

```APIDOC
## prompt-tune

### Description
Generate custom graphrag prompts with your own data (i.e. auto templating).

### Options
- **-r, --root** (DIRECTORY) - Optional - The project root directory.
- **-v, --verbose** (flag) - Optional - Run the prompt tuning pipeline with verbose logging.
- **--domain** (TEXT) - Optional - The domain your input data is related to.
- **--selection-method** (all|random|top|auto) - Optional - The text chunk selection method. Default: random
- **--n-subset-max** (INTEGER) - Optional - The number of text chunks to embed when --selection-method=auto. Default: 300
- **--k** (INTEGER) - Optional - The maximum number of documents to select from each centroid. Default: 15
- **--limit** (INTEGER) - Optional - The number of documents to load. Default: 15
- **--max-tokens** (INTEGER) - Optional - The max token count for prompt generation. Default: 2000
- **--min-examples-required** (INTEGER) - Optional - The minimum number of examples to generate/include. Default: 2
- **--chunk-size** (INTEGER) - Optional - The size of each example text chunk. Default: 1200
- **--overlap** (INTEGER) - Optional - The overlap size for chunking documents. Default: 100
- **--language** (TEXT) - Optional - The primary language used for inputs and outputs.
- **--discover-entity-types / --no-discover-entity-types** (flag) - Optional - Discover and extract unspecified entity types.
- **-o, --output** (PATH) - Optional - The directory to save prompts to. Default: prompts
```

--------------------------------

### Configure Asymmetric Model Usage

Source: https://microsoft.github.io/graphrag/config/models

Define multiple models in the settings.yaml file to assign different models to specific indexing and query workflows.

```yaml
completion_models:
  extraction_completion_model:
    model_provider: openai
    model: gpt-4o
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}
  query_completion_model:
    model_provider: openai
    model: o1
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}
...
extract_graph:
  completion_model_id: extraction_completion_model
  prompt: "prompts/extract_graph.txt"
  entity_types: [organization, person, geo, event]
  max_gleanings: 1
...
global_search:
  completion_model_id: query_completion_model
  map_prompt: "prompts/global_search_map_system_prompt.txt"
  reduce_prompt: "prompts/global_search_reduce_system_prompt.txt"
  knowledge_prompt: "prompts/global_search_knowledge_system_prompt.txt"
```

--------------------------------

### Build a GraphRAG index

Source: https://microsoft.github.io/graphrag/examples_notebooks/api_overview

Executes the indexing pipeline using a provided configuration. The result is a list of pipeline workflow results that can be iterated to check for success or errors.

```python
index_result: list[PipelineRunResult] = await api.build_index(config=graphrag_config)

# index_result is a list of workflows that make up the indexing pipeline that was run
for workflow_result in index_result:
    status = f"error\n{workflow_result.errors}" if workflow_result.errors else "success"
    print(f"Workflow Name: {workflow_result.workflow}\tStatus: {status}")
```

--------------------------------

### Execute DRIFTSearch Query

Source: https://microsoft.github.io/graphrag/examples_notebooks/drift_search

Performs an asynchronous search query using the initialized DRIFTSearch instance.

```python
resp = await search.search("Who is agent Mercer?")
```

--------------------------------

### Configure Workflows for FastGraphRAG

Source: https://microsoft.github.io/graphrag/index/byog

Use the text-based community reports workflow when entity and relationship descriptions are unavailable.

```yaml
workflows: [create_communities, create_community_reports_text, generate_text_embeddings]
```

--------------------------------

### Execute Graphrag Indexing Engine

Source: https://microsoft.github.io/graphrag/developing

Runs the indexing process for Graphrag using uv and poe. Replace <...args> with specific indexing parameters.

```bash
uv run poe index <...args>
```
Tokens:
Raw