# RAG Agente Multimodal

> Esta é uma aplicação RAG multimodal construída com Gemini Embedding 2 e Google ADK. Adicione texto, URLs, PDFs, imagens, áudio ou vídeo; faça uma pergunta; e obtenha uma resposta fundamentada com citações claras.

- Fonte: https://doutorai.pt/apps/multimodal-agentic-rag
- Categoria: RAG e Conhecimento
- Dificuldade: Médio
- Modelos: Gemini
- Frameworks: Google ADK
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: GOOGLE_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# Agente Multimodal RAG

Esta é uma aplicação RAG multimodal construída com Gemini Embedding 2 e Google ADK. Adiciona texto, URLs, PDFs, imagens, áudio ou vídeo; faz uma pergunta; e obtém uma resposta fundamentada com citações claras.

A interface inclui uma vista de incorporação 3D para inspecionar o espaço de pesquisa. Cada fonte aparece como um ponto. Quando fazes uma pergunta, a consulta é projetada no mesmo espaço e as fontes citadas são destacadas.

![Diagrama de arquitetura](/assets/apps-img/16fb6a02ed1fd7f4.png)

## O Que Faz

- Adiciona e remove fontes multimodais de um índice local em memória.
- Utiliza Gemini Embedding 2 para incorporações de fontes e consultas.
- Requer `GOOGLE_API_KEY`; a aplicação não utiliza vetores locais ou alternativas de resposta.
- Recupera evidências com similaridade cosseno sobre as incorporações armazenadas.
- Executa um agente Google ADK para coordenar a geração de respostas a partir do contexto recuperado.
- Mostra citações separadamente do texto da resposta, de modo a que os IDs de citação não sobrecarreguem a resposta.
- Projeta vetores de fonte e consulta numa vista PCA 3D para inspeção.

## Arquitetura

| Camada | Função |
| --- | --- |
| Frontend React + Vite | Gestor de fontes, painel de Q&A, citações, rastreio e vista de incorporação 3D |
| Backend FastAPI | Ingestão, recuperação, API de resposta e instantâneas do espaço de incorporação |
| `MultimodalRagStore` | Metadados de fonte em memória, partes, incorporações, pesquisa e projeção PCA |
| Gemini Embedding 2 | Incorporações de fontes e consultas através de modalidades suportadas |
| Agente Google ADK | Coordenador de respostas que recebe o mesmo pacote de recuperação mostrado na interface |

O detalhe importante da implementação é que `/ask` realiza a recuperação uma vez e passa esse mesmo pacote de recuperação para o fluxo de resposta do ADK. A resposta e o painel de citações são, portanto, baseados na mesma evidência classificada.

## Estrutura do Projeto

```text
rag_tutorials/multimodal_agentic_rag/
|-- README.md
|-- assets/
|   `-- multimodal-agentic-rag-architecture.png
|-- backend/
|   |-- app_state.py
|   |-- rag_store.py
|   |-- requirements.txt
|   |-- server.py
|   `-- agentic_rag_agent/
|       |-- __init__.py
|       `-- agent.py
`-- frontend/
    |-- index.html
    |-- package.json
    |-- src/
    |   |-- App.tsx
    |   |-- main.tsx
    |   `-- styles.css
    |-- tsconfig.json
    `-- vite.config.ts
```

## Executar Localmente

Inicia o backend:

```bash
cd rag_tutorials/multimodal_agentic_rag/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export GOOGLE_API_KEY="your-google-ai-studio-key"
python server.py
```

```markdown
O backend corre em:

## Instalação

Para instalar as dependências, corre o seguinte comando:

```bash
npm install
```

## Execução

Para iniciar o servidor, utiliza o seguinte comando:

```bash
npm start
```

O servidor estará disponível em `http://localhost:3000`.

## Endpoints

### GET /api/users

Este endpoint retorna uma lista de utilizadores.

### POST /api/users

Este endpoint cria um novo utilizador. O corpo da requisição deve conter:

```json
{
  "name": "Nome do Utilizador",
  "email": "email@exemplo.com"
}
```

### GET /api/users/:id

Este endpoint retorna os detalhes de um utilizador específico.

## Contribuição

Para contribuir, segue os seguintes passos:

1. Faz um fork do repositório.
2. Cria uma nova branch (`git checkout -b feature/nome-da-feature`).
3. Faz as tuas alterações e commit (`git commit -m 'Adiciona nova feature'`).
4. Faz push para a branch (`git push origin feature/nome-da-feature`).
5. Abre um Pull Request.

## Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro [LICENSE](LICENSE) para mais detalhes.
```

```text
http://localhost:8897
```

```markdown
Inicia o frontend em outro terminal:
```

```bash
cd rag_tutorials/multimodal_agentic_rag/frontend
npm install
npm run dev -- --port 5177
```

# O frontend corre em:

```bash
npm run dev
```

A aplicação estará disponível em `http://localhost:3000`.

## Estrutura do projeto

A estrutura do projeto é a seguinte:

```
/project-root
├── /public
│   └── /images
├── /src
│   ├── /components
│   ├── /pages
│   ├── /styles
│   └── /utils
├── package.json
└── README.md
```

## Instalação

Para instalar as dependências, executa o seguinte comando:

```bash
npm install
```

## Execução

Para executar a aplicação em modo de desenvolvimento, usa:

```bash
npm run dev
```

## Construção

Para construir a aplicação para produção, utiliza:

```bash
npm run build
```

## Testes

Para executar os testes, usa:

```bash
npm test
```

## Contribuição

Se desejas contribuir, por favor, segue estas etapas:

1. Faz um fork do repositório.
2. Cria uma nova branch (`git checkout -b feature/nome-da-sua-feature`).
3. Faz as tuas alterações e commit (`git commit -m 'Adiciona uma nova feature'`).
4. Faz push para a branch (`git push origin feature/nome-da-sua-feature`).
5. Abre um Pull Request.

## Licença

Este projeto está licenciado sob a licença MIT. Veja o ficheiro [LICENSE](LICENSE) para mais detalhes.

```text
http://localhost:5177
```

```markdown
# Se o backend estiver numa porta diferente:

Se o backend estiver a correr numa porta diferente da porta padrão, precisas de especificar a porta ao iniciar a aplicação. Para isso, podes usar a variável de ambiente `BACKEND_PORT`. Por exemplo:

```bash
export BACKEND_PORT=5000
```

Depois, inicia a aplicação normalmente. A aplicação irá agora comunicar com o backend na porta que especificaste.

## Exemplos de configuração

Aqui estão alguns exemplos de como configurar a porta do backend:

### Exemplo 1: Usar a linha de comandos

```bash
BACKEND_PORT=5000 npm start
```

### Exemplo 2: Usar um ficheiro `.env`

Cria um ficheiro chamado `.env` na raiz do teu projeto e adiciona a seguinte linha:

```
BACKEND_PORT=5000
```

### Exemplo 3: Usar um script de inicialização

Se estiveres a usar um script para iniciar a aplicação, podes definir a variável de ambiente diretamente no script:

```bash
#!/bin/bash
export BACKEND_PORT=5000
npm start
```

## Verificação da configuração

Para verificar se a configuração foi aplicada corretamente, podes usar o seguinte comando:

```bash
echo $BACKEND_PORT
```

Isto deve retornar a porta que definiste. Se não retornar nada, verifica se a variável de ambiente foi definida corretamente.
```

```bash
VITE_API_URL=http://localhost:8897 npm run dev -- --port 5177
```

## Experimenta

1. Abre `http://localhost:5177`.
2. Adiciona uma fonte de texto, URL, PDF, imagem, áudio ou vídeo.
3. Faz uma pergunta no painel de Q&A.
4. Revê a resposta e as citações.
5. Inspeciona a fonte e os pontos de consulta na vista de embedding.

## API

| Método | Endpoint | Descrição |
| --- | --- | --- |
| `GET` | `/health` | Estado do backend, disponibilidade do ADK, fornecedor, dimensões e contagens de fontes |
| `GET` | `/space` | Fontes atuais, pontos projetados, trilha de eventos e metadados de projeção |
| `POST` | `/sources/text` | Adiciona uma fonte de texto |
| `POST` | `/sources/url` | Busca e indexa uma URL pública |
| `POST` | `/sources/file` | Carrega e indexa um PDF, imagem, áudio ou vídeo |
| `DELETE` | `/sources/{source_id}` | Remove uma fonte e os seus chunks |
| `POST` | `/ask` | Recupera evidências, executa o fluxo de resposta do ADK e retorna citações |

## Notas

- O armazenamento é em memória. Reiniciar o backend redefine o índice da demonstração.
- A ingestão de URLs bloqueia localhost e intervalos de IP privados, a menos que `ALLOW_PRIVATE_URLS=true` esteja definido.
- Os ficheiros de média carregados através da Gemini File API são limpos após o embedding.
- O processamento de média bloqueante é executado num threadpool para que o loop de eventos do FastAPI não fique retido.
- Para produção, substitui o armazenamento em memória por armazenamento durável e adiciona autenticação, ingestão em segundo plano, avaliações, observabilidade e uma base de dados de vetores gerida.

## 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/multimodal-agentic-rag