Skip to content

# Інструкції для тестування голосових повідомлень та PDF файлів

Дата: 2025-11-18
Статус: ✅ Імплементовано

## ✅ Що працює зараз

### 1. Голосові повідомлення (STT)

- Формати: voice, audio, video_note (кружечки)
- Обробка:
- Telegram Gateway отримує голосове
- Завантажує через Local Telegram Bot API
- Відправляє на `dagi-stt:9000/stt` (Whisper)
- Отримує транскрибований текст
- Публікує в NATS як текстове повідомлення
- Router обробляє як звичайний текст
- Бот відповідає

### 2. PDF Документи

- Формати: PDF (`application/pdf` або `.pdf`)
- Обробка:
- Telegram Gateway отримує документ
- Перевіряє, чи це PDF
- Отримує `file_url` через Telegram API
- Публікує в NATS з `metadata.document`
- Router може викликати Parser Service
- Бот відповідає результатом парсингу

## 🧪 Як протестувати

### Test 1: Голосове повідомлення (українською)

Кроки: 1. Відкрити Telegram 2. Знайти одного з ботів: - `@DAARWIZZBot` - `@energyunionBot` (Helion) - `@greenfoodliveBot` (GREENFOOD) 3. Натиснути мікрофон та записати: "Привіт, як справи?" 4. Відправити

Очікуваний результат:

    Ти → 🎤 [Голосове 3 сек]
    Бот → 🎤 Обробляю голосове повідомлення...
    Бот → Привіт! У мене все добре, дякую що запитав. Чим можу допомогти?

Логи (якщо щось не так):

    ssh root@144.76.224.179 "docker logs --tail 50 telegram-gateway | grep -E '(🎤|voice|transcrib)'"
    ssh root@144.76.224.179 "docker logs --tail 20 dagi-stt | grep -E '(POST|/stt)'"

### Test 2: Голосове повідомлення (англійською)

Кроки: 1. Записати голосове: "Hello, what can you do?" 2. Відправити

Очікуваний результат:

    Ти → 🎤 [Голосове 2 сек]
    Бот → 🎤 Обробляю голосове повідомлення...
    Бот → Hello! I can help you with...

### Test 3: Довге голосове (> 10 секунд)

Кроки: 1. Записати довге голосове (15-30 сек) 2. Розповісти про щось (проєкт, ідея, питання) 3. Відправити

Очікуваний результат: - Транскрипція має зайняти 5-15 секунд - Бот має відповісти на основі транскрибованого тексту - Якщо > 30 сек - можлива timeout помилка

### Test 4: PDF документ

Кроки: 1. Підготувати PDF файл (будь-який, < 10 MB) 2. Відправити як файл боту 3. Дочекатися відповіді

Очікуваний результат:

    Ти → 📄 document.pdf (500 KB)
    Бот → 📄 Обробляю документ: document.pdf...
    Бот → [Результат парсингу або повідомлення що документ отримано]

Примітка: Повна обробка PDF через Parser потребує додаткової інтеграції в `router_handler.py`.

### Test 5: Не-PDF документ (DOCX, TXT)

Кроки: 1. Відправити DOCX або TXT файл 2. Дочекатися відповіді

Очікуваний результат: - Бот не має відповісти "Обробляю документ" - Документ має бути проігнорований (немає обробки) - Логи: `⏭️ Skipping non-PDF document`

## 🐛 Troubleshooting

### Проблема 1: Бот не відповідає на голосове

Діагностика:

    # 1. Перевірити логи telegram-gateway
    ssh root@144.76.224.179 "docker logs --tail 100 telegram-gateway | grep -E '(🎤|voice|ERROR)'"

    # 2. Перевірити чи працює STT
    ssh root@144.76.224.179 "docker ps | grep dagi-stt"
    ssh root@144.76.224.179 "docker logs --tail 50 dagi-stt"

    # 3. Тест STT вручну
    ssh root@144.76.224.179 "curl -X POST http://localhost:9000/stt -F 'file=@test_audio.ogg'"

Можливі причини: - STT сервіс не запущено - Помилка завантаження аудіо з Telegram - Timeout (файл занадто великий) - Формат аудіо не підтримується

Рішення:

    # Перезапустити STT
    docker restart dagi-stt

    # Перезапустити telegram-gateway
    docker restart telegram-gateway

### Проблема 2: STT повертає пусту транскрипцію

Діагностика:

    docker logs dagi-stt | grep -i "transcrib\\|text"

Можливі причини: - Занадто тихе/шумне аудіо - Дуже короткий файл (< 1 сек) - Мова не підтримується

Рішення: - Говорити чіткіше та голосніше - Записувати мінімум 2-3 секунди - Використовувати українську/англійську

### Проблема 3: Бот не реагує на PDF

Діагностика:

    ssh root@144.76.224.179 "docker logs --tail 100 telegram-gateway | grep -E '(📄|document|pdf)'"

Можливі причини: - Файл занадто великий (> 50 MB) - Не PDF формат - Router handler не обробляє документи

Рішення: - Перевірити `router_handler.py` для обробки `metadata.document` - Додати інтеграцію з Parser Service

## 📊 Логи для діагностики

### Telegram Gateway

    # Всі повідомлення
    docker logs --tail 100 telegram-gateway

    # Тільки voice/document
    docker logs --tail 200 telegram-gateway | grep -E '(🎤|📄|voice|document)'

    # Помилки
    docker logs --tail 100 telegram-gateway | grep ERROR

### STT Service

    # Останні транскрипції
    docker logs --tail 50 dagi-stt | grep -E '(transcrib|POST /stt)'

    # Помилки
    docker logs --tail 100 dagi-stt | grep -E '(ERROR|error|exception)'

### Parser Service

    # Останні парсинги
    docker logs --tail 50 dagi-parser | grep -E '(POST /ocr|parse)'

    # Помилки
    docker logs --tail 100 dagi-parser | grep ERROR

## ✅ Критерії успіху

### Голосові повідомлення:

- [x] Бот відправляє "🎤 Обробляю голосове повідомлення..."
- [x] Транскрипція займає < 10 сек (для 5-10 сек аудіо)
- [x] Бот відповідає на основі транскрибованого тексту
- [x] Підтримка української та англійської

### PDF документи:

- [x] Бот відправляє "📄 Обробляю документ: filename.pdf..."
- [x] Документ публікується в NATS з `metadata.document`
- [ ] Router викликає Parser Service (потребує інтеграції)
- [ ] Бот повертає результат парсингу

## 🚀 Наступні кроки

### 1. Інтеграція PDF з Parser (пріоритет 🔴)

Додати в `router_handler.py`:

    # If event has document metadata
    if event.metadata and "document" in event.metadata:
        doc_info = event.metadata["document"]
        # Call Parser Service
        # Return parsed result

### 2. TTS інтеграція (пріоритет 🟡)

- Додати опцію для голосових відповідей
- Користувач може отримувати відповідь голосом

### 3. Оптимізація STT (пріоритет 🟢)

- Використовувати `tiny` або `base` модель Whisper
- Додати GPU підтримку
- Кешування для повторюваних фраз

Тест створено: 2025-11-18
Оновлено: після імплементації voice/document handlers