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

> Uma aplicação Streamlit que demonstra como a Geração Aumentada por Recuperação (RAG) baseada em Gráfico de Conhecimento fornece raciocínio multi-hop com atribuição de fontes totalmente verificáveis.

- Fonte: https://doutorai.pt/apps/knowledge-graph-rag-citations
- Categoria: RAG e Conhecimento
- Dificuldade: Médio
- Modelos: Llama, Mistral
- Frameworks: Ollama (local)
- Corre local?: Sim (Ollama)
- Chaves necessárias: Nenhuma
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# 🔍 Knowledge Graph RAG com 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

| Funcionalidade | Descrição |
|----------------|-----------|
| 🔗 **Raciocínio Multi-hop** | Percorre relações de entidades para responder a perguntas complexas |
| 📚 **Citações Verificáveis** | Cada afirmação inclui o documento fonte e o texto |
| 🧠 **Rastro de Raciocínio** | Vê exatamente como a resposta foi derivada |
| 🏠 **Totalmente Local** | Usa Ollama para LLM, Neo4j para armazenamento de grafo |

## 🚀 Início Rápido

### Pré-requisitos

1. **Ollama** - Inferência LLM local

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

```markdown
# 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](https://neo4j.com/download/).
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:

   ```bash
   ./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:

```cypher
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.
```

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

### Instalação

```bash
# 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

```plaintext
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

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/knowledge-graph-rag-citations