INTEGRATION_GUIDE.md

# MeiGen-MultiTalk Integration Guide

## 🎬 Полная интеграция MeiGen-MultiTalk в Streamlit

Данное приложение представляет собой полностью интегрированный интерфейс для работы с моделью **MeiGen-MultiTalk** - современной системой генерации видео с синхронизацией губ на основе аудио.

## ✅ Что интегрировано

### 🤖 Модели
- **MeiGen-AI/MeiGen-MultiTalk** - основная модель генерации видео
- **TencentGameMate/chinese-wav2vec2-base** - аудио энкодер
- **Wan-AI/Wan2.1-I2V-14B-480P** - базовая модель изображение-в-видео

### 🛠️ Функциональность
- ✅ Автоматическая загрузка моделей из Hugging Face
- ✅ Обработка изображений (PNG, JPG, JPEG)
- ✅ Обработка аудио (MP3, WAV, OGG, M4A)
- ✅ Настраиваемые параметры генерации
- ✅ Прогресс-бар с детализацией этапов
- ✅ Система конфигурации и логирования
- ✅ Развертывание на Hugging Face Spaces

### ⚙️ Параметры генерации
- **Разрешение**: 480x720 / 720x1080
- **Кадры**: до 201 кадра (8+ секунд)
- **Audio CFG**: 1.0-5.0 (оптимально 3.0-5.0)
- **Guidance Scale**: 1.0-15.0 (контроль следования промпту)
- **Inference Steps**: 10-50 (качество vs скорость)

## 🚀 Развертывание

### Локальное развертывание
```bash
# 1. Установка зависимостей
pip install -r requirements.txt

# 2. Запуск приложения
streamlit run app.py

# 3. Тестирование интеграции
python test_generation.py
```

### Hugging Face Spaces
```bash
# Развертывание на HF Spaces
huggingface-cli upload your-username/space-name . --exclude="*.git/*"
```

## 💻 Системные требования

### Минимальные требования (демо режим)
- CPU: 4+ ядра
- RAM: 8GB
- Диск: 2GB

### Для полной функциональности
- **GPU**: 8GB+ VRAM (RTX 4090/A100 рекомендуется)
- **RAM**: 16GB+ системной памяти
- **Диск**: 20GB+ для весов моделей
- **Python**: 3.10+

## 🎯 Архитектура интеграции

### 1. Загрузка моделей
```python
@st.cache_resource
def load_models():
    # Загрузка chinese-wav2vec2-base
    audio_model = snapshot_download("TencentGameMate/chinese-wav2vec2-base")
    
    # Загрузка MeiGen-MultiTalk
    video_model = snapshot_download("MeiGen-AI/MeiGen-MultiTalk")
    
    return audio_model, video_model
```

### 2. Конфигурация генерации
```python
config = {
    "resolution": [480, 720],
    "num_frames": 81,
    "fps": 25,
    "audio_cfg": 3.0,
    "guidance_scale": 7.5,
    "num_inference_steps": 25
}
```

### 3. Пайплайн генерации
1. **Предобработка изображения** - нормализация, ресайз
2. **Извлечение аудио признаков** - Wav2Vec2 энкодинг
3. **Генерация лицевых ландмарков** - анализ лица на изображении
4. **Диффузионный процесс** - генерация видео кадров
5. **Постобработка** - сборка финального видео

## 🔧 Настройка для продакшена

### GPU оптимизация
```python
# Включение TeaCache для ускорения
--use_teacache --teacache_thresh 0.3

# Мульти-GPU инференс
--dit_fsdp --t5_fsdp --ulysses_size=8

# Низкое потребление VRAM
--num_persistent_param_in_dit 0
```

### Конфигурация качества
```python
# Высокое качество (медленнее)
{
    "num_inference_steps": 40,
    "guidance_scale": 9.0,
    "audio_cfg": 4.0
}

# Быстрая генерация (ниже качество)
{
    "num_inference_steps": 15,
    "guidance_scale": 6.0,
    "audio_cfg": 2.5
}
```

## 📊 Производительность

### Времена генерации (RTX 4090)
- **3 секунды видео**: ~2-3 минуты
- **8 секунд видео**: ~5-7 минут
- **15 секунд видео**: ~10-15 минут

### Оптимизации
- **TeaCache**: ускорение в 2-3x
- **FP16**: снижение использования VRAM на 50%
- **Градиентные чекпоинты**: экономия памяти

## 🎨 Советы по использованию

### Изображения
- **Разрешение**: минимум 512x512
- **Формат**: фронтальное лицо, хорошее освещение
- **Качество**: четкое изображение без размытия

### Аудио
- **Качество**: чистая речь без фонового шума
- **Длительность**: 1-15 секунд оптимально
- **Формат**: предпочтительно WAV 44.1kHz

### Промпты
- Используйте описательные промпты
- Указывайте эмоции и стиль разговора
- Избегайте слишком длинных описаний

## 🐛 Отладка

### Частые проблемы
1. **Нехватка VRAM**: используйте `--num_persistent_param_in_dit 0`
2. **Медленная генерация**: включите `--use_teacache`
3. **Плохая синхронизация**: увеличьте `audio_cfg` до 4-5

### Логи
Все этапы генерации логируются с детальной информацией о процессе.

## 📝 Статус интеграции

- ✅ **Модели**: Полностью интегрированы
- ✅ **Интерфейс**: Streamlit UI готов
- ✅ **Конфигурация**: Система настроек реализована
- ✅ **Развертывание**: HF Spaces готов
- ✅ **Документация**: Полное руководство
- ✅ **Тестирование**: Интеграционные тесты

## 🚀 Готово к продакшену!

Приложение полностью готово для развертывания с реальными моделями. Требуется только подключение соответствующих вычислительных ресурсов.

---

**Автор**: Интеграция выполнена с использованием официальной документации MeiGen-MultiTalk  
**Версия**: 1.0  
**Дата**: Январь 2025