Quick Start Guide¶

Get up and running with Gym in 5 minutes!

Prerequisites¶

Python: 3.9 or higher
PyTorch: 2.0 or higher (with CUDA for GPU support)
Git: For cloning the repository

Installation¶

Option 1: From Source (Recommended)¶

# Clone the repository
git clone https://github.com/zooai/gym.git
cd gym

# Install in development mode
pip install -e .

# For GPU support (NVIDIA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# For Apple Silicon (MPS)
pip install torch torchvision torchaudio

Option 2: From PyPI¶

pip install zoo-gym

Option 3: From Conda¶

conda create -n gym python=3.11
conda activate gym
pip install -e .

Verify Installation¶

# Check installation
python -c "import gym; print(gym.__version__)"

# Launch web UI
gym webui

The web interface should open at http://localhost:7860

Your First Training¶

Using Web UI¶

Launch the web interface:
```
gym webui
```
Navigate to the Train tab
Select model: Qwen/Qwen3-4B-Instruct
Choose dataset: alpaca_en_demo
Set training method: LoRA
Click Start Training

Using Command Line¶

gym train \
  --model_name_or_path Qwen/Qwen3-4B-Instruct \
  --template qwen3 \
  --dataset alpaca_en_demo \
  --finetuning_type lora \
  --lora_rank 8 \
  --lora_alpha 16 \
  --output_dir ./output/qwen3-lora \
  --per_device_train_batch_size 2 \
  --gradient_accumulation_steps 4 \
  --num_train_epochs 3 \
  --learning_rate 5e-5 \
  --fp16

Using Python API¶

from gym.train import run_sft
from gym.hparams import get_train_args

# Configure training
config = {
    "model_name_or_path": "Qwen/Qwen3-4B-Instruct",
    "template": "qwen3",
    "dataset": "alpaca_en_demo",
    "finetuning_type": "lora",
    "output_dir": "./output/qwen3-lora",
    "per_device_train_batch_size": 2,
    "num_train_epochs": 3
}

# Get arguments
model_args, data_args, training_args, finetuning_args, generating_args = get_train_args(config)

# Run training
run_sft(model_args, data_args, training_args, finetuning_args, generating_args)

Test Your Model¶

Chat with Your Model¶

gym chat \
  --model_name_or_path Qwen/Qwen3-4B-Instruct \
  --adapter_name_or_path ./output/qwen3-lora \
  --template qwen3

Serve as API¶

gym api \
  --model_name_or_path Qwen/Qwen3-4B-Instruct \
  --adapter_name_or_path ./output/qwen3-lora \
  --port 8000

Then test with curl:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-lora",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Next Steps¶

Installation Guide - Detailed installation options
First Training - In-depth training tutorial
Continuous Learning GRPO - Training-free adaptation
Custom Datasets - Use your own data

Troubleshooting¶

CUDA Out of Memory¶

Reduce batch size:

--per_device_train_batch_size 1
--gradient_accumulation_steps 8

Slow Training¶

Enable Flash Attention:

pip install flash-attn --no-build-isolation

Add flag:

--flash_attn fa2

Model Download Issues¶

Use mirror:

export HF_ENDPOINT=https://hf-mirror.com

Import Errors¶

Reinstall in development mode:

pip install -e . --no-deps
pip install -r requirements.txt

Getting Help¶

Documentation: https://zoo-gym.readthedocs.io
GitHub Issues: https://github.com/zooai/gym/issues
Discord: https://discord.gg/zooai
Email: support@zoo.ngo

Ready to dive deeper? Check out the Installation Guide for more options!