Skip to content

INSTALLATION_STEPS.md

Latest commit

 

History

History
381 lines (284 loc) · 8.2 KB

INSTALLATION_STEPS.md

File metadata and controls

381 lines (284 loc) · 8.2 KB

Math Tutor Bot - Complete Installation Guide

Overview

This guide will help you install a multimodal Math Tutor Bot using Qwen2.5-Omni-3B. The bot supports:

  • Text conversations
  • Voice input/output
  • Image understanding (diagrams, graphs, etc.)

Choose Your Installation Path

Option A: Full Model (Recommended)

  • Size: ~12GB download
  • Features: All capabilities (text, speech, images)
  • Requirements: 16GB RAM, 15GB disk space
  • Best for: Those with sufficient resources

Option B: Lightweight Model

  • Size: ~4GB download
  • Features: Text + separate TTS/STT
  • Requirements: 8GB RAM, 5GB disk space
  • Best for: Limited resources or no GPU

Option A: Full Installation (Qwen2.5-Omni-3B)

Step 1: Create Python Environment

Choose conda (recommended) or venv:

Using conda:

conda create -n tutor python=3.11 -y
conda activate tutor

Using venv:

python -m venv tutor
source tutor/bin/activate  # On Windows: tutor\Scripts\activate

Step 2: Install Dependencies

pip install torch transformers accelerate
pip install qwen-omni-utils soundfile
pip install openai-whisper
pip install kokoro>=0.9.2

Step 3: Install the Qwen Model

Run the installation script:

python install_qwen_full.py

This will:

  • Download ~12GB of model files (first time only)
  • Load the model into memory
  • Run a test to verify installation
  • Save model in ~/.cache/huggingface/

Alternative: Manual Installation

from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor
import torch

# Load model (downloads ~12GB on first run)
model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-3B",
    torch_dtype="auto",
    device_map="auto"  # Uses GPU if available, else CPU
)
processor = Qwen2_5OmniProcessor.from_pretrained("Qwen/Qwen2.5-Omni-3B")

print("Model loaded successfully!")

Step 4: Verify Installation

python simple_tutor_example.py

Expected output:

Loading model...
Model loaded!
Question: How do I solve 2x + 5 = 13?
Answer: [Model's step-by-step explanation]

Option B: Lightweight Installation

Step 1: Create Python Environment

conda create -n tutor python=3.11 -y
conda activate tutor

Step 2: Install Dependencies

pip install transformers torch
pip install kokoro>=0.9.2 soundfile
pip install openai-whisper

Step 3: Install Smaller Models

from transformers import AutoModelForCausalLM, AutoTokenizer
from kokoro import KPipeline
import whisper

# 1. Text generation: Qwen2.5-1.5B (~3GB)
text_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct",
    torch_dtype="auto",
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-1.5B-Instruct")

# 2. Text-to-Speech: Kokoro (~200MB)
tts = KPipeline(lang_code='a')

# 3. Speech-to-Text: Whisper tiny (~150MB)
stt = whisper.load_model("tiny")

Step 4: Test Lightweight Setup

python full_tutor_lightweight.py

Memory Optimization (Optional)

4-bit Quantization (GPU Required)

If you have limited GPU memory, use quantization:

pip install bitsandbytes
python install_qwen_with_quantization.py

This reduces memory from 12GB to ~3GB.

Manual quantization:

from transformers import BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16
)

model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-3B",
    quantization_config=quantization_config,
    device_map="auto"
)

System Requirements

Full Model (Qwen2.5-Omni-3B)

  • OS: Windows, macOS, or Linux
  • Python: 3.10 or 3.11
  • RAM: 16GB minimum (8GB with quantization)
  • Disk: 15GB free space
  • GPU: Optional (8GB VRAM recommended for better performance)
  • Internet: For initial download only

Lightweight Model

  • OS: Windows, macOS, or Linux
  • Python: 3.10 or 3.11
  • RAM: 8GB minimum
  • Disk: 5GB free space
  • GPU: Optional
  • Internet: For initial download only

Testing Your Installation

Quick Test

Create test.py:

from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor

print("Loading model...")
model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-3B",
    torch_dtype="auto",
    device_map="auto"
)
processor = Qwen2_5OmniProcessor.from_pretrained("Qwen/Qwen2.5-Omni-3B")
print("✓ Model loaded!")

conversation = [{"role": "user", "content": "What is 2+2?"}]
text_input = processor.apply_chat_template(conversation, add_generation_prompt=True, tokenize=False)
inputs = processor(text=text_input, return_tensors="pt").to(model.device)
generated_ids = model.generate(**inputs, max_new_tokens=50)
response = processor.batch_decode(generated_ids[:, inputs['input_ids'].shape[1]:], skip_special_tokens=True)[0]

print(f"Test: What is 2+2?")
print(f"Answer: {response}")
print("\n✓ Everything works!")

Run:

python test.py

Common Installation Issues

Issue: "Out of memory"

Solutions:

  1. Use quantization: python install_qwen_with_quantization.py
  2. Use lightweight version: See Option B above
  3. Close other applications
  4. Use smaller model: Qwen2.5-1.5B instead of 3B

Issue: "No module named 'transformers'"

Solution:

pip install transformers accelerate

Issue: Slow download

Solutions:

  1. Be patient - 12GB takes 30-60 minutes
  2. Check internet connection
  3. Download will resume if interrupted
  4. Models cache in ~/.cache/huggingface/

Issue: "CUDA out of memory" (GPU)

Solutions:

# Use CPU instead
device_map="cpu"

# Or use half precision
torch_dtype=torch.float16

Issue: Model not found

Solution:

# Check internet connection
# Verify HuggingFace is accessible
# Try manual download from https://huggingface.co/Qwen/Qwen2.5-Omni-3B

Running Examples

After installation, try these examples:

1. Simple Text Chat

python simple_tutor_example.py

2. Complete Feature Guide

python qwen_usage_guide.py

3. Test All Modes

python test_qwen_omni.py

4. Test Text-to-Speech

python test_kokoro.py

Next Steps After Installation

  1. Test basic functionality: Run simple_tutor_example.py
  2. Explore all features: Read qwen_usage_guide.py
  3. Customize system prompt: Edit teaching style
  4. Build frontend: Web app, desktop app, or CLI
  5. Add features: Progress tracking, quizzes, etc.

Verification Checklist

  • Python environment created and activated
  • All dependencies installed via pip
  • Model downloaded successfully (~12GB or ~4GB)
  • Test script runs without errors
  • Model responds to "What is 2+2?" correctly
  • Example scripts execute successfully

Installation Summary

Full Installation Commands (Quick Copy)

# Create environment
conda create -n tutor python=3.11 -y
conda activate tutor

# Install dependencies
pip install torch transformers accelerate
pip install qwen-omni-utils soundfile
pip install openai-whisper
pip install kokoro>=0.9.2

# Install model
python install_qwen_full.py

# Test installation
python simple_tutor_example.py

Lightweight Installation Commands (Quick Copy)

# Create environment
conda create -n tutor python=3.11 -y
conda activate tutor

# Install dependencies
pip install transformers torch
pip install kokoro>=0.9.2 soundfile
pip install openai-whisper

# Run lightweight version
python full_tutor_lightweight.py

Resources

Support

If you encounter issues:

  1. Check the troubleshooting section above
  2. Verify system requirements
  3. Review error messages carefully
  4. Check the example scripts for reference
  5. Ensure all dependencies are installed

You're ready to build your Math Tutor Bot!