◆ RAG Local — Seus documentos consultados por uma IA local, sem nuvem · 24 € · ou todos os kits 49 € →

#Por que usar o GraphRAG?

Imagine o corpus de um escritório jurídico: 200 contratos, 500 e-mails, 80 decisões. Você faz a pergunta: “Quais são os principais riscos jurídicos mencionados em nossos contratos com clientes nos últimos três anos, e com quais clientes recorrentes?”. Um RAG vetorial clássico busca 5 ou 10 chunks “relevantes”, fornece esses trechos ao LLM, e ele responde… com uma visão parcial. Ele não identifica os padrões transversais.

GraphRAG, em vez de retornar apenas trechos brutos, raciocina sobre uma estrutura: quem menciona o quê, quais entidades se repetem, quais relações as ligam. Para esse tipo de pergunta de síntese (« global ») sobre um corpus, o grafo supera a abordagem vetorial — exatamente o que demonstrava o artigo original da Microsoft Research em 2024.

Para quem é este guia

Você já tem um RAG vetorial local funcionando (ChromaDB, LlamaIndex, AnythingLLM…), mas está travando nas perguntas de síntese. Caso contrário, comece com um RAG clássico antes de abordar esse tipo.

#GraphRAG vs RAG vetorial: a verdadeira diferença

O kit RAG Local

Seus documentos, sua IA: um RAG local confiável para seus PDFs, notas e e-mails — sem enviar nada para a nuvem.

Espaço online vitalício
PDF + arquivos
Atualizações vitalícias

O kit RAG Local →ou todos os kits vitalícios — 49 € →

As duas abordagens compartilham um objetivo: injetar contexto externo no prompt do LLM para limitar as alucinações. Mas elas não recuperam a mesma coisa.

RAG vetorial: Divide o corpus em chunks, calcula um embedding por chunk e armazena em uma base vetorial (ChromaDB, Qdrant, FAISS). Ao receber uma consulta, recupera os k chunks mais próximos pela similaridade de cosseno.
GraphRAG: Solicita a um LLM que extraia entidades e relações de cada chunk, constrói um grafo, agrupa as entidades em comunidades e resume cada comunidade. Ao receber uma consulta, percorre o grafo ou agrega resumos de comunidades.
Pontos fortes do RAG vetorial: Rápido para indexação (alguns minutos para 10 MB de texto), barato, excelente para perguntas específicas (« qual é a cláusula de rescisão no contrato Acme? »).
Pontos fortes do GraphRAG: Excelente para perguntas gerais (“quais são os temas recorrentes?”, “quais entidades estão mais conectadas?”), rastreabilidade detalhada por meio das arestas, multi-hop nativo.
Limitação da abordagem vetorial: Perde as relações entre documentos. Uma pergunta que exige relacionar 3 documentos semanticamente distantes não recupera os trechos corretos.
Fraqueza do GraphRAG: Indexação pesada: é preciso passar cada chunk por um LLM. Para um corpus de 10 MB, conte com várias horas e muita VRAM, enquanto a indexação vetorial termina em 5 minutos.

→

A abordagem híbrida ganha muitas vezes

Na prática, as melhores stacks combinam os dois: grafo para perguntas globais e navegação, busca vetorial (ou BM25) para consultas específicas. Veja também a pesquisa híbrida BM25 + vetorial para outra forma de combinação.

#Como funciona internamente

Um pipeline GraphRAG completo encadeia 5 etapas. Todas utilizam o LLM (exceto o clustering).

01
Chunking
O corpus é dividido em trechos de 500 a 1500 tokens, como em um RAG clássico. O tamanho tem impacto direto na qualidade da extração: se o trecho for curto demais, o LLM deixa de identificar relações; se for longo demais, ele esquece algumas delas.
02
Extração de entidades e relações
Cada chunk é enviado a um LLM com um prompt estruturado do tipo: “Extraia todas as entidades (pessoa, organização, local, conceito) e as relações entre elas. Formato JSON.” Esta é a etapa custosa — uma chamada ao LLM por chunk.
03
Construção do grafo
Entidades extraídas tornam-se nós, as relações tornam-se arestas. Entidades idênticas que aparecem em vários chunks são mescladas (resolução de entidades, geralmente por embedding ou por regra de normalização).
04
Detecção de comunidades
Um algoritmo de agrupamento (Leiden no caso da Microsoft, um algoritmo mais simples no nano-graphrag) agrupa os nós fortemente conectados em comunidades. Essas comunidades são a chave do raciocínio “global”.
05
Resumo das comunidades
O LLM gera um resumo textual de cada comunidade a partir das entidades e relações que ela contém. Esses resumos tornam-se as unidades de recuperação para perguntas globais.

Na consulta, o GraphRAG distingue dois modos: local (busca de uma entidade específica e de seu entorno) e global (agregação de resumos de comunidades). O LLM combina depois o contexto recuperado com a pergunta para produzir a resposta final.

#Ferramentas disponíveis para uma implantação local

Microsoft GraphRAG: A implementação de referência (github.com/microsoft/graphrag). Completa, bem feita, mas pesada: pensada inicialmente para Azure OpenAI, a adaptação para Ollama exige paciência. Indexação muito custosa em tokens.
nano-graphrag: Implementação mínima (~1000 linhas) compatível nativamente com Ollama (github.com/gusye1234/nano-graphrag). É essa implementação que vamos usar aqui: 10 vezes menos código para entender, com a mesma ideia.
LightRAG: Variante mais recente, otimizada para a latência das consultas. Compatível com o Ollama. Mais simples que o Microsoft GraphRAG, mais estruturada que o nano-graphrag.
LlamaIndex KnowledgeGraphIndex: Se você já está usando LlamaIndex, a integração é imediata, mas a abordagem é mais rudimentar (sem comunidades).

Escolha pedagógica

Este guia utiliza nano-graphrag porque tudo cabe em dois arquivos Python que podemos ler, modificar, depurar. Uma vez dominado o conceito, passar para Microsoft GraphRAG ou LightRAG em produção torna-se trivial.

#Pré-requisitos

Ollama instalado e funcionando: Se não for o caso, siga primeiro nosso guia de instalação do Ollama.
Um LLM de raciocínio sólido (14-24B): A extração de entidades exige bastante capacidade de processamento. gpt-oss 20B, Mistral Small 24B ou Qwen 3.5 9B (limite inferior) funcionam bem. Abaixo de 8B, o JSON gerado costuma estar malformado.
Um modelo de embeddings local: nomic-embed-text via Ollama, ou bge-m3 / multilingual-e5-large via sentence-transformers.
No mínimo 16 GB de VRAM: 12 GB servem como solução provisória para um modelo de 8-9B em Q4 (Qwen 3.5 9B), mas a indexação será lenta. 16 GB acomodam gpt-oss 20B ou Mistral Small 24B; 24 GB (RTX 4090, M-Max) oferecem uma margem confortável.
Python 3.10+: nano-graphrag e a maioria dos frameworks RAG modernos exigem 3.10 ou mais.

#1. Indexar um corpus com nano-graphrag

Prepare primeiro os modelos no Ollama. Para este tutorial, usamos gpt-oss 20B (quantização MXFP4 por padrão, ~14 GB) e nomic-embed-text como modelo de embeddings.

Terminal

ollama pull gpt-oss:20b
ollama pull nomic-embed-text
ollama serve  # si pas déjà en service

Instale em seguida o nano-graphrag em um ambiente venv dedicado.

Terminal

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
pip install nano-graphrag

O script de indexação cabe em cerca de vinte linhas. Ele é conectado ao Ollama pelo endpoint compatível com a OpenAI na porta 11434.

index.py

import asyncio
from nano_graphrag import GraphRAG, QueryParam
from nano_graphrag.llm import ollama_model_if_cache, ollama_embedding

WORKING_DIR = "./graphrag_cache"

async def main():
    rag = GraphRAG(
        working_dir=WORKING_DIR,
        best_model_func=ollama_model_if_cache,
        cheap_model_func=ollama_model_if_cache,
        embedding_func=ollama_embedding,
        best_model_kwargs={"model_name": "gpt-oss:20b"},
        cheap_model_kwargs={"model_name": "gpt-oss:20b"},
    )

    with open("corpus.txt", encoding="utf-8") as f:
        text = f.read()

    await rag.ainsert(text)

if __name__ == "__main__":
    asyncio.run(main())

Inicie a indexação. Conforme o tamanho do corpus e a GPU, conte com um tempo de alguns minutos (1 MB de texto) a várias horas (50 MB).

Terminal

python index.py

Paciência: é lento por natureza

Para um corpus de 5 MB com gpt-oss 20B em uma RTX 4090, conte com cerca de 2 horas. O nano-graphrag processa os chunks sequencialmente por padrão. Isso é normal — você paga pela extração com o LLM, não por um cálculo de embeddings.

No final, o diretório graphrag_cache/ contém o grafo serializado, os embeddings e os resumos de comunidades.

#2. Consultar o grafo

Após a indexação, a consulta é rápida (alguns segundos por requisição), pois o LLM passa a ler apenas o contexto recuperado do grafo, e não a totalidade do corpus.

query.py

import asyncio
from nano_graphrag import GraphRAG, QueryParam
from nano_graphrag.llm import ollama_model_if_cache, ollama_embedding

async def main():
    rag = GraphRAG(
        working_dir="./graphrag_cache",
        best_model_func=ollama_model_if_cache,
        cheap_model_func=ollama_model_if_cache,
        embedding_func=ollama_embedding,
        best_model_kwargs={"model_name": "gpt-oss:20b"},
        cheap_model_kwargs={"model_name": "gpt-oss:20b"},
    )

    # Mode global : synthèse à partir des résumés de communautés
    print(await rag.aquery(
        "Quels sont les thèmes principaux du corpus ?",
        param=QueryParam(mode="global")
    ))

    # Mode local : recherche centrée sur des entités
    print(await rag.aquery(
        "Quelle est la position de l'entreprise X sur le sujet Y ?",
        param=QueryParam(mode="local")
    ))

asyncio.run(main())

→

Escolher o modo certo

Pergunta que começa com «quais são os principais…», «quais são as tendências…», «faça uma síntese…» → modo global. Pergunta sobre uma entidade específica → modo local. Se você não sabe, tente os dois: as respostas muitas vezes diferem radicalmente.

#Custo de computação local: o que se pode esperar

Esta é a parte que surpreende todo mundo na primeira vez. Indexar 5 MB de texto em GraphRAG exige cerca de 50 a 200 vezes mais processamento do que um RAG vetorial sobre o mesmo corpus. Aqui estão referências concretas, em termos de ordens de grandeza.

Corpus de 1 MB (~300 páginas): gpt-oss 20B (MXFP4) na RTX 4090: ~25 minutos de indexação. Na RTX 3060 de 12 GB (offload parcial): ~3 h. No Mac M3 Max de 64 GB: ~40 minutos.
Corpus de 5 MB (~1500 páginas): RTX 4090: ~2h. M4 Pro 48 GB: ~3h. Acima desse volume, planeje deixar rodando durante a noite.
Pico de uso de VRAM: O modelo gpt-oss 20B (MXFP4) ocupa ~14 GB permanentemente. Os embeddings nomic adicionam ~1 GB. Com menos de 16 GB de VRAM, espere uma transferência parcial para a RAM, com execução na CPU (offload parcial).
Custo por requisição: Alguns segundos no modo local, 5 a 30 s no modo global (agregação de várias comunidades). Pouco oneroso em comparação com a indexação.
Reindexação incremental: O nano-graphrag atualmente não consegue atualizar corretamente um grafo existente. Adicionar 10% de novos documentos = executar novamente uma indexação parcial ou completa. O Microsoft GraphRAG lida melhor com esse ponto.

A armadilha do LLM pequeno demais

Você está pensando em usar Granite 4.2 3B ou Qwen 3.5 2B para ganhar velocidade? A extração de JSON será inconsistente, as entidades terão nomes incorretos e o grafo será inutilizável. É exatamente o erro em que a indexação rápida produz um grafo que não pode ser aproveitado. Invista em um modelo de no mínimo 8B, idealmente gpt-oss 20B ou Mistral Small 24B.

#Quando o GraphRAG realmente supera a busca vetorial

GraphRAG não é um substituto universal do RAG vetorial. Ele o supera de longe em certos casos de uso, mas tem desempenho claramente inferior em outros.

Síntese de um corpus: “Quais são os 5 temas principais discutidos em nossos 200 e-mails sobre o assunto X?” → GraphRAG vence com folga. A busca vetorial traz apenas 5 a 10 e-mails, enquanto o grafo agrega as comunidades.
Perguntas multi-hop: “Quais fornecedores trabalham tanto com a Acme quanto com a Beta Corp?” → O GraphRAG resolve isso percorrendo as arestas. A abordagem vetorial precisa encontrar os trechos corretos e contar com o LLM para fazer o join.
Exploração de relações: “Quem são as pessoas mais mencionadas em relação ao projeto Atlas?” → O GraphRAG foi concebido para isso (centralidade, vizinhança). A abordagem vetorial não tem a noção de relação.
Perguntas e respostas factuais focadas: « Qual a duração do aviso prévio no contrato Acme de 12 de março de 2024? » → RAG vetorial ganha: mais rápido, mais preciso, menos caro para indexar.
Corpus que muda com muita frequência: Se você adicionar documentos todos os dias, o custo de reindexação do GraphRAG se torna proibitivo. Continue usando busca vetorial ou busca vetorial + BM25.
Corpus < 500 kB: Não é necessário um grafo: o LLM pode ler tudo no contexto se você tiver 32k+ tokens. O GraphRAG só se justifica para corpora grandes demais para caber no contexto.

→

A regra prática

Se seus usuários fazem principalmente perguntas do tipo “procure esta informação específica”, continue com a busca vetorial. Se o valor estiver na síntese, na exploração de padrões ou na análise transversal de um corpus estável, o GraphRAG vale o custo de indexação.

#Para se aprofundar

GraphRAG é um campo ativo: as implementações evoluem rápido, os benchmarks também. Algumas dicas para continuar.

RAG local: introdução: Se alguns conceitos do RAG vetorial ainda forem confusos, o guia de introdução é uma boa base antes de empregar o GraphRAG em produção.
Estratégias de chunking: A qualidade de extração de entidades depende diretamente do tamanho e da coerência dos chunks. Este guia aprofunda as boas práticas.
Busca híbrida BM25 + vetorial: Para combinar o GraphRAG com um retrieval clássico, veja primeiro a pesquisa híbrida: mesma lógica de união de sinais.
Escolher sua GPU para IA local: A indexação GraphRAG exige muitos recursos. Se você usa uma GPU de 8 a 12 GB hoje, passar para 16 a 24 GB muda radicalmente o ritmo de processamento.

Este guia ajudou você?

Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.

Os kits QuelLLMO guia de referência por uso

RAG Local Copiloto Local IA local Agentes Locais IA Empresarial IA Sem Filtros Mac Imagens IA

Todos os kits vitalícios — 49 €

Próximo passo lógico

RAG · 12 min

#Por que usar o GraphRAG?

#GraphRAG vs RAG vetorial: a verdadeira diferença

#Como funciona internamente

#Ferramentas disponíveis para uma implantação local

#Pré-requisitos

#1. Indexar um corpus com nano-graphrag

#2. Consultar o grafo

#Custo de computação local: o que se pode esperar

#Quando o GraphRAG realmente supera a busca vetorial

#Para se aprofundar

RAG local: introdução

Estratégias de chunking

Busca híbrida BM25 + vetorial

Escolher sua GPU para IA local