|
|
--- |
|
|
language: en |
|
|
library_name: transformers |
|
|
license: mit |
|
|
tags: |
|
|
- finetuning |
|
|
- lora |
|
|
- qlora |
|
|
- unsloth |
|
|
- gpu |
|
|
- distributed |
|
|
datasets: |
|
|
- wikitext |
|
|
pipeline_tag: text-generation |
|
|
model-index: |
|
|
- name: Humigence |
|
|
results: |
|
|
- task: |
|
|
type: text-generation |
|
|
dataset: |
|
|
name: WikiText-2 |
|
|
type: wikitext |
|
|
metrics: |
|
|
- type: loss |
|
|
value: 1.50 |
|
|
--- |
|
|
|
|
|
# 🧠 Humigence CLI |
|
|
|
|
|
**Your AI. Your pipeline. Zero code.** |
|
|
|
|
|
A complete MLOps suite built for makers, teams, and enterprises. Humigence provides zero-config, GPU-aware fine-tuning with surgical precision and complete reproducibility. |
|
|
|
|
|
## ✨ Key Features |
|
|
|
|
|
- 🎯 **Interactive Wizard**: Step-by-step configuration with Basic/Advanced modes |
|
|
- 🖥️ **Smart GPU Detection**: Automatic detection and selection of available GPUs |
|
|
- 🚀 **Dual-GPU Training**: Multi-GPU support with Unsloth + TorchRun |
|
|
- 🧪 **Training Recipes**: QLoRA (4-bit), LoRA (FP16/BF16), Full Fine-tuning |
|
|
- 📊 **Intelligent Batching**: Auto-fit batch size to available VRAM |
|
|
- 🔄 **Complete Reproducibility**: Config snapshots and reproduce scripts |
|
|
- 📈 **Built-in Evaluation**: Curated prompts and quality gates |
|
|
- 📦 **Artifact Export**: Structured outputs with run summaries |
|
|
|
|
|
## 🚀 Quick Start |
|
|
|
|
|
### Prerequisites |
|
|
|
|
|
- **GPU**: NVIDIA GPU with CUDA support (RTX 5090, RTX 4080, etc.) |
|
|
- **RAM**: 8GB+ recommended |
|
|
- **Storage**: 10GB+ for models and datasets |
|
|
- **Python**: 3.8+ with PyTorch |
|
|
|
|
|
### Installation |
|
|
|
|
|
```bash |
|
|
# Clone the repository |
|
|
git clone https://github.com/your-username/humigence.git |
|
|
cd humigence |
|
|
|
|
|
# Install dependencies |
|
|
pip install -r requirements.txt |
|
|
|
|
|
# Set up Unsloth (required for training) |
|
|
python3 training/unsloth/setup_humigence_unsloth.py |
|
|
|
|
|
# Launch the interactive wizard |
|
|
python3 cli/main.py |
|
|
``` |
|
|
|
|
|
### Basic Usage |
|
|
|
|
|
```bash |
|
|
# Launch the interactive wizard |
|
|
python3 cli/main.py |
|
|
|
|
|
# The wizard will guide you through: |
|
|
# 1. Model selection |
|
|
# 2. Dataset configuration |
|
|
# 3. Training parameters |
|
|
# 4. GPU selection (single or multi-GPU) |
|
|
# 5. Launch training |
|
|
``` |
|
|
|
|
|
## 🎯 Training Workflow |
|
|
|
|
|
### 1. Interactive Setup |
|
|
|
|
|
The Humigence wizard guides you through: |
|
|
|
|
|
- **Setup Mode**: Basic (essential config) or Advanced (full control) |
|
|
- **Hardware Detection**: Automatic GPU, CPU, and memory detection |
|
|
- **Model Selection**: Choose from supported models or custom paths |
|
|
- **Dataset Loading**: Auto-detection from `~/humigence_data/` or custom paths |
|
|
- **Training Recipe**: QLoRA, LoRA, or Full Fine-tuning |
|
|
- **GPU Selection**: Single-GPU auto-selection or multi-GPU prompting |
|
|
|
|
|
### 2. GPU Selection |
|
|
|
|
|
Humigence intelligently handles GPU selection: |
|
|
|
|
|
- **Single GPU**: Automatically selects and uses the available GPU |
|
|
- **Multiple GPUs**: Prompts you to choose: |
|
|
``` |
|
|
🔧 Training Mode: |
|
|
> Multi-GPU Training (all available GPUs) |
|
|
Single GPU Training (choose specific GPU) |
|
|
``` |
|
|
|
|
|
### 3. Training Execution |
|
|
|
|
|
```bash |
|
|
🚀 Humigence Training Starting... |
|
|
✅ Configuration Loaded: [all settings] |
|
|
🖥️ GPU Detection: 2x RTX 5090 detected |
|
|
🔧 Training Mode: Multi-GPU Training |
|
|
📦 Loading model: Qwen/Qwen2.5-0.5B |
|
|
✅ LoRA adapters applied |
|
|
📚 Loading dataset: wikitext2 (10,000 samples) |
|
|
🚀 Starting training with TorchRun... |
|
|
✅ Training complete — adapters saved. |
|
|
``` |
|
|
|
|
|
## 📊 Supported Models |
|
|
|
|
|
- **Qwen/Qwen2.5-0.5B**: 77M parameters (recommended for testing) |
|
|
- **microsoft/Phi-2**: 839M parameters |
|
|
- **TinyLlama/TinyLlama-1.1B-Chat-v1.0**: 369M parameters |
|
|
- **Custom Models**: Any HuggingFace model or local path |
|
|
|
|
|
## 🗂️ Dataset Support |
|
|
|
|
|
- **JSONL Format**: Line-by-line JSON with instruction/output pairs |
|
|
- **Auto-Detection**: Scans `~/humigence_data/` directory |
|
|
- **Custom Paths**: Specify any local dataset file |
|
|
- **Sample Datasets**: Includes demo datasets for testing |
|
|
|
|
|
### Dataset Format |
|
|
|
|
|
```json |
|
|
{"instruction": "What is machine learning?", "output": "Machine learning is a subset of artificial intelligence..."} |
|
|
{"instruction": "Explain quantum computing", "output": "Quantum computing uses quantum mechanical phenomena..."} |
|
|
``` |
|
|
|
|
|
## 🖥️ Hardware Requirements |
|
|
|
|
|
### Minimum Requirements |
|
|
- **GPU**: NVIDIA GPU with 8GB+ VRAM |
|
|
- **RAM**: 16GB+ system RAM |
|
|
- **Storage**: 20GB+ free space |
|
|
|
|
|
### Recommended Setup |
|
|
- **GPU**: RTX 4080/4090/5090 or better |
|
|
- **RAM**: 32GB+ system RAM |
|
|
- **Storage**: 50GB+ free space |
|
|
|
|
|
### Multi-GPU Support |
|
|
- **Dual-GPU**: RTX 5090 + RTX 5090 (tested) |
|
|
- **Memory**: 16GB+ VRAM per GPU recommended |
|
|
- **Training**: Automatic TorchRun distribution |
|
|
|
|
|
## 📁 Project Structure |
|
|
|
|
|
``` |
|
|
humigence/ |
|
|
├── cli/ |
|
|
│ ├── main.py # Main CLI entry point |
|
|
│ ├── config_wizard.py # Interactive configuration wizard |
|
|
│ └── lora_wizard.py # LoRA-specific wizard |
|
|
├── training/ |
|
|
│ └── unsloth/ # Unsloth integration |
|
|
│ ├── wizard.py # Unsloth training wizard |
|
|
│ └── train_lora_dual.py # Multi-GPU training script |
|
|
├── pipelines/ |
|
|
│ └── lora_trainer.py # Training pipeline |
|
|
├── utils/ |
|
|
│ ├── device.py # Hardware detection |
|
|
│ ├── dataset_loader.py # Dataset utilities |
|
|
│ └── validators.py # Data validation |
|
|
├── config/ |
|
|
│ └── default_config.json # Default configuration |
|
|
└── runs/ # Training outputs |
|
|
└── humigence/ |
|
|
├── config.snapshot.json |
|
|
├── adapters/ # LoRA weights |
|
|
└── artifacts.zip # Complete export |
|
|
``` |
|
|
|
|
|
## 🔧 Configuration |
|
|
|
|
|
### Basic Mode (Recommended) |
|
|
|
|
|
Essential configuration with sensible defaults: |
|
|
|
|
|
- **Learning Rate**: 2e-4 |
|
|
- **Epochs**: 1 |
|
|
- **Gradient Accumulation**: 4 |
|
|
- **LoRA Rank**: 16 |
|
|
- **LoRA Alpha**: 32 |
|
|
|
|
|
### Advanced Mode |
|
|
|
|
|
Full control over all parameters: |
|
|
|
|
|
- LoRA configuration (rank, alpha, dropout) |
|
|
- Training hyperparameters |
|
|
- Data processing options |
|
|
- Evaluation settings |
|
|
|
|
|
## 🚀 Training Modes |
|
|
|
|
|
### Single-GPU Training |
|
|
|
|
|
```bash |
|
|
# Automatically selected when 1 GPU detected |
|
|
🔧 Single GPU detected - using GPU 0: RTX 5090 |
|
|
🚀 Launching single-GPU training... |
|
|
``` |
|
|
|
|
|
### Multi-GPU Training |
|
|
|
|
|
```bash |
|
|
# Prompts when multiple GPUs detected |
|
|
🔧 2 GPUs detected - choose training mode |
|
|
> Multi-GPU Training (all available GPUs) |
|
|
Single GPU Training (choose specific GPU) |
|
|
``` |
|
|
|
|
|
## 📈 Evaluation & Monitoring |
|
|
|
|
|
### Built-in Evaluation |
|
|
|
|
|
- **Curated Prompts**: 5 diverse evaluation questions |
|
|
- **Model Inference**: Generation with temperature sampling |
|
|
- **Quality Gates**: Loss thresholds and evaluation metrics |
|
|
- **Status Tracking**: ACCEPTED.txt or REJECTED.txt files |
|
|
|
|
|
### Run Monitoring |
|
|
|
|
|
```bash |
|
|
# View training progress |
|
|
tail -f runs/humigence/training.log |
|
|
|
|
|
# Check evaluation results |
|
|
cat runs/humigence/eval_results.jsonl |
|
|
|
|
|
# View run summary |
|
|
cat runs/humigence/run_summary.json |
|
|
``` |
|
|
|
|
|
## 🔄 Reproducibility |
|
|
|
|
|
Every training run generates: |
|
|
|
|
|
- **Config Snapshot**: Complete configuration in JSON |
|
|
- **Reproduce Script**: One-click rerun capability |
|
|
- **Artifact Archive**: Complete export of all outputs |
|
|
- **Run Summary**: Structured metadata for tracking |
|
|
|
|
|
```bash |
|
|
# Rerun any training |
|
|
./runs/humigence/reproduce.sh |
|
|
|
|
|
# Or use the config directly |
|
|
python3 training/unsloth/train_lora_dual.py --config runs/humigence/config.snapshot.json |
|
|
``` |
|
|
|
|
|
## 🛠️ Development |
|
|
|
|
|
### Dependencies |
|
|
|
|
|
Core dependencies are pinned for stability: |
|
|
|
|
|
```txt |
|
|
transformers>=4.41.0,<5.0.0 |
|
|
torch>=2.1.0 |
|
|
unsloth @ git+https://github.com/unslothai/unsloth.git |
|
|
rich>=13.0.0 |
|
|
inquirer>=3.1.0 |
|
|
``` |
|
|
|
|
|
### Local Development |
|
|
|
|
|
```bash |
|
|
# Install in development mode |
|
|
pip install -e . |
|
|
|
|
|
# Run tests |
|
|
python3 -m pytest tests/ |
|
|
|
|
|
# Run specific test |
|
|
python3 test_gpu_selection.py |
|
|
``` |
|
|
|
|
|
## 🤝 Contributing |
|
|
|
|
|
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. |
|
|
|
|
|
### Quick Contribution Guide |
|
|
|
|
|
1. Fork the repository |
|
|
2. Create a feature branch: `git checkout -b feature/amazing-feature` |
|
|
3. Make your changes |
|
|
4. Add tests if applicable |
|
|
5. Commit your changes: `git commit -m 'Add amazing feature'` |
|
|
6. Push to the branch: `git push origin feature/amazing-feature` |
|
|
7. Open a Pull Request |
|
|
|
|
|
## 📄 License |
|
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |
|
|
|
|
|
## 🙏 Acknowledgments |
|
|
|
|
|
- [Unsloth](https://github.com/unslothai/unsloth) for fast LoRA training |
|
|
- [HuggingFace](https://huggingface.co/) for the transformers library |
|
|
- [Microsoft](https://github.com/microsoft) for PEFT and LoRA implementations |
|
|
- The open-source ML community |
|
|
|
|
|
## 🆚 Comparison with Other Tools |
|
|
|
|
|
| Feature | Humigence CLI | Other Tools | |
|
|
|---------|---------------|-------------| |
|
|
| **Setup** | Interactive wizard | Manual config | |
|
|
| **GPU Detection** | Automatic | Manual | |
|
|
| **Multi-GPU** | Built-in TorchRun | Complex setup | |
|
|
| **Reproducibility** | Complete snapshots | Partial | |
|
|
| **Evaluation** | Built-in prompts | External tools | |
|
|
| **Artifacts** | Structured export | Manual collection | |
|
|
|
|
|
## 🐛 Troubleshooting |
|
|
|
|
|
### Common Issues |
|
|
|
|
|
**GPU not detected:** |
|
|
```bash |
|
|
# Check CUDA installation |
|
|
python3 -c "import torch; print(torch.cuda.is_available())" |
|
|
|
|
|
# Check GPU visibility |
|
|
nvidia-smi |
|
|
``` |
|
|
|
|
|
**Out of memory:** |
|
|
```bash |
|
|
# Reduce batch size in config |
|
|
# Or use QLoRA for memory efficiency |
|
|
``` |
|
|
|
|
|
**Training fails:** |
|
|
```bash |
|
|
# Check logs |
|
|
cat runs/humigence/training.log |
|
|
|
|
|
# Verify dataset format |
|
|
head -5 ~/humigence_data/your_dataset.jsonl |
|
|
``` |
|
|
|
|
|
### Getting Help |
|
|
|
|
|
- **Issues**: [GitHub Issues](https://github.com/your-username/humigence/issues) |
|
|
- **Discussions**: [GitHub Discussions](https://github.com/your-username/humigence/discussions) |
|
|
- **Documentation**: [Wiki](https://github.com/your-username/humigence/wiki) |
|
|
|
|
|
## 🗺️ Roadmap |
|
|
|
|
|
### Current Features ✅ |
|
|
- Interactive configuration wizard |
|
|
- Single and multi-GPU training |
|
|
- QLoRA and LoRA support |
|
|
- Built-in evaluation |
|
|
- Complete reproducibility |
|
|
|
|
|
### Coming Soon 🚧 |
|
|
- RAG implementation |
|
|
- EnterpriseGPT integration |
|
|
- Batch inference |
|
|
- Context length optimization |
|
|
- Web UI interface |
|
|
- Model serving |
|
|
|
|
|
### Future Features 🔮 |
|
|
- Distributed training across nodes |
|
|
- Advanced evaluation metrics |
|
|
- Model compression |
|
|
- Deployment automation |
|
|
|
|
|
--- |
|
|
|
|
|
**Built with ❤️ for the AI community** |
|
|
|
|
|
*Humigence — Your AI. Your pipeline. Zero code.* |
|
|
|
|
|
## 📊 Stats |
|
|
|
|
|
 |
|
|
 |
|
|
 |
|
|
 |
|
|
 |
|
|
 |
|
|
 |
