GraphRAG on Kubernetes with Neo4j: Production Knowledge Graph RAG Guide (2026)

helm repo add neo4j https://helm.neo4j.com/neo4j
helm repo update
kubectl create namespace neo4j

# values.prod.yaml
neo4j:
  name: prod
  edition: "enterprise"
  acceptLicenseAgreement: "yes"
  offlineMaintenanceModeEnabled: false
  password: ${NEO4J_PASSWORD}            # via external-secrets in practice
  resources:
    cpu: "4"
    memory: "32Gi"

volumes:
  data:
    mode: "defaultStorageClass"
    defaultStorageClass:
      requests:
        storage: 500Gi
      storageClassName: gp3
  transactions:
    mode: "defaultStorageClass"
    defaultStorageClass:
      requests:
        storage: 100Gi
      storageClassName: gp3

env:
  NEO4J_dbms_memory_pagecache_size: "16G"
  NEO4J_server_memory_heap_initial__size: "8G"
  NEO4J_server_memory_heap_max__size: "8G"
  NEO4J_db_tx__log_rotation_retention__policy: "1 days"
  NEO4J_dbms_security_procedures_unrestricted: "gds.*,apoc.*"
  NEO4J_PLUGINS: '["apoc", "graph-data-science"]'
  NEO4J_server_backup_enabled: "true"

config:
  server.bolt.listen_address: ":7687"
  server.bolt.advertised_address: ":7687"
  server.http.listen_address: ":7474"

logInitialPassword: "no"

podSpec:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: helm.neo4j.com/neo4j.name
              operator: In
              values: [prod]
        topologyKey: kubernetes.io/hostname

services:
  bolt:
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
      service.beta.kubernetes.io/aws-load-balancer-internal: "true"

for i in 0 1 2; do
  helm upgrade --install core-$i neo4j/neo4j \
    --namespace neo4j \
    --values values.prod.yaml \
    --set neo4j.name=core-$i \
    --set neo4j.minimumClusterSize=3 \
    --wait --timeout 15m
done

FROM python:3.11-slim
RUN pip install \
    neo4j==5.22.0 \
    neo4j-graphrag==0.4.0 \
    openai==1.51.0 \
    qdrant-client==1.11.0 \
    pydantic==2.9.0

# extraction_worker.py
import asyncio
import neo4j
from neo4j_graphrag.llm import OpenAILLM
from neo4j_graphrag.embeddings import OpenAIEmbeddings
from neo4j_graphrag.experimental.pipeline.kg_builder import SimpleKGPipeline

# LLM via LiteLLM proxy (OpenAI-compatible) - see /deploy-litellm-proxy-on-kubernetes/
llm = OpenAILLM(
    model_name="llama-3.1-70b-selfhosted",
    api_key="sk-litellm-abc123",
    base_url="https://llm.example.ae/v1",
    model_params={"temperature": 0.0, "max_tokens": 4096},
)

embedder = OpenAIEmbeddings(
    model="text-embedding-3-large",
    api_key="sk-litellm-abc123",
    base_url="https://llm.example.ae/v1",
)

driver = neo4j.AsyncGraphDatabase.driver(
    "neo4j+s://neo4j.example.ae:7687",
    auth=("neo4j", os.environ["NEO4J_PASSWORD"]),
)

# Schema - constrain what the LLM extracts
entities = [
    "Person", "Company", "Product", "Service",
    "Document", "Incident", "Contract",
]
relations = [
    "WORKS_AT", "OWNS", "DEPENDS_ON",
    "MENTIONS", "RESOLVED_BY", "SUPERSEDES",
]
potential_schema = [
    ("Person", "WORKS_AT", "Company"),
    ("Company", "OWNS", "Product"),
    ("Service", "DEPENDS_ON", "Service"),
    ("Document", "MENTIONS", "Person"),
    ("Incident", "RESOLVED_BY", "Person"),
    ("Contract", "SUPERSEDES", "Contract"),
]

pipeline = SimpleKGPipeline(
    llm=llm,
    driver=driver,
    embedder=embedder,
    entities=entities,
    relations=relations,
    potential_schema=potential_schema,
    from_pdf=False,
    neo4j_database="neo4j",
    on_error="IGNORE",
)

async def ingest_doc(text: str, source_id: str):
    await pipeline.run_async(text=text, document_info={"source_id": source_id})

apiVersion: apps/v1
kind: Deployment
metadata:
  name: graphrag-extraction-worker
  namespace: graphrag
spec:
  replicas: 3
  selector:
    matchLabels: {app: graphrag-extraction-worker}
  template:
    metadata:
      labels: {app: graphrag-extraction-worker}
    spec:
      containers:
        - name: worker
          image: registry.example.ae/graphrag/extraction:v1.0.0
          env:
            - name: NEO4J_URI
              value: "neo4j+s://core-0-neo4j.neo4j.svc.cluster.local:7687"
            - name: LITELLM_URL
              value: "http://litellm.llm-gateway.svc.cluster.local:4000"
          envFrom:
            - secretRef:
                name: graphrag-secrets
          resources:
            requests: {cpu: 500m, memory: 1Gi}
            limits: {memory: 4Gi}
---
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: graphrag-extraction-worker
  namespace: graphrag
spec:
  scaleTargetRef: {name: graphrag-extraction-worker}
  minReplicaCount: 1
  maxReplicaCount: 10
  triggers:
    - type: redis
      metadata:
        address: redis.graphrag:6379
        listName: "graphrag:extract:pending"
        listLength: "5"

# orchestrator/rag.py
from qdrant_client import AsyncQdrantClient
from neo4j import AsyncGraphDatabase

qdrant = AsyncQdrantClient(url=QDRANT_URL, api_key=QDRANT_API_KEY)
neo4j_driver = AsyncGraphDatabase.driver(NEO4J_URL, auth=("neo4j", NEO4J_PWD))

async def hybrid_retrieve(query: str, tenant_id: str) -> dict:
    # 1. Vector search
    q_embedding = await embed(query)
    vector_hits = await qdrant.search(
        collection_name="documents",
        query_vector=q_embedding,
        query_filter={"must": [{"key": "tenant_id", "match": {"value": tenant_id}}]},
        limit=10,
    )

    # 2. Expand each hit to its 2-hop subgraph in Neo4j
    chunk_ids = [h.payload["chunk_id"] for h in vector_hits]
    async with neo4j_driver.session() as session:
        subgraph = await session.run("""
            MATCH (c:Chunk)-[:MENTIONS]-(e)
            WHERE c.id IN $chunk_ids
            WITH e
            MATCH path = (e)-[*1..2]-(related)
            WHERE all(n IN nodes(path) WHERE n.tenant_id = $tenant_id OR NOT 'tenant_id' IN keys(n))
            RETURN DISTINCT
              e.name AS entity,
              type(last(relationships(path))) AS relation,
              related.name AS related_entity,
              related.description AS related_description
            LIMIT 50
        """, chunk_ids=chunk_ids, tenant_id=tenant_id)
        graph_facts = await subgraph.data()

    return {
        "chunks": [{"text": h.payload["text"], "source": h.payload["source_id"]} for h in vector_hits],
        "graph_facts": graph_facts,
    }

async def answer(query: str, tenant_id: str, user_id: str) -> str:
    retrieval = await hybrid_retrieve(query, tenant_id)

    prompt_context = "\n\n".join([
        "RELEVANT DOCUMENTS:",
        "\n".join(f"- {c['text']}" for c in retrieval["chunks"]),
        "",
        "RELATED ENTITIES AND RELATIONSHIPS:",
        "\n".join(f"- {f['entity']} {f['relation']} {f['related_entity']}: {f['related_description'] or ''}"
                  for f in retrieval["graph_facts"]),
    ])

    # Generate via LiteLLM
    resp = await llm.chat.completions.create(
        model="gpt-4o-uae-primary",
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": f"{prompt_context}\n\nQuestion: {query}"},
        ],
        extra_body={"metadata": {"trace_user_id": user_id, "tags": ["graphrag", "prod"]}},
    )
    return resp.choices[0].message.content