Інструкції для тестування голосових повідомлень та 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