DEPLOYMENT_GUIDE.md

# Hướng dẫn Deploy MIMO lên Hugging Face Spaces

## Tổng quan
MIMO là một mô hình AI để tạo video nhân vật có thể điều khiển được. Hướng dẫn này sẽ giúp bạn deploy dự án lên Hugging Face Spaces.

## Chuẩn bị Files

### 1. Files cần thiết đã được tạo/cập nhật:
- ✅ `app_hf.py` - Ứng dụng Gradio được tối ưu cho HF Spaces
- ✅ `README_HF.md` - README với metadata cho HF Spaces
- ✅ `requirements.txt` - Dependencies đã được cập nhật
- ✅ `.gitattributes` - Cấu hình Git LFS cho files lớn

### 2. Cấu trúc thư mục sau khi deploy:
```
repo/
├── app.py (rename from app_hf.py)
├── README.md (use README_HF.md content)
├── requirements.txt
├── .gitattributes
├── configs/
├── src/
├── tools/
├── assets/ (sẽ được tải tự động hoặc cần upload)
└── pretrained_weights/ (sẽ được tải tự động)
```

## Các bước Deploy

### Bước 1: Tạo Repository trên Hugging Face
1. Truy cập https://huggingface.co/new-space
2. Chọn "Create new Space"
3. Điền thông tin:
   - **Space name**: `mimo-demo` (hoặc tên khác)
   - **License**: Apache 2.0
   - **SDK**: Gradio
   - **Hardware**: GPU (khuyến nghị T4 hoặc A10G)
   - **Visibility**: Public

### Bước 2: Clone và Setup Repository
```bash
# Clone space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/mimo-demo
cd mimo-demo

# Copy files từ project hiện tại
cp /path/to/mimo-demo/app_hf.py ./app.py
cp /path/to/mimo-demo/README_HF.md ./README.md
cp /path/to/mimo-demo/requirements.txt ./
cp /path/to/mimo-demo/.gitattributes ./
cp -r /path/to/mimo-demo/configs ./
cp -r /path/to/mimo-demo/src ./
cp -r /path/to/mimo-demo/tools ./

# Tạo thư mục assets cơ bản (nếu chưa có)
mkdir -p assets/masks assets/test_image assets/video_template
```

### Bước 3: Cấu hình Git LFS
```bash
# Initialize git lfs
git lfs install

# Add large files to git lfs tracking
git lfs track "*.pth"
git lfs track "*.bin"
git lfs track "*.safetensors"
git lfs track "*.mp4"
git lfs track "assets/**"
git lfs track "pretrained_weights/**"
```

### Bước 4: Upload Assets và Model Weights
Có 2 cách để xử lý model weights và assets:

#### Cách 1: Tự động download (Khuyến nghị)
Code trong `app_hf.py` đã được thiết kế để tự động download models từ Hugging Face khi khởi động. Điều này giúp giảm kích thước repository.

#### Cách 2: Upload manual
```bash
# Download và upload assets manually nếu cần
# (Chỉ nên dùng cho files nhỏ < 50MB)
```

### Bước 5: Commit và Push
```bash
git add .
git commit -m "Initial deployment of MIMO demo"
git push
```

### Bước 6: Cấu hình Space Settings
1. Truy cập settings của Space trên Hugging Face
2. Kiểm tra:
   - **Hardware**: Chọn GPU phù hợp (T4 minimum, A10G khuyến nghị)
   - **Environment variables**: Thêm nếu cần
   - **Secrets**: Thêm API keys nếu cần

## Tối ưu hóa Performance

### 1. GPU Memory Management
- App đã được tối ưu để sử dụng `@spaces.GPU` decorator
- Tự động fallback về CPU nếu không có GPU
- Clear GPU cache sau mỗi inference

### 2. Model Loading Optimization
- Lazy loading cho models
- Error handling cho missing files
- Fallback mechanisms

### 3. File Size Optimization
- Sử dụng Git LFS cho files > 10MB
- Automatic model downloading thay vì upload
- Compress assets khi có thể

## Troubleshooting

### Lỗi thường gặp:

#### 1. "Model files not found"
- **Nguyên nhân**: Models chưa được download
- **Giải pháp**: Kiểm tra function `download_models()` và network connection

#### 2. "CUDA out of memory"
- **Nguyên nhân**: GPU memory không đủ
- **Giải pháp**:
  - Upgrade lên GPU lớn hơn
  - Reduce batch size trong code
  - Optimize model loading

#### 3. "Assets not found"
- **Nguyên nhân**: Assets folder trống
- **Giải pháp**:
  - Upload assets manually
  - Sử dụng fallback mechanisms trong code

#### 4. "Build timeout"
- **Nguyên nhân**: Requirements install quá lâu
- **Giải pháp**:
  - Optimize requirements.txt
  - Use pre-built images
  - Split installation steps

### Logs và Monitoring
- Kiểm tra logs trong HF Spaces interface
- Monitor GPU usage và memory
- Check app performance metrics

## Cấu hình nâng cao

### Environment Variables
```bash
# Thêm trong Space settings nếu cần:
HF_TOKEN=your_token_here
CUDA_VISIBLE_DEVICES=0
```

### Custom Dockerfile (Nếu cần)
```dockerfile
FROM python:3.10

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 7860

CMD ["python", "app.py"]
```

## Kết luận

Sau khi hoàn thành các bước trên, Space của bạn sẽ:
- ✅ Tự động build và deploy
- ✅ Load models từ Hugging Face
- ✅ Có GPU acceleration
- ✅ UI thân thiện với người dùng
- ✅ Error handling tốt

**Lưu ý quan trọng**:
- GPU Spaces có chi phí. Kiểm tra pricing trên Hugging Face
- Test thoroughly trước khi public
- Monitor usage và performance

## Support
Nếu gặp vấn đề:
1. Check Space logs
2. Review Hugging Face documentation
3. Check MIMO GitHub repository issues
4. Contact repository maintainers