Skip to main content
GraphRAG can be configured using a settings.yaml or settings.json file in your project root. This page documents all available configuration options.

​
Environment variable substitution

Configuration values can reference environment variables using ${VAR_NAME} syntax: 
completion_models:
  default_completion_model:
    api_key: ${GRAPHRAG_API_KEY}
.env
GRAPHRAG_API_KEY=your-api-key-here
If a .env file is present in your project root, environment variables will be automatically loaded.

​
Language model configuration

​
Completion models

Define completion models for text generation tasks: 
completion_models:
  default_completion_model:
    model_provider: openai
    model: gpt-4.1
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}
    retry:
      type: exponential_backoff
      max_retries: 7
      base_delay: 2.0
    rate_limit:
      type: sliding_window
      period_in_seconds: 60
      requests_per_period: 100
You can define multiple models and reference them by key in workflow configurations. See LLM Models for detailed examples.

​
Embedding models

Define embedding models for vector generation: 
embedding_models:
  default_embedding_model:
    model_provider: openai
    model: text-embedding-3-large
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}

​
Input configuration

​
Input settings

Configure document input format and location: 
input:
  type: text  # text, csv, json, jsonl
  encoding: utf-8
  file_pattern: ".*\\.txt$"  # regex pattern for files
  id_column: id  # for CSV/JSON
  title_column: title  # for CSV/JSON
  text_column: text  # for CSV/JSON
​
type
string
default:"text"
Input data format: text, csv, json, or jsonl
​
encoding
string
default:"utf-8"
Character encoding for input files
​
file_pattern
string
Regex pattern to match input files (defaults based on type)
​
id_column
string
Column name for document IDs (CSV/JSON only)
​
title_column
string
Column name for document titles (CSV/JSON only)
​
text_column
string
Column name for document text content (CSV/JSON only)

​
Chunking configuration

Configure how documents are split into chunks: 
chunking:
  type: tokens  # tokens or sentence
  size: 1200
  overlap: 100
  encoding_model: o200k_base
  prepend_metadata:
    - title
    - source
​
type
string
default:"tokens"
Chunking strategy: tokens or sentence
​
size
integer
default:"1200"
Maximum chunk size in tokens
​
overlap
integer
default:"100"
Number of overlapping tokens between chunks
​
encoding_model
string
default:"o200k_base"
Tokenizer model for splitting text
​
prepend_metadata
array
Document metadata fields to prepend to each chunk

​
Storage configuration

See the Storage page for detailed storage configuration.

​
Workflow configurations

​
Text embedding

Configure text embedding generation: 
embed_text:
  embedding_model_id: default_embedding_model
  model_instance_name: text_embedding
  batch_size: 16
  batch_max_tokens: 8191
  names:
    - text_unit_text
    - entity_description
    - community_full_content
​
embedding_model_id
string
required
Reference to embedding model configuration
​
batch_size
integer
default:"16"
Maximum number of texts to embed in one batch
​
batch_max_tokens
integer
default:"8191"
Maximum total tokens per batch
​
names
array
Which embeddings to generate: text_unit_text, entity_description, community_full_content

​
Graph extraction

Configure LLM-based entity and relationship extraction: 
extract_graph:
  completion_model_id: default_completion_model
  model_instance_name: extract_graph
  prompt: "prompts/extract_graph.txt"
  entity_types:
    - organization
    - person
    - geo
    - event
  max_gleanings: 1
​
completion_model_id
string
required
Reference to completion model configuration
​
prompt
string
Path to extraction prompt file
​
entity_types
array
default:"[organization, person, geo, event]"
List of entity types to extract
​
max_gleanings
integer
default:"1"
Number of additional extraction passes for thoroughness

​
NLP-based extraction

Configure NLP-based graph extraction (alternative to LLM): 
extract_graph_nlp:
  normalize_edge_weights: true
  concurrent_requests: 25
  async_mode: threaded  # threaded or asyncio
  text_analyzer:
    extractor_type: regex_english  # regex_english, syntactic_parser, cfg
    max_word_length: 15
    include_named_entities: true

​
Description summarization

Configure entity and relationship description summarization: 
summarize_descriptions:
  completion_model_id: default_completion_model
  model_instance_name: summarize_descriptions
  prompt: "prompts/summarize_descriptions.txt"
  max_length: 500
  max_input_tokens: 4000
​
max_length
integer
default:"500"
Maximum output tokens per summary
​
max_input_tokens
integer
default:"4000"
Maximum input tokens to collect for summarization

​
Graph clustering

Configure Leiden hierarchical clustering: 
cluster_graph:
  max_cluster_size: 10
  use_lcc: true
  seed: 0xDEADBEEF
​
max_cluster_size
integer
default:"10"
Maximum cluster size for export
​
use_lcc
boolean
default:"true"
Whether to use only the largest connected component
​
seed
integer
default:"0xDEADBEEF"
Random seed for consistent clustering results

​
Graph pruning

Configure optional graph pruning to optimize modularity: 
prune_graph:
  min_node_freq: 2
  max_node_freq_std: null
  min_node_degree: 1
  max_node_degree_std: null
  min_edge_weight_pct: 40.0
  remove_ego_nodes: true
  lcc_only: false
​
min_node_freq
integer
default:"2"
Minimum node frequency to retain
​
min_node_degree
integer
default:"1"
Minimum node degree (connections) to retain
​
min_edge_weight_pct
float
default:"40.0"
Minimum edge weight percentile to retain
​
remove_ego_nodes
boolean
default:"true"
Remove ego nodes (nodes connected to everything)

​
Community reports

Configure community report generation: 
community_reports:
  completion_model_id: default_completion_model
  model_instance_name: community_reporting
  graph_prompt: "prompts/community_report_graph.txt"
  text_prompt: "prompts/community_report_text.txt"
  max_length: 2000
  max_input_length: 8000
​
graph_prompt
string
Prompt for graph-based community summarization
​
text_prompt
string
Prompt for text-based community summarization
​
max_length
integer
default:"2000"
Maximum output tokens per report
​
max_input_length
integer
default:"8000"
Maximum input tokens for report generation

​
Claim extraction

Configure optional claim extraction: 
extract_claims:
  enabled: false
  completion_model_id: default_completion_model
  prompt: "prompts/extract_claims.txt"
  description: "Any claims or facts that could be relevant to information discovery."
  max_gleanings: 1
Claim extraction is disabled by default and requires prompt tuning for your specific domain.

​
Snapshots

Configure optional data snapshots: 
snapshots:
  embeddings: false
  graphml: false
  raw_graph: false
​
embeddings
boolean
default:"false"
Export embeddings to parquet files
​
graphml
boolean
default:"false"
Export graph to GraphML format
​
raw_graph
boolean
default:"false"
Export raw extracted graph before merging

​
Query configurations

Configure local search for targeted queries: 
local_search:
  completion_model_id: default_completion_model
  embedding_model_id: default_embedding_model
  prompt: "prompts/local_search_system_prompt.txt"
  text_unit_prop: 0.5
  community_prop: 0.15
  conversation_history_max_turns: 5
  top_k_entities: 10
  top_k_relationships: 10
  max_context_tokens: 12000
Configure global search for broad queries: 
global_search:
  completion_model_id: default_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"
  data_max_tokens: 12000
  map_max_length: 1000
  reduce_max_length: 2000
  dynamic_search_threshold: 1
Configure DRIFT search for iterative exploration: 
drift_search:
  completion_model_id: default_completion_model
  embedding_model_id: default_embedding_model
  prompt: "prompts/drift_search_system_prompt.txt"
  reduce_prompt: "prompts/drift_search_reduce_prompt.txt"
  n_depth: 3
  drift_k_followups: 20
  concurrency: 32
Configure basic vector search: 
basic_search:
  completion_model_id: default_completion_model
  embedding_model_id: default_embedding_model
  prompt: "prompts/basic_search_system_prompt.txt"
  k: 10
  max_context_tokens: 12000

​
Advanced settings

​
Workflows

Override the default workflow execution order: 
workflows:
  - extract_graph
  - summarize_descriptions
  - cluster_graph
  - community_reports
Most users don’t need to customize workflows. Only specify this if you want precise control over execution order.

​
Concurrency settings

Control global concurrency for async operations: 
concurrent_requests: 25
async_mode: threaded  # threaded or asyncio

​
Next steps

LLM models

Detailed guide to configuring language models

Storage

Configure storage backends and caching

Initialization

Learn about the init command

Start indexing

Begin processing your documents

Build docs developers (and LLMs) love

Get started for freeTalk to us