🧠 VetorizaBR

Treinamento de embeddings em português com CBOW e Skip-Gram + Negative Sampling, com integração total a banco de dados e pipeline automatizado.

---

🌐 Visão Geral

O VetorizaBR é um sistema completo de geração, treinamento e persistência de word embeddings em português. Com base em modelos clássicos como CBOW e Skip-Gram, o sistema permite:

• Processar textos de forma eficiente e escalável;
• Construir um vocabulário limpo e normalizado;
• Gerar pares de treinamento para modelos de embedding;
• Treinar embeddings com suporte a GPU e negative sampling;
• Persistir os vetores em um banco SQLite normalizado;
• Consultar os vetores posteriormente para qualquer palavra do vocabulário.

---

⚔️ CBOW vs Skip-Gram

Característica	CBOW	Skip-Gram
Entrada	Palavras de contexto	Palavra alvo
Saída	Palavra central	Palavras de contexto
Vantagem	Rápido com grandes volumes de dados	Melhor com dados esparsos
Ideal para	Vocabulário frequente	Vocabulário raro
Pares gerados	1 contexto → 1 alvo	1 alvo → múltiplos contextos

---

🗂️ Estrutura do Projeto

text-embedding/
├── data/
|   ├──database/
│   |   └── database.py         ← Interface com banco SQLite
|   └── pt_words/
│       └── database.py         ← Arquivo com palavras do idioma
├── src/
│   ├── ML/
│   │   ├── SkipGram.py     # Implementação do modelo Skip-Gram
│   │   └── CBOW.py         # Implementação do modelo CBOW
│   ├── TextProcessor.py    # Processamento e limpeza dos textos
│   └── embedding.py        # Classe principal VetorizaBR e pipeline de treinamento
├── utils/
│   ├── imports.py          # Imports utilitários e configuração de logging
│   └── dimension_reduction/
│       └── PCA.py          # Redução de dimensionalidade (opcional)
├── README.md

---

📊 Esquema Visual do Banco de Dados

+------------------------+                   +------------------------------+                   +------------------------+
|       document         |                   |      document_word_link     |                   |         word           |
+------------------------+                   +------------------------------+                   +------------------------+
| id_document (PK)       |◄────────────┐     | doc_id (FK → document)      |     ┌────────────►| id_word (PK)           |
| document_text (UNIQ)   |             └────►| word_id (FK → word)         |◄────┘             | word_text (UNIQ)       |
+------------------------+                   | PRIMARY KEY (doc_id, word_id)|                   +------------------------+
                                             +------------------------------+

+-------------------+                         +-------------------+
|    stop_word      |                         |     pt_word       |
+-------------------+                         +-------------------+
| word_text (PK)    |                         | word_text (PK)    |
+-------------------+                         +-------------------+

---

⚙️ Instalação

1. Pré-requisitos

• Python 3.10+
• Conexão à internet no primeiro uso (download do database)
• GPU CUDA (opcional, mas recomendado)

Instale as dependências:

# Crie um ambiente virtual:
python -m venv venv

# Linux
source venv/bin/activate 
# Windows
./venv/scripts/activate

# Instale as dependências
pip install -r requirements.txt

2. Configuração do .env

Crie um arquivo .env na raiz do projeto com as variáveis abaixo:

DATABASE_PATH=./data/db
PT_WORDS_PATH=./data/pt_words.txt
HUGGING_FACE=seu_token_huggingface

---

3. Preparação dos Dados

• Os textos são extraídos automaticamente do dataset OSCAR via HuggingFace.
• O vocabulário é extraído dos textos presentes no banco e do arquivo pt_words.txt.

---

4. Executar a pipeline principal

python -m src.embedding

---

🚀 Exemplo de Uso

Treinamento de Embeddings com CBOW

from src.embedding import VetorizaBR

modelo = VetorizaBR(
    embedding_dim=100,
    epochs=5,
    neg_samples=5,
    batch_size=128,
    window_size=2
)

modelo.process_and_train(model_type="cbow")  # ou "skipgram"
modelo.save_embeddings()

Consulta de Embeddings

vetor = modelo.get_embedding("educação")
print(vetor)

---

🔎 Principais Classes

• VetorizaBR: Pipeline completo de processamento, treinamento e persistência dos embeddings.
• TextProcessor: Responsável por extrair e limpar sentenças do banco de dados.
• SkipGram / CBOW: Modelos de embedding com geração de pares para treinamento.
• Database: Interface para acesso e atualização do banco de dados.

---

🧩 Parâmetros e Configurações

Parâmetro	Descrição	Padrão
embedding_dim	Dimensão dos vetores de embedding	100
epochs	Número de épocas de treinamento	5
lr	Taxa de aprendizado	0.025
neg_samples	Número de amostras negativas	5
window_size	Tamanho da janela de contexto	2
batch_size	Tamanho do batch para treinamento	128

---

🛠️ Dicas e Observações

• O tamanho do batch pode ser ajustado conforme a memória disponível na GPU.
• O pipeline está preparado para paralelismo máximo em GPU, mas também funciona em CPU.
• O vocabulário e os embeddings são persistidos no banco de dados para fácil reutilização.
• O projeto utiliza logging colorido para facilitar o acompanhamento do pipeline.
• O banco de dados é criado e populado automaticamente na primeira execução.

---

🤝 Como Contribuir

Contribuições são bem-vindas! Siga os passos abaixo:

1. Fork este repositório
2. Crie uma nova branch: git checkout -b minha-feature
3. Faça suas alterações e commit: git commit -m 'Minha contribuição'
4. Push na sua branch: git push origin minha-feature
5. Abra um Pull Request

---

📚 Recursos Relacionados

• Mikolov et al., 2013 - Word2Vec
• GloVe: Global Vectors for Word Representation
• OSCAR Dataset (HuggingFace)
• Negative Sampling Explained (Blog)

---

🪪 Licença e Versão

---

Projeto acadêmico para PLN em língua portuguesa.