USER_GUIDE.md

# Medical Transcriber GUI - Руководство пользователя

## 🎯 Обзор

Medical Transcriber - это полнофункциональное Windows приложение для быстрого транскрибирования медицинских аудиодиктовок с автоматической коррекцией и созданием отчётов в формате DOCX.

### Основные возможности:

✅ **Транскрибирование аудио** - использует модель Whisper
✅ **Автоматическая коррекция** - улучшение текста через LLM (GPT-4, Claude, Gemini)
✅ **База медицинских терминов** - специальная обработка медицинской лексики
✅ **Автогенерация отчётов** - создание красивых DOCX документов
✅ **Сохранение истории** - все результаты сохраняются с временными метками
✅ **Удобный интерфейс** - простой и понятный GUI

## 🚀 Быстрый старт

### Вариант 1: Запуск готового .exe (Рекомендуется)

1. Скачайте `MedicalTranscriber.exe` из папки `dist/`
2. Двойной клик для запуска
3. Приложение готово к использованию!

**Требования:**
- Windows 10/11
- 4+ ГБ оперативной памяти
- 2+ ГБ свободного места на диске

### Вариант 2: Запуск из Python

```bash
# Перейти в папку проекта
cd Trans_for_doctors

# Установить зависимости
pip install -r requirements.txt

# Запустить GUI
python run_gui.py
```

## 📖 Использование приложения

### Шаг 1: Выбор аудиофайла

1. Откройте вкладку **"Транскрибирование"**
2. Нажмите кнопку **"Обзор..."** в секции "1. Выбор аудиофайла"
3. Выберите аудиофайл (поддерживаются: WAV, MP3, M4A)
4. Путь к файлу отобразится в поле ввода

**Поддерживаемые форматы:**
- `.wav` - рекомендуется (лучшее качество)
- `.mp3` - обычно качество достаточно
- `.m4a` - работает, но медленнее

**Подсказка:** Чем выше качество аудио, тем лучше результат!

### Шаг 2: Заполнение данных пациента

1. В секции **"2. Данные пациента"** нажмите **"Заполнить данные пациента..."**
2. В открывшемся диалоге заполните:
   - **ФИО пациента** - обязательно (для отчёта)
   - **Дата рождения** - в формате ДД.MM.YYYY
   - **Область исследования** - например "МРТ головы"
   - **Номер исследования** - идентификатор
   - **Дата исследования** - автоматически установлена на сегодня
   - **ФИО врача** - подпись в отчёте

3. Нажмите **"OK"** - данные сохранены

**Если включена опция "Автоматически создать отчёт":**
- Все поля ФИО пациента и врача будут автоматически добавлены в DOCX отчёт
- Дата исследования используется для датирования отчёта

### Шаг 3: Выбор опций обработки

В секции **"3. Опции обработки"** доступны:

- ✅ **Использовать LLM-коррекцию** - включить улучшение текста через AI (рекомендуется)
- ✅ **Автоматически создать отчёт** - генерировать DOCX файл (рекомендуется)
- ✅ **Сохранить оригинальную транскрипцию** - сохранять необработанный текст

### Шаг 4: Запуск обработки

1. Убедитесь, что выбран аудиофайл
2. Если нужен отчёт - заполните данные пациента
3. Нажмите большую зелёную кнопку **"▶ Начать транскрибирование"**
4. Дождитесь завершения (может занять несколько минут)
5. Результаты будут выведены в окне "5. Результаты"

**Примерное время обработки:**
- 30 сек аудио → 2-5 минут (зависит от мощности ПК и размера модели)
- С LLM коррекцией → +1-3 минуты

### Шаг 5: Сохранённые результаты

После успешной обработки результаты автоматически сохраняются в папках:

```
Trans_for_doctors/
├── results/
│   ├── result_20260116_120530.json          # Оригинальная транскрипция
│   ├── result_20260116_120530_corrected.json # Скорректированная версия
│   └── reports/
│       └── report_20260116_120530.docx      # Финальный отчёт
└── logs/
    └── transcription_20260116_120530.log    # Логи обработки
```

## ⚙️ Вкладка "Настройки"

### Модель Whisper

- **Путь к модели** - папка с загруженной моделью Whisper
  - По умолчанию: папка проекта
  - Скачайте модель если её нет (см. ниже)

- **Устройство** - выбор железа для вычислений
  - `auto` - автоматически выбирает GPU если доступен, иначе CPU
  - `cuda` - использовать NVIDIA GPU (требуется CUDA Toolkit)
  - `cpu` - процессор (медленнее, но всегда работает)

- **Тип данных** - точность вычислений
  - `float32` - стандарт (медленнее, точнее)
  - `float16` - половинная точность (быстрее, меньше памяти)
  - `bfloat16` - BF16 (рекомендуется для новых GPU)

### OpenRouter API (для LLM коррекции)

- **API Ключ** - требуется для включения умной коррекции
  - Получите на https://openrouter.ai
  - Зарегистрируйтесь и создайте ключ
  - Вставьте в поле "API Ключ"

- **Модель LLM** - выбор модели для коррекции
  - `gpt-4o` - лучшее качество коррекции, дороже
  - `claude-3-opus` - отличное качество, более дешево
  - `gemini-pro` - хорошее качество, быстро
  - `gpt-4-turbo` - баланс качества и скорости

### База медицинских терминов

- **Путь к файлу терминов** - файл со специальной медицинской лексикой
  - По умолчанию: `medical_terms.txt` в папке проекта
  - Может быть отредактирован для добавления новых терминов

## 🔑 Получение API ключа для OpenRouter

1. Перейдите на https://openrouter.ai
2. Нажмите **"Sign Up"** (или **"Log In"** если уже есть аккаунт)
3. Заполните форму регистрации
4. Перейдите в **Settings → Keys**
5. Нажмите **"Create Key"**
6. Скопируйте ключ
7. Вставьте в GUI приложение → вкладка "Настройки"

**Стоимость:**
- За запросы платите по использованию (около 5-10 рублей за 1000 слов)
- Первый месяц обычно есть бесплатный кредит ($5-10)

## 🐛 Решение проблем

### Проблема: "Модель не найдена"

**Решение:**
1. Скачайте модель Whisper:
   ```bash
   huggingface-cli download openai/whisper-base-ru --local-dir ./whisper_model
   ```
2. В вкладке "Настройки" укажите путь к папке `whisper_model`

### Проблема: "Чёрный экран при запуске"

**Решение:**
- Приложение может загружаться медленно (особенно при первом запуске)
- Подождите 30-60 секунд
- Проверьте наличие модели Whisper

### Проблема: "API Ключ неверный"

**Решение:**
1. Проверьте ключ на https://openrouter.ai/settings/keys
2. Убедитесь, что скопировали полный ключ
3. Наличие кредитов на аккаунте (добавьте платёж если нужно)

### Проблема: "Недостаточно памяти"

**Решение:**
- Используйте `float16` вместо `float32` в настройках
- Закройте другие приложения
- Используйте GPU если есть (установите CUDA)

### Проблема: Приложение зависает

**Решение:**
- Обычно это означает, что Whisper загружает модель (может занять несколько минут)
- Если зависание длится более 5 минут, перезагрузитесь
- Проверьте логи в папке `logs/`

## 📄 Формат сохраняемых отчётов

### DOCX отчёт

Отчёт содержит следующие секции:

```
╔════════════════════════════════════════╗
║ Магнитно-резонансная томография       ║
╚════════════════════════════════════════╝

Ф.И.О: Иванов Иван Иванович
Дата рождения: 15.03.1985
Область исследования: МРТ головы
№ исследования: 12345
Дата исследования: 16.01.2026

Протокол обследования:
────────────────────
[Полная скорректированная транскрипция]

Заключение:
──────────
[Итоговое заключение]

Рекомендовано:
──────────────
[Рекомендации врача]

────────────────────────────────────────
Врач - рентгенолог                    Петров П.П.

16.01.2026

Внимание! Данное заключение не является диагнозом...
```

### JSON результаты

Сохраняются оригинальные и скорректированные версии в JSON:

```json
{
  "timestamp": "2026-01-16T12:05:30",
  "audio_file": "path/to/audio.wav",
  "transcription": "оригинальный текст...",
  "corrections": [
    {
      "type": "correction",
      "original": "неверное слово",
      "corrected": "верное слово"
    }
  ]
}
```

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

1. **Чистое аудио** - лучше результат
   - Избегайте фонового шума
   - Говорите чётко и не слишком быстро
   - Используйте хороший микрофон

2. **Правильная область исследования** - более точные отчёты
   - Укажите конкретное исследование (МРТ, КТ, УЗ и т.д.)
   - Указание области помогает коррекции

3. **Используйте LLM коррекцию** - качество на 30-50% выше
   - Немного дороже, но результат лучше
   - Используйте более мощные модели для сложных текстов

4. **Сохраняйте историю** - легче найти предыдущие отчёты
   - Все результаты автоматически сохраняются
   - Используйте номера исследований для организации

## 📞 Техподдержка

Если возникла проблема, проверьте:

1. **Папка логов** (`logs/`)
   - Откройте последний лог-файл
   - Ищите сообщения об ошибках

2. **Консоль Python** (если запускаете через `python run_gui.py`)
   - Там видны детальные ошибки

3. **Попытайтесь воспроизвести**
   - Попробуйте с другим аудиофайлом
   - Проверьте сетевое подключение (для API)

---

**Версия:** 1.0
**Дата:** Январь 2026
**Язык:** Русский