Um chatbot inteligente baseado em Retrieval-Augmented Generation (RAG) capaz de responder perguntas sobre a história e participação da Seleção Brasileira nas Copas do Mundo FIFA (geral de todas as edições), utilizando documentos da Wikipedia como base de conhecimento e o Google Gemini para geração de respostas contextualizadas.
O BrasilnaCopaAI é um projeto de portfólio desenvolvido com foco em Inteligência Artificial Generativa e Engenharia de Dados.
Ao invés de depender do conhecimento padrão (e estático) de um modelo de linguagem, o sistema realiza buscas semânticas em um banco vetorial local contendo documentos extraídos da Wikipedia sobre a Seleção Brasileira nas Copas do Mundo. Apenas os trechos mais relevantes são enviados ao modelo generativo (Google Gemini), garantindo respostas confiáveis, contextualizadas e sem alucinações.
O chatbot responderá perguntas exclusivamente sobre:
- Seleção Brasileira: Jogadores convocados, comissão técnica e histórico.
- Partidas & Desempenho: Grupos, fases da competição, adversários e estatísticas presentes nos documentos.
Important
Toda resposta gerada deve ter embasamento nos documentos indexados. Caso a informação não conste na base, o chatbot informará que não possui tal conhecimento, evitando inventar fatos.
O projeto é dividido em dois serviços independentes que se comunicam via HTTP/JSON:
[Usuário] ──> [Interface Streamlit] ──(HTTP)──> [Backend FastAPI]
│
┌─────────────────┴─────────────────┐
▼ ▼
[LangChain + ChromaDB] [Google Gemini API]
Para mais detalhes sobre os fluxos de ingestão de dados e execução do pipeline RAG, consulte a Documentação de Arquitetura.
- Core: Python 3.12+
- Backend: FastAPI, Uvicorn, Pydantic
- Frontend: Streamlit
- IA & Orquestração: LangChain e Google Gemini API
- Banco Vetorial: ChromaDB
- Processamento de Dados: Wikipedia API, Beautiful Soup, Pandas
BrasilnaCopaAI/
├── app/ # Código fonte do Backend (FastAPI)
│ ├── api/ # Rotas e controladores de endpoints
│ ├── ingestion/ # Coleta e processamento dos textos
│ ├── models/ # Esquemas de dados (Pydantic)
│ ├── rag/ # Orquestração RAG (LangChain)
│ ├── services/ # Integrações externas (Gemini/Wiki)
│ └── vectorstore/ # Configuração do banco vetorial
├── streamlit/ # Código fonte da Interface Web
├── data/ # Bases de dados locais (raw, processed, db)
├── docs/ # Documentação detalhada do projeto
├── tests/ # Testes automatizados (pytest)
└── requirements.txt # Dependências do projeto
Você pode executar o projeto de duas maneiras: utilizando o Docker Compose (método recomendado, automatizado e multiplataforma) ou manualmente (configurando o ambiente virtual Python local).
Este é o método mais simples e rápido. O Docker se encarrega de instalar todas as dependências, baixar o modelo local de embeddings (se configurado) e rodar o pipeline de ingestão e indexação do ChromaDB de forma 100% automatizada no primeiro boot.
- Docker e Docker Compose instalados na máquina.
- Chave de API do Google Gemini.
Crie um arquivo .env na raiz do projeto com as chaves necessárias (baseando-se no .env.example):
GEMINI_API_KEY=sua_chave_aqui
USE_LOCAL_EMBEDDINGS=trueNa raiz do repositório, execute:
docker compose up --buildAguarde a inicialização. O frontend Streamlit estará disponível em http://localhost:8501 e o backend FastAPI Swagger em http://localhost:8000/docs.
Para mais detalhes sobre comandos e persistência de dados, consulte o Guia de Execução com Docker.
- Python 3.12 ou superior instalado localmente.
- Chave de API do Google Gemini.
git clone https://github.com/DanielDPereira/BrasilnaCopaAI.git
cd BrasilnaCopaAINo Windows:
python -m venv .venv
.venv\Scripts\activateNo Linux/macOS:
python3 -m venv .venv
source .venv/bin/activatepip install -r requirements.txtCrie um arquivo .env na raiz do projeto baseado no .env.example:
# Chave da API do Google Gemini
GEMINI_API_KEY=sua_chave_aqui
# (Opcional) Múltiplas chaves separadas por vírgula para tolerância a falhas
GEMINI_API_KEYS=chave_1,chave_2,chave_3
# Configuração para rodar offline / economizar cota da API (true/false)
USE_LOCAL_EMBEDDINGS=true
# Caminho do banco vetorial
CHROMA_DB_PATH=data/dbPara rodar sem depender das quotas de API do Gemini para embeddings, você deve baixar o modelo local executando:
python scripts/download_local_model.pyIsso baixará automaticamente os arquivos model.onnx e tokenizer.json do Hugging Face para a pasta data/models/.
Para que o RAG funcione, você precisa coletar e popular o banco de dados vetorial local:
- Executar a Coleta e Limpeza (Wikipedia):
python -m app.ingestion.run
- Executar a Carga no Banco Vetorial (ChromaDB):
python -m app.vectorstore.populate
uvicorn app.main:app --reload --reload-dir app- O backend rodará em
http://localhost:8000. - Acesse a documentação Swagger interativa em
http://localhost:8000/docs.
Em um novo terminal com o ambiente virtual ativado:
streamlit run streamlit/app.pyA interface do chat abrirá automaticamente no seu navegador padrão (em http://localhost:8501).
Para aprofundar-se no projeto, consulte os guias disponíveis na pasta docs/:
- 🏗️ Arquitetura Detalhada: Entenda os fluxos detalhados de ingestão de dados, busca vetorial e prompt engineering.
- 🐳 Execução com Docker: Detalhes sobre o empacotamento, volumes e comando docker compose.
- ⚙️ Guia de Desenvolvimento e Convenções: Padrões de código, Conventional Commits, branches (Git Flow) e como rodar a suíte de testes.
- 🧪 Testes e Refinamentos (Épico 8): Detalhes das métricas de qualidade, suíte de 29 testes unitários/integrados e resiliência de chaves.
- 📋 Planejamento, Roadmap e Backlog: Acompanhe o roadmap das 8 fases do projeto, as listas de tarefas (Tasks) por épicos e as definições de pronto (DoD).
- Autor: Daniel Dias Pereira
- Licença: Distribuído sob a licença MIT. Veja o arquivo
LICENSEpara mais detalhes.