stt/README.md

STT Module

Модуль транскрибации речи в текст (Speech-to-Text) на базе Whisper.

Структура

stt/
├── __init__.py              # Экспорты модуля
├── whisper_transcriber.py   # Основной класс транскрибера
├── audio_processor.py       # Обработка аудио
└── README.md                # Документация

WhisperTranscriber

Основной класс для транскрибации медицинских диктовок.

Возможности

• ✅ Поддержка GPU/CPU
• ✅ Локальные модели Whisper
• ✅ Медицинские промпты для улучшения точности
• ✅ Различные форматы аудио (wav, mp3, flac и др.)
• ✅ Временные метки (timestamps)
• ✅ Автоматический выбор устройства

Примеры использования

Базовая транскрибация

from stt import WhisperTranscriber
from pathlib import Path

# Инициализация
transcriber = WhisperTranscriber(
    model_path=Path("./"),  # путь к папке с моделью
    device="auto",          # auto, cuda, cpu
    dtype="float32",        # float32, float16, bfloat16
    language="russian"
)

# Транскрибация файла
result = transcriber.transcribe_file(
    audio_path=Path("audio.wav")
)

print(f"Текст: {result['text']}")

С медицинским промптом

from stt import WhisperTranscriber
from knowledge_base import MedicalTermManager

# Загружаем медицинские термины
term_manager = MedicalTermManager("medical_terms.txt")
medical_prompt = term_manager.get_terms_as_text()

# Инициализация транскрибера
transcriber = WhisperTranscriber(model_path=Path("./"))

# Транскрибация с промптом
result = transcriber.transcribe_file(
    audio_path=Path("medical_dictation.wav"),
    medical_prompt=medical_prompt
)

print(result['text'])

С временными метками

result = transcriber.transcribe_file(
    audio_path=Path("audio.wav"),
    return_timestamps=True
)

print(f"Текст: {result['text']}")
print(f"Временные метки:")
for chunk in result['timestamps']:
    print(f"  {chunk['timestamp']}: {chunk['text']}")

Обработка аудио

from stt import load_audio, resample_audio, get_audio_duration

# Загрузка аудио
audio = load_audio(Path("audio.wav"), sr=16000)

# Получить длительность
duration = get_audio_duration(audio, sr=16000)
print(f"Длительность: {duration:.2f} сек")

# Ресемплинг
audio_resampled = resample_audio(audio, orig_sr=16000, target_sr=8000)

Информация о модели

transcriber = WhisperTranscriber(model_path=Path("./"))
info = transcriber.get_model_info()

print(f"Модель: {info['model_path']}")
print(f"Устройство: {info['device']}")
print(f"CUDA доступна: {info['cuda_available']}")
if info['cuda_device_name']:
    print(f"GPU: {info['cuda_device_name']}")

Интеграция с pipeline

from stt import WhisperTranscriber
from knowledge_base import MedicalTermManager
from corrector import MedicalLLMCorrector

# Шаг 1: Загрузка медицинских терминов
term_manager = MedicalTermManager("medical_terms.txt")
medical_prompt = term_manager.get_terms_as_text()

# Шаг 2: STT транскрибация
transcriber = WhisperTranscriber(model_path=Path("./"))
stt_result = transcriber.transcribe_file(
    audio_path=Path("dictation.wav"),
    medical_prompt=medical_prompt
)

original_text = stt_result['text']
print(f"STT: {original_text}")

# Шаг 3: LLM коррекция
corrector = MedicalLLMCorrector()
corrector.medical_terms = medical_prompt
corrected_text, corrections = corrector.correct_transcription(original_text)

print(f"LLM: {corrected_text}")
print(f"Исправлений: {len(corrections)}")

Параметры WhisperTranscriber

init

• model_path (Path): Путь к папке с моделью Whisper
• device (str): Устройство для вычислений
  • "auto" - автоматический выбор (CUDA > MPS > CPU)
  • "cuda" - NVIDIA GPU
  • "cpu" - Процессор
• dtype (str): Тип данных
  • "float32" - полная точность (медленнее, но точнее)
  • "float16" - половинная точность (быстрее, GPU)
  • "bfloat16" - brain float (оптимально для новых GPU)
• language (str): Язык транскрибации (по умолчанию "russian")

transcribe / transcribe_file

• audio / audio_path: Аудио данные или путь к файлу
• medical_prompt (Optional[str]): Медицинский промпт для улучшения точности
• return_timestamps (bool): Возвращать временные метки

Audio Processor Functions

load_audio(audio_path, sr=16000)

Загрузить аудио файл с автоматическим ресемплингом.

resample_audio(audio, orig_sr, target_sr)

Изменить частоту дискретизации.

get_audio_duration(audio, sr=16000)

Получить длительность аудио в секундах.

validate_audio(audio_path)

Проверить валидность аудио файла.

Поддерживаемые форматы аудио

• WAV
• MP3
• FLAC
• OGG
• M4A
• WMA

Все форматы автоматически конвертируются в нужную частоту дискретизации (16000 Hz).

Требования

torch>=2.3.0
transformers>=4.44.0
librosa>=0.10.2
soundfile>=0.12.1

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

GPU (CUDA)

• float16: ~10x быстрее CPU
• bfloat16: оптимально для A100/H100

CPU

• float32: высокая точность, медленно
• Рекомендуется для небольших файлов

Troubleshooting

CUDA out of memory

Используйте dtype="float16" или уменьшите размер аудио.

Низкая точность транскрибации

1. Добавьте медицинский промпт
2. Проверьте качество аудио
3. Используйте более крупную модель Whisper