whisper-api-server/tools/whisper_merge_guide.md

# Полное руководство по объединению моделей Whisper

## Содержание
1. [Введение](#введение)
2. [Установка и подготовка](#установка-и-подготовка)
3. [Базовое использование](#базовое-использование)
4. [Детальные настройки](#детальные-настройки)
   - [Методы слияния](#методы-слияния)
   - [Параметры для метода Direct](#параметры-для-метода-direct)
   - [Параметры для метода SLERP](#параметры-для-метода-slerp)
   - [Параметры для метода TIES](#параметры-для-метода-ties)
5. [Практические рекомендации](#практические-рекомендации)
6. [Тестирование и оценка](#тестирование-и-оценка)
7. [Устранение неполадок](#устранение-неполадок)

## Введение

Скрипт `whisper_merge.sh` позволяет объединять две модели Whisper, обученные на разных датасетах, для получения комбинированной модели с улучшенными характеристиками. Особенно полезно для моделей, обученных на разных типах данных одного языка (например, разные диалекты русского языка, формальная/неформальная речь и т.д.).

## Установка и подготовка

1. **Убедитесь, что Conda установлена** в вашей системе.
2. **Скачайте скрипт `whisper_merge.sh`** и сделайте его исполняемым:
   ```bash
   chmod +x whisper_merge.sh
   ```
3. **Подготовьте модели для слияния**. По умолчанию скрипт ищет модели по следующим путям:
   - Модель A: `/mnt/cloud/llm/whisper/whisper-large-v3-russian`
   - Модель B: `/mnt/cloud/llm/whisper/whisper-large-v3-ru-podlodka`
   - Директория для результатов: `/mnt/cloud/llm/whisper/whisper-large-v3-russian+podlodka`

   Пути можно изменить, отредактировав переменные `MODEL_A`, `MODEL_B` и `OUTPUT_DIR` в начале скрипта.

## Базовое использование

### Первый запуск

Для первого запуска рекомендуется использовать флаг `--update` для установки всех зависимостей:

```bash
./whisper_merge.sh --update
```

Это создаст окружение conda с именем `whisper-merge` и установит необходимые пакеты.

### Стандартное слияние

Для выполнения слияния с настройками по умолчанию:

```bash
./whisper_merge.sh
```

По умолчанию будут использованы следующие параметры:
- Метод слияния: `all` (все методы)
- SLERP t: `0.5`
- TIES density: `0.8`
- Encoder weights: `0.6,0.4`
- Decoder weights: `0.4,0.6`
- Direct alpha: `0.5`

## Детальные настройки

### Методы слияния

Скрипт поддерживает три метода слияния моделей:

1. **Direct** (`--method direct`) — простое линейное смешивание весов:
   ```bash
   ./whisper_merge.sh --method direct
   ```
   - **Преимущества**: простота, надежность, меньшие вычислительные требования
   - **Недостатки**: может не сохранять геометрию пространства весов
   - **Когда использовать**: для быстрого тестирования или когда модели очень близки

2. **SLERP** (`--method slerp`) — сферическая линейная интерполяция:
   ```bash
   ./whisper_merge.sh --method slerp
   ```
   - **Преимущества**: лучше сохраняет геометрию пространства весов
   - **Недостатки**: требует больше вычислений, может не работать корректно для некоторых моделей
   - **Когда использовать**: для моделей, где важно сохранение пространственных отношений между параметрами

3. **TIES** (`--method ties`) — алгоритм Task Induced Expert Selection:
   ```bash
   ./whisper_merge.sh --method ties
   ```
   - **Преимущества**: позволяет индивидуально настраивать веса для кодировщика и декодера
   - **Недостатки**: более сложный, требует тонкой настройки параметров
   - **Когда использовать**: для продвинутого слияния, когда известно, что одна модель лучше работает с определенными аспектами (например, фонетикой или грамматикой)

4. **All** (`--method all`) — применяет все три метода и сохраняет результаты в отдельные подпапки:
   ```bash
   ./whisper_merge.sh --method all
   ```
   - **Преимущества**: позволяет сравнить результаты всех методов
   - **Недостатки**: требует больше времени и дискового пространства
   - **Когда использовать**: при первоначальном тестировании для выбора оптимального метода

### Параметры для метода Direct

#### Direct Alpha (`--direct-alpha`)

Определяет вес первой модели в процессе слияния:

```bash
./whisper_merge.sh --method direct --direct-alpha 0.7
```

- **Диапазон**: от 0.0 до 1.0
- **По умолчанию**: 0.5 (равный вес обеих моделей)
- **Влияние**:
  - `0.0` — полностью использует веса второй модели (MODEL_B)
  - `0.5` — равный вклад обеих моделей
  - `1.0` — полностью использует веса первой модели (MODEL_A)
- **Рекомендации**:
  - Если MODEL_A лучше справляется с задачей: увеличьте alpha (`0.6` — `0.8`)
  - Если MODEL_B лучше справляется с задачей: уменьшите alpha (`0.2` — `0.4`)
  - Для тонкой настройки изменяйте значение с шагом 0.05

### Параметры для метода SLERP

#### SLERP t (`--slerp-t`)

Определяет соотношение весов при сферической интерполяции:

```bash
./whisper_merge.sh --method slerp --slerp-t 0.3
```

- **Диапазон**: от 0.0 до 1.0
- **По умолчанию**: 0.5 (равный вклад)
- **Влияние**:
  - `0.0` — полностью вес на MODEL_A
  - `1.0` — полностью вес на MODEL_B
  - Промежуточные значения дают нелинейную интерполяцию между моделями
- **Рекомендации**:
  - В отличие от direct alpha, здесь значение `0` соответствует MODEL_A, а `1` соответствует MODEL_B
  - SLERP обычно дает более гладкое слияние, чем direct
  - Для русских моделей обычно хорошо работают значения `0.4` — `0.6`

### Параметры для метода TIES

#### TIES Density (`--ties-density`)

Определяет долю параметров, которые будут смешаны индивидуально, а не усреднены:

```bash
./whisper_merge.sh --method ties --ties-density 0.85
```

- **Диапазон**: от 0.0 до 1.0
- **По умолчанию**: 0.8
- **Влияние**:
  - `0.0` — все параметры усредняются
  - `1.0` — все параметры смешиваются индивидуально по заданным весам
  - Промежуточные значения определяют процент параметров с наибольшей разницей, которые будут смешаны индивидуально
- **Рекомендации**:
  - Более высокие значения (`0.8` — `0.9`) лучше сохраняют индивидуальные особенности каждой модели
  - Более низкие значения (`0.5` — `0.7`) дают более стабильный результат
  - Для русских моделей рекомендуется `0.85`, что позволяет сохранить уникальные особенности обеих моделей

#### Encoder Weights (`--encoder-weights`)

Определяет веса моделей для кодировщика (отвечает за обработку аудиосигнала):

```bash
./whisper_merge.sh --method ties --encoder-weights "0.7,0.3"
```

- **Формат**: два числа, разделенные запятой, сумма должна равняться 1.0
- **По умолчанию**: "0.6,0.4"
- **Влияние**:
  - Первое число — вес MODEL_A для кодировщика
  - Второе число — вес MODEL_B для кодировщика
- **Рекомендации**:
  - Если MODEL_A лучше распознает фонетические особенности речи: увеличьте её вес (e.g., "0.7,0.3")
  - Если MODEL_B лучше распознает акценты или диалекты: увеличьте её вес (e.g., "0.4,0.6")
  - Для русских моделей, если одна из них лучше обрабатывает различные диалекты, дайте ей больший вес в кодировщике

#### Decoder Weights (`--decoder-weights`)

Определяет веса моделей для декодера (отвечает за формирование текста):

```bash
./whisper_merge.sh --method ties --decoder-weights "0.3,0.7"
```

- **Формат**: два числа, разделенные запятой, сумма должна равняться 1.0
- **По умолчанию**: "0.4,0.6"
- **Влияние**:
  - Первое число — вес MODEL_A для декодера
  - Второе число — вес MODEL_B для декодера
- **Рекомендации**:
  - Если MODEL_A лучше справляется с грамматикой: увеличьте её вес (e.g., "0.6,0.4")
  - Если MODEL_B имеет лучший языковой контекст: увеличьте её вес (e.g., "0.3,0.7")
  - Для русских моделей, если одна модель лучше обрабатывает грамматические конструкции, дайте ей больший вес в декодере

## Практические рекомендации

### Для слияния русских моделей

1. **Общее правило**: начинайте с метода TIES с близкими к равным весами.

2. **Если модели обучены на разных типах данных**:
   ```bash
   ./whisper_merge.sh --method ties --ties-density 0.85 --encoder-weights "0.6,0.4" --decoder-weights "0.5,0.5"
   ```
   Это даст больший приоритет первой модели в распознавании звуков, но обе модели будут равно влиять на грамматику.

3. **Если одна модель лучше с формальной речью, а другая с разговорной**:
   ```bash
   ./whisper_merge.sh --method ties --ties-density 0.9 --encoder-weights "0.5,0.5" --decoder-weights "0.6,0.4"
   ```
   Высокая плотность (0.9) позволит сохранить уникальные особенности обеих моделей.

4. **Для моделей, где первая модель имеет высокое качество, но вторая содержит специфичные улучшения**:
   ```bash
   ./whisper_merge.sh --method slerp --slerp-t 0.3
   ```
   Это сохранит основу первой модели (70%) и добавит 30% особенностей второй.

### Для наилучших результатов

Рекомендуется выполнить несколько экспериментов с разными настройками и сравнить результаты:

```bash
# Эксперимент 1: TIES с приоритетом первой модели
./whisper_merge.sh --method ties --ties-density 0.85 --encoder-weights "0.65,0.35" --decoder-weights "0.6,0.4"

# Эксперимент 2: SLERP с уклоном к первой модели
./whisper_merge.sh --method slerp --slerp-t 0.4

# Эксперимент 3: Прямое слияние
./whisper_merge.sh --method direct --direct-alpha 0.6
```

## Тестирование и оценка

После слияния моделей важно оценить результаты:

1. **Подготовьте тестовый набор данных**, включающий:
   - Формальную речь
   - Разговорную речь
   - Различные диалекты
   - Различные шумовые условия
   - Различные темпы речи

2. **Выполните транскрипцию** с помощью объединенной модели и сравните с исходными моделями.

3. **Оцените результаты** по следующим критериям:
   - Word Error Rate (WER)
   - Character Error Rate (CER)
   - Обработка специфичных для русского языка особенностей (падежи, ударения)
   - Скорость обработки

## Устранение неполадок

### Проблемы со слиянием SLERP или TIES

Если возникают ошибки при использовании методов SLERP или TIES, скрипт автоматически откатывается к методу Direct. Для решения проблем:

1. **Проверьте совместимость моделей**:
   - Модели должны иметь одинаковую архитектуру
   - Версии Whisper должны быть совместимы

2. **Увеличьте объем памяти**:
   - SLERP и TIES требуют больше оперативной памяти
   - Попробуйте запустить на машине с большим объемом RAM

3. **Проверьте логи** для определения конкретной проблемы

### Проблемы с окружением Conda

Если возникают проблемы с созданием или активацией окружения:

1. **Обновите Conda**:
   ```bash
   conda update -n base conda
   ```

2. **Удалите и пересоздайте окружение**:
   ```bash
   conda env remove -n whisper-merge
   ./whisper_merge.sh --update
   ```

3. **Проверьте пути к моделям** и убедитесь, что они корректны