RAG com Gráfico de Conhecimento e Citações Verificáveis

Uma aplicação Streamlit que demonstra como Knowledge Graph-based Retrieval-Augmented Generation (RAG) fornece raciocínio multi-hop com atribuição de fontes totalmente verificável.

🎯 O Que Torna Isto Diferente?

O RAG tradicional baseado em vetores encontra blocos de texto semelhantes, mas tem dificuldades com:

• Perguntas que requerem informação de múltiplos documentos
• Cadeias de raciocínio complexas
• Fornecer fontes verificáveis para cada afirmação

Knowledge Graph RAG resolve estes problemas ao:

1. Construir um grafo estruturado de entidades e relações a partir de documentos
2. Percorrer conexões para encontrar informação relacionada (raciocínio multi-hop)
3. Rastrear a proveniência para que cada afirmação se ligue à sua fonte

✨ Funcionalidades

🚀 Início Rápido

Pré-requisitos

1. Ollama - Inferência LLM local

   # Install from https://ollama.ai
   ollama pull llama3.2

2. Neo4j - Base de dados de grafo de conhecimento

Introdução

O Neo4j é uma base de dados de grafo que permite armazenar e consultar dados de forma eficiente, utilizando uma estrutura de grafo. É ideal para aplicações que necessitam de relacionamentos complexos entre dados.

Instalação

Para instalar o Neo4j, segue os seguintes passos:

1. Faz o download da versão mais recente do Neo4j a partir do site oficial.
2. Extrai o ficheiro para o diretório desejado.
3. Navega até ao diretório extraído e executa o seguinte comando para iniciar o servidor:

./bin/neo4j start

Conexão ao Neo4j

Após iniciar o servidor, podes aceder à interface web do Neo4j através do seguinte URL:

http://localhost:7474

Utiliza as credenciais padrão (username: `neo4j`, password: `neo4j`) para fazer login.

## Criar um grafo

Para criar um grafo, utiliza o seguinte comando no console do Neo4j:

```cypher
CREATE (n:Person {name: 'Alice', age: 30})

Isto cria um nó do tipo Person com as propriedades name e age.

Consultar dados

Para consultar os dados que criaste, utiliza a seguinte consulta:

MATCH (n:Person) RETURN n

Isto irá retornar todos os nós do tipo Person no grafo.

Conclusão

O Neo4j é uma ferramenta poderosa para trabalhar com dados em forma de grafo. Com a sua interface intuitiva e linguagem de consulta Cypher, é fácil de começar a construir e consultar grafos complexos.

   # Using Docker
   docker run -d \
     --name neo4j \
     -p 7474:7474 -p 7687:7687 \
     -e NEO4J_AUTH=neo4j/password \
     neo4j:latest

Instalação

# Clone and navigate
cd knowledge_graph_rag_citations

# Install dependencies
pip install -r requirements.txt

# Run the app
streamlit run knowledge_graph_rag.py

📖 Como Funciona

Passo 1: Documento → Grafo de Conhecimento

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Document      │ ──► │  LLM Extraction  │ ──► │ Knowledge Graph │
│   (Text/PDF)    │     │  (Entities+Rels) │     │    (Neo4j)      │
└─────────────────┘     └──────────────────┘     └─────────────────┘

Passo 2: Consulta → Percurso Multi-hop

Para realizar uma consulta que envolve múltiplos saltos, deves seguir os seguintes passos:

1. Identificar as Entidades: Começa por identificar as entidades relevantes na tua consulta. Estas podem ser pessoas, organizações ou conceitos que desejas explorar.

2. Definir as Relações: Depois de identificares as entidades, define as relações entre elas. Por exemplo, se uma pessoa "trabalha para" uma organização, ou se uma organização "usa" uma tecnologia.

3. Construir a Consulta: Utiliza as entidades e relações identificadas para construir a tua consulta. Certifica-te de que a consulta é clara e específica para obter os resultados desejados.

4. Executar a Consulta: Após construíres a consulta, executa-a no sistema que estás a utilizar. Verifica se os resultados são os esperados.

5. Analisar os Resultados: Por fim, analisa os resultados obtidos. Se necessário, ajusta a tua consulta e repete o processo até obteres os resultados desejados.

Exemplo de Consulta

SELECT ?person ?organization
WHERE {
  ?person works_for ?organization .
  ?organization uses ?technology .
}

Neste exemplo, a consulta procura pessoas que trabalham para organizações que utilizam uma determinada tecnologia.

┌─────────┐     ┌─────────────┐     ┌─────────────┐     ┌───────────┐
│  Query  │ ──► │  Find Start │ ──► │  Traverse   │ ──► │  Context  │
│         │     │   Entities  │     │  Relations  │     │  + Sources│
└─────────┘     └─────────────┘     └─────────────┘     └───────────┘

Passo 3: Resposta → Citações Verificadas

┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
│   Context   │ ──► │  Generate   │ ──► │  Answer with     │
│ + Sources   │     │   Answer    │     │  [1][2] Citations│
└─────────────┘     └─────────────┘     └──────────────────┘
                                                │
                                                ▼
                                        ┌──────────────────┐
                                        │ Citation Details │
                                        │ • Source Doc     │
                                        │ • Source Text    │
                                        │ • Reasoning Path │
                                        └──────────────────┘

🖥️ Exemplo de Utilização

1. Adicionar um Documento

Cola ou seleciona um documento de exemplo. O sistema extrai entidades e relações:

Document: "GraphRAG was developed by Microsoft Research. 
           Darren Edge led the project..."

Extracted:
  ├── Entity: GraphRAG (TECHNOLOGY)
  ├── Entity: Microsoft Research (ORGANIZATION)  
  ├── Entity: Darren Edge (PERSON)
  └── Relationship: Darren Edge --[WORKS_FOR]--> Microsoft Research

2. Fazer uma Pergunta

Para fazer uma pergunta, utiliza a seguinte estrutura:

1. Título: Um título claro e conciso que descreva a tua pergunta.
2. Descrição: Explica o problema que estás a enfrentar ou a dúvida que tens. Inclui detalhes relevantes, como:

• O que já tentaste.
• Qualquer mensagem de erro que tenhas recebido.
• O ambiente em que estás a trabalhar (ex: sistema operativo, versão do software).

3. Código: Se aplicável, inclui um exemplo de código que reproduza o problema. Usa blocos de código para facilitar a leitura.

4. Etiquetas: Adiciona etiquetas relevantes para ajudar a categorizar a tua pergunta.

Exemplo:

### Título: Erro ao instalar o pacote XYZ

**Descrição**: Estou a tentar instalar o pacote XYZ no meu projeto, mas recebo a seguinte mensagem de erro:

npm install xyz

**Erro**: `npm ERR! code E404`

**Tentativas**: Já verifiquei se o nome do pacote está correto e tentei reinstalar o npm.

**Ambiente**: Windows 10, Node.js v14.17.0

**Código**:
```javascript
const xyz = require('xyz');

### 3. Responder a uma Pergunta

Para responder a uma pergunta, segue estas diretrizes:

1. **Leia atentamente**: Certifica-te de que compreendeste a pergunta antes de responder.
2. **Seja claro e conciso**: Fornece uma resposta direta e fácil de entender.
3. **Inclui exemplos**: Se possível, fornece exemplos de código ou links para documentação relevante.
4. **Referências**: Se a tua resposta se baseia em fontes externas, cita-as.

Exemplo de resposta:

Para resolver o erro npm ERR! code E404, verifica se o pacote XYZ está realmente disponível no npm. Podes fazer isso pesquisando no site do npm. Se o pacote não existir, verifica se o nome está correto ou se existe uma alternativa.

### 4. Etiquetas

As etiquetas ajudam a categorizar as perguntas e a facilitar a busca por tópicos específicos. Algumas etiquetas comuns incluem:

- `instalação`
- `erro`
- `configuração`
- `desempenho`

### 5. Conclusão

Fazer perguntas e responder a perguntas é uma parte importante da comunidade. Seguindo estas diretrizes, ajudarás a manter um ambiente útil e colaborativo.

Question: "Who developed GraphRAG and what organization are they from?"

### 3. Obter Resposta Verificada

Answer: GraphRAG was developed by researchers at Microsoft Research [1],

with Darren Edge leading the project [2].

Citations:

[1] Source: AI Research Paper

Text: "GraphRAG is a technique developed by Microsoft Research..."

[2] Source: AI Research Paper

Text: "...introduced by researchers including Darren Edge..."

## 🔧 Configuração

| Definição | Padrão | Descrição |
|-----------|--------|-----------|
| Neo4j URI | `bolt://localhost:7687` | Cadeia de conexão Neo4j |
| Neo4j User | `neo4j` | Nome de utilizador da base de dados |
| Neo4j Password | - | Palavra-passe da base de dados |
| LLM Model | `llama3.2` | Modelo Ollama para extração/geração |

## 🏗️ Arquitetura

knowledge_graph_rag_citations/

├── knowledge_graph_rag.py # Main Streamlit application

├── requirements.txt # Python dependencies

└── README.md # This file

### Componentes Principais

- **`KnowledgeGraphManager`**: interface Neo4j para operações em grafo
- **`extract_entities_with_llm()`**: extração de entidades/relações baseada em LLM
- **`generate_answer_with_citations()`**: RAG multi-hop com rastreio de proveniência

## 🎓 Aprende Mais

Este exemplo é inspirado no [VeritasGraph](https://github.com/bibinprathap/VeritasGraph), um framework de nível empresarial para:
- RAG de grafo de conhecimento em local
- Traços de raciocínio visual (Veritas-Scope)
- Integração de LLM afinado com LoRA

## 📝 Licença

Licença MIT