🏆 Projeto desenvolvido para o curso LLM Zoomcamp da DataTalks.Club
🇬🇧 This README is also available in English.
Os aplicativos de identificação de aves existentes funcionam, em geral, com fotos ou sons. No entanto, nem sempre o observador consegue registrar uma imagem ou gravação no momento do avistamento. Nessas situações, a única referência disponível é a descrição visual da ave, como por exemplo: cor, tamanho, formato do bico ou comportamento. O AvesRAG foi criado para atender exatamente esse cenário, permitindo a identificação de aves a partir de descrições em texto.
O AvesRAG Assistant é um assistente inteligente interativo busca resolver esse problema, ele capaz de identificar aves com base em descrições fornecidas pelo usuário. Utilizando a técnica de RAG (Retrieval-Augmented Generation), ele busca informações em uma base de dados personalizada e retorna até 3 espécies candidatas com descrições resumidas.
- Criar uma ferramenta interativa para identificação de aves.
- Utilizar RAG para combinar busca estruturada e geração de texto por LLM.
- Garantir que o backend e o pipeline sejam modulares e fáceis de adaptar.
- Coletar feedback dos usuários para melhorar continuamente os resultados.
- Monitorar o uso da api de LLM.
A base de dados utilizada foi criada a partir de:
- Integração de bases já existentes.
- Scraping de fontes online.
- Parametrização de dados via LLM*.
📂 Repositório do construtor da base: ➡ rafaelladuarte/avesrag-dataset-builder
✅ Entrada de dados via formulário com validação .
✅ Busca otimizada com MinSearch (semântica + textual).
✅ Retorno de até 3 espécies candidatas.
✅ Resumo automático das espécies com imagens.
✅ Coleta de feedback do usuário
🔄 Monitoramento do uso da LLM - API.
-
Testes realizados:
- BM25 (textual)
- Vetorial (embeddings)
- Busca híbrida (melhor resultado)
-
Resultado: busca híbrida apresentou maior recall e precisão para descrições curtas.
- Avaliados diferentes modelos open-source.
llama-3.1-8b-instantgemma2-9b-itdeepseek-r1-distill-llama-70b
- Testados prompts zero-shot vs few-shot.
- Resultado:
llama-3.1-8b-instantcom few-shot teve melhor equilíbrio entre custo e precisão.
- Coleta de feedback de usuários (sim/não sobre utilidade da resposta).
- Armazenamento em PostgreSQL
- Dashboard no Streamlit com métricas:
- Nº de consultas
- Espécies mais buscadas
- Taxa de respostas aceitas
- Tempo médio de resposta
| Categoria | Ferramentas |
|---|---|
| Linguagem | Python 3.11+ |
| Framework Web | Streamlit |
| LLM (Assistente) | llama-3.1-8b-instant |
| LLMs (Base de dados) | gemma2-9b-it, deepseek-r1-distill-llama-70b, llama-3.1-8b-instant |
| Backend de Busca | MinSearch (adaptado) |
| API LLM | Groq API |
| Processamento | pandas, numpy |
| Controle de Versão | Git + GitHub |
📦 avesrag-assistant
├── app/ # Código-fonte da aplicação Streamlit
│ ├── app.py # Arquivo principal da aplicação
│ ├── dev.py # Script auxiliar para desenvolvimento e testes locais
│ ├── Dockerfile # Define como construir a imagem Docker da aplicação
│ ├── entrypoint.sh # Script de inicialização do container (ex: espera pelo DB)
│ ├── requirements.txt # Dependências Python da aplicação
│ └── script/ # Scripts auxiliares da aplicação
├── db/ # Scripts para inicialização e manutenção do banco de dados
│ └── init.sql # Script SQL para criar tabelas e dados iniciais
├── docker-compose.yml # Orquestração de containers Docker (app + banco + serviços)
├── docs/ # Documentação e materiais de apoio
│ ├── images/ # Imagens usadas na documentação
│ ├── note/ # Anotações, rascunhos e referências
│ └── notebooks/ # Jupyter Notebooks de análises e experimentos
├── monitoring/ # Configuração de monitoramento da aplicação (em desenvolvimento)
├── Pipfile # Definições de dependências via Pipenv
├── Pipfile.lock # Lockfile de dependências do Pipenv
├── README.md # Documentação principal (Português)
├── README.en.md # Documentação principal (Inglês)
└── requirements.txt # Alternativa de dependências para instalação via pip
git clone https://github.com/usuario/avesrag-assistant.git
cd avesrag-assistantCrie um arquivo .env com:
GROQ_API_KEY1="yourkeyhere"
GROQ_API_KEY2="yourkeyhere"
POSTGRES_URI="postgres://username:password@avesrag_db:5432/avesrag"
POSTGRES_USER="username"
POSTGRES_PASSWORD="password"
POSTGRES_DB="avesrag"
POSTGRES_HOST="avesrag_db"
O Docker Compose irá ler este arquivo para configurar os containers.
No diretório raiz do projeto:
docker compose up --buildIsso irá:
- Construir a imagem da aplicação.
- Subir o container da aplicação (
avesrag_app) e do banco (avesrag_db) automaticamente.
Depois que os containers estiverem rodando, abra no navegador:
http://localhost:8501
docker compose downIsso para e remove os containers, mas mantém o banco de dados salvo no volume definido no
docker-compose.yml.
- Problema descrito claramente
- Knowledge base + LLM no fluxo
- Avaliação de múltiplos retrieval flows
- Avaliação de diferentes prompts/modelos
- Interface em Streamlit
- Ingestão automatizada via scripts Python
- Monitoramento de feedback
- Monitoramento do uso do LLM + dashboard
- Containerização com Docker
- Reprodutibilidade (instruções + requirements)
- 🔧 Ajustar pesos e parâmetros de busca no MinSearch
- 🐦 Expandir base para mais espécies brasileiras
- 🧪 Criar testes unitários e de integração
- 📊 Adicionar logging e monitoramento de consultas
Distribuído sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.