Skip to content

indexing-and-query.md

Latest commit

 

History

History
99 lines (69 loc) · 7.06 KB

indexing-and-query.md

File metadata and controls

99 lines (69 loc) · 7.06 KB

Indexing, Querying, and Prompt Tuning in GraphRAG for .NET

GraphRAG for .NET keeps feature parity with the Python reference project described in the Microsoft Research blog and the GraphRAG paper. This document explains how the .NET workflows map to the concepts documented on microsoft.github.io/graphrag, highlights the supported query modes, and shows how to customise prompts via manual or auto tuning outputs.

Indexing Architecture

  • Workflow parity. Each indexing stage matches the Python pipeline and the default data flow:
    • load_input_documents → create_base_text_units → summarize_descriptions
    • extract_graph persists entities and relationships
    • create_communities produces communities
    • community_summaries writes community_reports
    • extract_covariates stores covariates
  • Storage schema. Tables share the column layout described under index outputs. The new strongly-typed records (CommunityRecord, CovariateRecord, etc.) mirror the JSON representation used by the Python implementation.
  • Cluster configuration. GraphRagConfig.ClusterGraph exposes the same knobs as the Python cluster_graph settings, enabling largest-component filtering and deterministic seeding.

Language Model Registration

Workflows resolve language models from the DI container via Microsoft.Extensions.AI. Register keyed services for every ModelId you plan to reference:

using Azure;
using Azure.AI.OpenAI;
using GraphRag.Config;
using Microsoft.Extensions.AI;

var openAi = new OpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));
const string chatModelId = "chat_model";
const string embeddingModelId = "embedding_model";

services.AddKeyedSingleton<IChatClient>(chatModelId, _ => openAi.GetChatClient(chatDeployment));
services.AddKeyedSingleton<IEmbeddingGenerator<string, Embedding>>(embeddingModelId, _ => openAi.GetEmbeddingClient(embeddingDeployment));

Configure retries, rate limits, and logging when you construct the concrete clients. GraphRagConfig.Models simply records the set of registered keys so configuration overrides can validate references.

Pipeline Cache

IPipelineCache is intentionally infrastructure-neutral. To mirror ASP.NET Core's in-memory behaviour, register the built-in cache services alongside the provided adapter:

services.AddMemoryCache();
services.AddSingleton<IPipelineCache, MemoryPipelineCache>();

Need Redis or something else? Implement IPipelineCache yourself and register it through DI; the pipeline will automatically consume your custom cache.

Query Capabilities

The query layer ports the orchestrators documented in the GraphRAG query overview:

  • Global search (docs) traverses community summaries and graph context to craft answers spanning the corpus.
  • Local search (docs) anchors on a document neighbourhood when you need focused context.
  • Drift search (docs) monitors narrative changes across time slices.
  • Question generation (docs) produces follow-up questions to extend an investigation.

Every orchestrator consumes the same indexed tables as the Python project, so the .NET stack interoperates with BYOG scenarios described in the index architecture guide.

Prompt Tuning

Manual and auto prompt tuning are both available without code changes:

  1. Manual overrides follow the rules from manual prompt tuning.
    • Place custom templates under a directory referenced by GraphRagConfig.PromptTuning.Manual.Directory and set Enabled = true.
    • Filenames follow the stage key pattern section/workflow/kind.txt (see table below).
  2. Auto tuning integrates the outputs documented in auto prompt tuning.
    • Point GraphRagConfig.PromptTuning.Auto.Directory at the folder containing the generated prompts and set Enabled = true.
    • The runtime prefers explicit paths from workflow configs, then manual overrides, then auto-tuned files, and finally the built-in defaults in prompts/.
  3. Inline overrides can be injected directly from code: set ExtractGraphConfig.SystemPrompt, ExtractGraphConfig.Prompt, or the equivalent properties to either a multi-line string or a value prefixed with inline:. Inline values bypass template file lookups and are used as-is.

Stage Keys and Placeholders

Workflow Stage key Purpose Supported placeholders
extract_graph (system) index/extract_graph/system.txt System prompt that instructs the extractor. N/A
extract_graph (user) index/extract_graph/user.txt User prompt template for individual text units. {{max_entities}}, {{text}}
community_summaries (system) index/community_reports/system.txt System guidance for cluster summarisation. N/A
community_summaries (user) index/community_reports/user.txt User prompt template for entity lists. {{max_length}}, {{entities}}

Placeholders are replaced at runtime with values drawn from workflow configuration:

  • {{max_entities}} → ExtractGraphConfig.EntityTypes.Count + 5 (minimum 1)
  • {{text}} → the original text unit content
  • {{max_length}} → CommunityReportsConfig.MaxLength
  • {{entities}} → bullet list of entity titles and descriptions

If a template is omitted, the runtime falls back to the built-in prompts defined in GraphRagPromptLibrary.

Integration Tests

tests/ManagedCode.GraphRag.Tests/Integration/CommunitySummariesIntegrationTests.cs exercises the new prompt loader end-to-end using the file-backed pipeline storage. Combined with the existing Aspire-powered suites, the tests demonstrate how indexing, community detection, and summarisation behave with tuned prompts while remaining faithful to the GraphRAG BYOG guidance.

Further Reading

These resources underpin the .NET implementation and provide broader context for customising or extending the library.