RAG Agente Multimodal

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.

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

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

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:

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

O backend corre em:

Instalação

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

npm install

Execução

Para iniciar o servidor, utiliza o seguinte comando:

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:

{
  "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.

http://localhost:8897

Inicia o frontend em outro terminal:

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

O frontend corre em:

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:

npm install

Execução

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

npm run dev

Construção

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

npm run build

Testes

Para executar os testes, usa:

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.

http://localhost:5177

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:

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

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:

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.

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

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.