README.md

---
title: Training CPU
emoji: 🧠
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# 🧠 CPU Fine-Tuning Interface

**[EN]** A complete web interface for fine-tuning language models on CPU using LoRA/PEFT, with dataset creation, training monitoring, model evaluation chat, and GGUF export.

**[PT]** Interface web completa para fine-tuning de modelos de linguagem em CPU com LoRA/PEFT, criação de datasets, monitorização do treino, chat de avaliação e exportação GGUF.

---

## 🇬🇧 English

### Features

- **Dynamic Configuration** — displays hardware info and training parameters loaded from `app.py` (read-only)
- **GGUF Converter** — converts merged model to GGUF format (F16 original size or Q8_0 ~50% size)
- **Dataset Creator** — processes PDF, TXT, DOCX, MD, JSONL and MediaWiki XML files into training datasets
- **Train AI** — start, monitor and control fine-tuning with LoRA on CPU
- **Training Logs** — real-time log viewer with progress bar and ETA
- **Model Chat** — evaluate the trained model directly in the interface after merge
- **Output Directory** — browse and download all generated files

### How to Use

1. **Configure** — the left panel shows your current hardware and training parameters
2. **Create Dataset** — upload a document and configure chunking, schema and cleaning options
3. **Train** — enter the base model path and training files, set epochs and click **Start Training**
4. **Monitor** — watch the progress bar, step counter, elapsed time and ETA in real time
5. **Merge** — after training completes, click **Merge** to combine base model + LoRA adapter
6. **Chat** — test the merged model directly in the chat panel
7. **Export GGUF** — convert to GGUF for use with llama.cpp, Ollama or LM Studio

### Supported Input Formats (Dataset)

| Format | Description |
|--------|-------------|
| `.pdf` | PDF documents (text extraction + optional OCR) |
| `.txt` | Plain text files |
| `.docx` | Microsoft Word documents |
| `.md` | Markdown files |
| `.jsonl` | Existing JSONL datasets (passthrough + cleaning) |
| `.xml` | MediaWiki dumps (Wikipedia, government wikis) |

### Dataset Schemas

| Schema | Description |
|--------|-------------|
| `text` | Plain text only — simplest format |
| `lite` | Text + basic metadata (id, doc_id) |
| `full` | Everything including tables and extraction method |
| `prompt_completion` | Instruction/response format for directed fine-tuning |

### GGUF Export

After merging, enter the merged model path and choose:
- **F16** — original size, full precision, best quality
- **Q8_0** — ~50% smaller, near-lossless quality, faster inference

Requires `convert_hf_to_gguf.py` and `gguf-py/` folder in the Space root (from [llama.cpp](https://github.com/ggml-org/llama.cpp)).

### Technical Stack

- **Backend**: Flask + Python
- **Training**: HuggingFace Transformers + PEFT (LoRA)
- **Dataset**: Custom processor (PyMuPDF, python-docx, pandas)
- **Frontend**: Vanilla JS + Tailwind CSS
- **Hardware**: CPU-only (optimised for multi-core, dynamic RAM management)

### Notes

- This Space is designed for **testing and portfolio demonstration**
- For serious training, use a GPU or a local machine with XPU/CUDA
- Training a 1B parameter model on CPU takes approximately 100–150 hours per epoch
- The dynamic accumulation system automatically adjusts gradient accumulation based on available RAM

---

## 🇵🇹 Português

### Funcionalidades

- **Configuração Dinâmica** — mostra informação de hardware e parâmetros de treino carregados do `app.py` (só leitura)
- **Conversor GGUF** — converte modelo merged para formato GGUF (F16 tamanho original ou Q8_0 ~50% do tamanho)
- **Criador de Datasets** — processa ficheiros PDF, TXT, DOCX, MD, JSONL e XML MediaWiki em datasets de treino
- **Treinar IA** — iniciar, monitorizar e controlar o fine-tuning com LoRA em CPU
- **Logs de Treino** — visualizador de logs em tempo real com barra de progresso e ETA
- **Chat do Modelo** — avaliar o modelo treinado directamente na interface após merge
- **Directório de Output** — navegar e descarregar todos os ficheiros gerados

### Como Usar

1. **Configurar** — o painel esquerdo mostra o teu hardware actual e parâmetros de treino
2. **Criar Dataset** — carrega um documento e configura chunking, schema e opções de limpeza
3. **Treinar** — introduz o caminho do modelo base e ficheiros de treino, define as épocas e clica em **Start Training**
4. **Monitorizar** — acompanha a barra de progresso, contador de passos, tempo decorrido e ETA em tempo real
5. **Merge** — após o treino terminar, clica em **Merge** para combinar modelo base + adaptador LoRA
6. **Chat** — testa o modelo merged directamente no painel de chat
7. **Exportar GGUF** — converte para GGUF para uso com llama.cpp, Ollama ou LM Studio

### Formatos de Entrada Suportados (Dataset)

| Formato | Descrição |
|---------|-----------|
| `.pdf` | Documentos PDF (extracção de texto + OCR opcional) |
| `.txt` | Ficheiros de texto simples |
| `.docx` | Documentos Microsoft Word |
| `.md` | Ficheiros Markdown |
| `.jsonl` | Datasets JSONL existentes (passthrough + limpeza) |
| `.xml` | Dumps MediaWiki (Wikipedia, wikis governamentais) |

### Schemas de Dataset

| Schema | Descrição |
|--------|-----------|
| `text` | Só texto — formato mais simples |
| `lite` | Texto + metadados básicos (id, doc_id) |
| `full` | Tudo incluindo tabelas e método de extracção |
| `prompt_completion` | Formato instrução/resposta para fine-tuning dirigido |

### Exportação GGUF

Após o merge, introduz o caminho do modelo merged e escolhe:
- **F16** — tamanho original, precisão total, melhor qualidade
- **Q8_0** — ~50% menor, qualidade quase sem perda, inferência mais rápida

Requer `convert_hf_to_gguf.py` e pasta `gguf-py/` na raiz do Space (do repositório [llama.cpp](https://github.com/ggml-org/llama.cpp)).

### Stack Técnico

- **Backend**: Flask + Python
- **Treino**: HuggingFace Transformers + PEFT (LoRA)
- **Dataset**: Processador personalizado (PyMuPDF, python-docx, pandas)
- **Frontend**: Vanilla JS + Tailwind CSS
- **Hardware**: CPU apenas (optimizado para multi-core, gestão dinâmica de RAM)

### Notas

- Este Space foi criado para **testes e demonstração de portfolio**
- Para treino sério, usa uma GPU ou máquina local com XPU/CUDA
- Treinar um modelo de 1B parâmetros em CPU demora aproximadamente 100–150 horas por época
- O sistema de acumulação dinâmica ajusta automaticamente o gradient accumulation com base na RAM disponível

---

## 📁 File Structure / Estrutura de Ficheiros

```
app.py                      # Main Flask application
config_manager.py           # Dynamic configuration manager
pdf_txt_to_dataset.py       # Dataset processor
dataset_endpoints.py        # Dataset API endpoints
gguf_endpoints.py           # GGUF conversion endpoints
convert_hf_to_gguf.py       # llama.cpp conversion script
gguf-py/                    # llama.cpp GGUF library
requirements.txt            # Python dependencies
templates/
  index.html                # Web interface
```

## 📦 Dependencies / Dependências

```
torch (CPU)
transformers
peft
accelerate
datasets
flask
pymupdf
pandas
python-docx
gguf
sentencepiece
tensorboard
psutil
py-cpuinfo
```

---

*Built with ❤️ for CPU fine-tuning experimentation*