graphrag

Habilidade GraphRAG

Geração aumentada por recuperação sobre um grafo de conhecimento em vez de fragmentos planos. Entidades e relacionamentos são extraídos dos seus documentos, armazenados em um banco de dados de grafos, e o LLM raciocina sobre a estrutura do grafo no momento da consulta.

Por que um Grafo em Vez de Vetores

A busca vetorial encontra fragmentos similares. Ela não consegue seguir conexões:

• "Quais fornecedores foram afetados pela paralisação na fábrica X?" precisa de Paralisação → afeta → Fábrica → fornecido_por → Fornecedor — dois saltos que nenhum fragmento contém.
• "Resuma tudo que sabemos sobre o projeto Y" precisa da comunidade de entidades ao redor de Y, não dos dez parágrafos mais similares.

Se suas perguntas são consultas de fato único, mantenha-se com RAG vetorial — é mais simples. Recorra ao GraphRAG quando as perguntas abrangerem relacionamentos.

Pilha

• Kuzu — banco de dados de grafos embutido (pip install kuzu), sem servidor para executar, linguagem de consulta Cypher. Comece por aqui.
• Neo4j — quando você superar o embutido: multi-usuário, grafos maiores, visualização Bloom. Mesmas habilidades de Cypher são transferíveis.
• Extração com LLM — qualquer modelo forte com saída estruturada para extração de entidades/relacionamentos.

Pipeline

1. Defina o esquema primeiro

Não deixe o extrator inventar tipos livremente — você terá 40 grafias do mesmo relacionamento. Declare os tipos de nós e arestas antecipadamente:

CREATE NODE TABLE Pessoa(nome STRING, PRIMARY KEY(nome));
CREATE NODE TABLE Projeto(nome STRING, status STRING, PRIMARY KEY(nome));
CREATE NODE TABLE Documento(titulo STRING, data DATE, PRIMARY KEY(titulo));
CREATE REL TABLE TRABALHA_EM(DE Pessoa PARA Projeto, papel STRING);
CREATE REL TABLE MENCIONA(DE Documento PARA Pessoa);
CREATE REL TABLE MENCIONA_PROJETO(DE Documento PARA Projeto);

Mantenha o esquema pequeno (5-10 tipos de nós). Você pode estendê-lo; não pode "desextrair" um grafo bagunçado de forma barata.

2. Extraia entidades e relacionamentos

Divida os documentos em fragmentos (500-1000 tokens, com sobreposição) e então solicite ao extrator:

Extraia entidades e relacionamentos do texto abaixo.

Tipos de nó permitidos: Pessoa, Projeto, Documento
Tipos de aresta permitidos: TRABALHA_EM (Pessoa→Projeto), MENCIONA (Documento→Pessoa),
                    MENCIONA_PROJETO (Documento→Projeto)

Regras:
- Normalize nomes ("J. Silva" e "João Silva" são a mesma Pessoa)
- Extraia apenas relacionamentos declarados ou claramente implícitos no texto
- Retorne JSON: {"nodes": [...], "edges": [...]}

Texto:
<fragmento>

Verifique manualmente 10-20 fragmentos. A qualidade da extração é o teto para tudo a jusante — um grafo ruidoso gera respostas ruidosas.

3. Carregue no Kuzu

import kuzu
db = kuzu.Database("./knowledge.kz")
conn = kuzu.Connection(db)
# crie o esquema, depois MERGE/CREATE com parâmetros para cada nó/aresta extraído

Desduplique no carregamento (MERGE na chave primária) — a mesma entidade aparece em muitos fragmentos.

4. Padrões de consulta

Busca local — tudo conectado a uma entidade:

MATCH (p:Pessoa {nome: $nome})-[r]-(vizinho)
RETURN type(r), vizinho;

Raciocínio multi-salto — siga relacionamentos através do grafo:

// Quem trabalha em projetos mencionados em documentos sobre a paralisação?
MATCH (d:Documento)-[:MENCIONA_PROJETO]->(proj:Projeto)<-[:TRABALHA_EM]-(p:Pessoa)
WHERE d.titulo CONTAINS 'paralisação'
RETURN DISTINCT p.nome, proj.nome;

Sumarização global — detecção de comunidades, depois resuma cada comunidade:

// Encontre clusters densamente conectados (execute uma vez, armazene id da comunidade nos nós)
CALL show_tables();  // depois use a detecção de comunidades do seu grafo

Resuma cada comunidade com o LLM: "estas entidades agrupam-se em torno do tópico X." Esta é a "consulta global" do GraphRAG — perguntas como "quais são os principais temas nestes documentos?"

5. Responda com o LLM

O padrão de consulta que funciona:

1. O agente traduz a pergunta em 1-3 consultas Cypher
2. Os resultados retornam como linhas estruturadas
3. O LLM sintetiza a resposta a partir das linhas, citando evidências de nós/arestas
4. Se uma consulta não retornar nada, o agente reformula — nunca alucina conteúdo do grafo

Conhecimento temporal (memória do agente)

Para memória do agente entre sessões, adicione tempo às arestas: carimbos VALIDO_DE / VALIDO_ATE, fatos substituídos marcados em vez de deletados. Este é o padrão de grafo de conhecimento temporal (veja Graphiti/Zep): "o usuário costumava preferir X, agora prefere Y" permanece consultável em vez de ser sobrescrito.

Anti-padrões

• Extrair sem um esquema. Extração de forma livre produz um grafo que ninguém consegue consultar.
• GraphRAG para tudo. Consulta de fato único em documentos limpos? Busca vetorial é mais barata e melhor. Use o grafo onde relacionamentos importam.
• Confiar cegamente na extração. Todo pipeline precisa de um ciclo de verificação manual; erros de extração se acumulam silenciosamente.
• Fragmentos enormes. A extração de entidades degrada além de ~1000 tokens — o modelo começa a perder relacionamentos. Fragmentos menores, mais deles.
• Sem desduplicação no carregamento. "João Silva", "J. Silva", "Silva" como três nós quebram silenciosamente consultas multi-salto.