Перейти к содержанию

Mode

На этой странице Hermes Agent поддерживает полноценное голосовое взаимодействие через CLI и мессенджеры. Разговаривайте с агентом через микрофон, слушайте голосовые ответы и ведите живые голосовые беседы в голосовых каналах Discord. Если вы хотите получить практическое руководство по настройке с рекомендуемыми конфигурациями и реальными сценариями использования, смотрите Использование голосового режима с Hermes.

Предварительные требования​

Перед использованием голосовых функций убедитесь, что у вас есть: 1. Установленный Hermes Agent — pip install hermes-agent (см. Установка) 2. Настроенный LLM-провайдер — запустите hermes model или укажите учётные данные провайдера в ~/.hermes/.env 3. Работающая базовая настройка — выполните hermes, чтобы убедиться, что агент отвечает на текст, прежде чем включать голос

tip Директория ~/.hermes/ и файл config.yaml по умолчанию создаются автоматически при первом запуске hermes. Вам нужно только вручную создать ~/.hermes/.env для API-ключей.

Обзор​

Функция Платформа Описание
Интерактивный голос CLI Нажмите Ctrl+B для записи, агент автоматически определяет тишину и отвечает
Автоответ голосом Telegram, Discord Агент отправляет голосовое сообщение вместе с текстовым ответом
Голосовой канал Discord Бот заходит в голосовой канал, слушает говорящих пользователей, отвечает голосом
## Требования​
### Пакеты Python​
[code]
# CLI голосовой режим (микрофон + воспроизведение звука)
pip install "hermes-agent[voice]" 
# Discord + Telegram (включает discord.py[voice] для поддержки голосовых каналов)  
pip install "hermes-agent[messaging]"

# Премиум TTS (ElevenLabs)  
pip install "hermes-agent[tts-premium]"

# Локальный TTS (NeuTTS, опционально)  
python -m pip install -U neutts[all]

# Всё сразу  
pip install "hermes-agent[all]"

[/code] Дополнение| Пакеты| Требуется для
---|---|---
voice| sounddevice, numpy| CLI голосовой режим
messaging| discord.py[voice], python-telegram-bot, aiohttp| Боты Discord и Telegram
tts-premium| elevenlabs| TTS-провайдер ElevenLabs
Опциональный локальный TTS-провайдер: установите neutts отдельно через python -m pip install -U neutts[all]. При первом использовании модель загружается автоматически. info discord.py[voice] автоматически устанавливает PyNaCl (для шифрования голоса) и привязки opus. Это необходимо для поддержки голосовых каналов Discord.

Системные зависимости​

[code] # macOS
brew install portaudio ffmpeg opus
brew install espeak-ng # для NeuTTS 

# Ubuntu/Debian  
sudo apt install portaudio19-dev ffmpeg libopus0  
sudo apt install espeak-ng   # для NeuTTS

[/code] Зависимость| Назначение| Требуется для
---|---|---
PortAudio| Ввод с микрофона и воспроизведение звука| CLI голосовой режим
ffmpeg| Конвертация аудиоформатов (MP3 → Opus, PCM → WAV)| Все платформы
Opus| Кодек для голоса в Discord| Голосовые каналы Discord
espeak-ng| Бэкенд фонемизатора| Локальный провайдер NeuTTS

API-ключи​

Добавьте в ~/.hermes/.env: [code] # Speech-to-Text — локальному провайдеру НЕ нужен ключ
# pip install faster-whisper # Бесплатно, работает локально, рекомендуется
GROQ_API_KEY=your-key # Groq Whisper — быстро, бесплатный тариф (облако)
VOICE_TOOLS_OPENAI_KEY=your-key # OpenAI Whisper — платный (облако) 

# Text-to-Speech (опционально — Edge TTS и NeuTTS работают без ключа)  
ELEVENLABS_API_KEY=***           # ElevenLabs — премиум качество  
# VOICE_TOOLS_OPENAI_KEY выше также включает OpenAI TTS

[/code] tip Если установлен faster-whisper, голосовой режим работает без каких-либо API-ключей для STT. Модель (~150 МБ для base) загружается автоматически при первом использовании.

CLI Голосовой режим​

Голосовой режим доступен как в классическом CLI (hermes chat), так и в TUI (hermes --tui). Поведение идентично в обоих — те же слэш-команды, то же VAD-определение тишины, тот же стриминг TTS, тот же фильтр галлюцинаций. TUI дополнительно направляет crash-forensic логи в ~/.hermes/logs/, так что ошибки push-to-talk на экзотических аудио-бэкендах можно сообщать с полным стектрейсом, а не терять их бесследно.

Быстрый старт​

Запустите CLI и включите голосовой режим: [code] hermes # Запуск интерактивного CLI

[/code] Затем используйте эти команды внутри CLI: [code] /voice Включить/выключить голосовой режим
/voice on Включить голосовой режим
/voice off Выключить голосовой режим
/voice tts Включить/выключить TTS
/voice status Показать текущее состояние

[/code]

Как это работает​

  1. Запустите CLI командой hermes и включите голосовой режим через /voice on
  2. Нажмите Ctrl+B — звучит звуковой сигнал (880 Гц), начинается запись
  3. Говорите — индикатор уровня звука показывает ваш вход: ● [▁▂▃▅▇▇▅▂] ❯
  4. Перестаньте говорить — после 3 секунд тишины запись автоматически останавливается
  5. Два сигнала (660 Гц) подтверждают окончание записи
  6. Аудио транскрибируется через Whisper и отправляется агенту
  7. Если TTS включён, ответ агента озвучивается
  8. Запись автоматически перезапускается — говорите снова без нажатия каких-либо клавиш

Этот цикл продолжается, пока вы не нажмёте Ctrl+B во время записи (выход из непрерывного режима) или 3 последовательные записи не обнаружат речь. tip Клавиша записи настраивается через voice.record_key в ~/.hermes/config.yaml (по умолчанию: ctrl+b).

Определение тишины​

Двухэтапный алгоритм определяет, когда вы закончили говорить: 1. Подтверждение речи — ждёт аудио выше порога RMS (200) в течение как минимум 0,3 с, допуская кратковременные провалы между слогами 2. Обнаружение окончания — после подтверждения речи срабатывает через 3,0 секунды непрерывной тишины

Если речь не обнаружена вообще в течение 15 секунд, запись останавливается автоматически. Оба параметра — silence_threshold и silence_duration — настраиваются в config.yaml. Вы также можете отключить звуковые сигналы начала/окончания записи с помощью voice.beep_enabled: false.

Стриминг TTS​

Когда TTS включён, агент озвучивает ответ предложение за предложением по мере генерации текста — вам не нужно ждать полного ответа: 1. Буферизирует изменения текста в полные предложения (минимум 20 символов) 2. Удаляет markdown-разметку и блоки <think> 3. Генерирует и воспроизводит аудио по предложениям в реальном времени

Фильтр галлюцинаций​

Whisper иногда генерирует вымышленный текст из тишины или фонового шума («Спасибо за просмотр», «Подпишитесь» и т.д.). Агент отфильтровывает их с помощью набора из 26 известных фраз-галлюцинаций на нескольких языках, а также регулярного выражения, которое ловит повторяющиеся вариации.

Голосовые ответы шлюза (Telegram и Discord)​

Если вы ещё не настроили своих ботов для мессенджеров, смотрите руководства по платформам: * Руководство по настройке Telegram * Руководство по настройке Discord

Запустите шлюз для подключения к вашим мессенджерам: [code] hermes gateway # Запуск шлюза (подключается к настроенным платформам)
hermes gateway setup # Интерактивный мастер настройки для первичной конфигурации

[/code]

Discord: Каналы и ЛС​

Бот поддерживает два режима взаимодействия в Discord: Режим| Как общаться| Требуется упоминание| Настройка
---|---|---|---|---
Личные сообщения (ЛС)| Откройте профиль бота → «Сообщение»| Нет| Работает сразу
Серверный канал| Пишите в текстовом канале, где присутствует бот| Да (@имябота)| Бот должен быть приглашён на сервер
ЛС (рекомендуется для личного использования): Просто откройте ЛС с ботом и пишите — @упоминание не нужно. Голосовые ответы и все команды работают так же, как в каналах. Серверные каналы: Бот отвечает только когда вы упоминаете его через @ (например, @hermesbyt4 привет). Убедитесь, что во всплывающем окне упоминания вы выбираете пользователя бота, а не роль с тем же именем. tip Чтобы отключить требование упоминания в серверных каналах, добавьте в ~/.hermes/.env: [code] DISCORD_REQUIRE_MENTION=false

[/code] Или укажите конкретные каналы для свободного ответа (без упоминания): [code] DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

[/code]

Команды​

Эти команды работают в Telegram и Discord (ЛС и текстовые каналы): [code] /voice Включить/выключить голосовой режим
/voice on Голосовые ответы только при отправке голосового сообщения
/voice tts Голосовые ответы для ВСЕХ сообщений
/voice off Отключить голосовые ответы
/voice status Показать текущую настройку

[/code]

Режимы​

Режим Команда Поведение
off /voice off Только текст (по умолчанию)
voice_only /voice on Озвучивает ответ только при отправке голосового сообщения
all /voice tts Озвучивает ответ на каждое сообщение
Настройка голосового режима сохраняется между перезапусками шлюза.
### Доставка на платформы​
Платформа Формат Примечания
--- --- ---
Telegram Голосовое сообщение (Opus/OGG) Воспроизводится в чате. ffmpeg конвертирует MP3 → Opus при необходимости
Discord Нативное голосовое сообщение (Opus/OGG) Воспроизводится как голосовое сообщение пользователя. Возвращается к файловому вложению, если API голосовых сообщений не срабатывает
* * *
## Голосовые каналы Discord​
Самая захватывающая голосовая функция: бот заходит в голосовой канал Discord, слушает говорящих пользователей, транскрибирует их речь, обрабатывает через агента и озвучивает ответ в голосовом канале.
### Настройка​
#### 1\. Разрешения бота Discord​
Если у вас уже есть бот Discord для текста (см. Руководство по настройке Discord), вам нужно добавить голосовые разрешения.
Перейдите на Портал разработчиков Discord → ваше приложение → Installation → Default Install Settings → Guild Install:
Добавьте следующие разрешения к существующим текстовым разрешениям:
Разрешение Назначение Требуется
--- --- ---
Подключаться (Connect) Заходить в голосовые каналы Да
Говорить (Speak) Воспроизводить TTS-аудио в голосовых каналах Да
Использовать голосовую активность (Use Voice Activity) Определять, когда пользователи говорят Рекомендуется
Обновлённое целое число разрешений:
Уровень Целое число Что включено
--- --- ---
Только текст 274878286912 Просмотр каналов, отправка сообщений, чтение истории, вставки, вложения, ветки, реакции
Текст + Голос 274881432640 Всё выше + Подключаться, Говорить
Повторно пригласите бота с обновлённым URL разрешений:
[code]
https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274881432640

[/code] Замените YOUR_APP_ID на ID вашего приложения с Портала разработчиков. warning Повторное приглашение бота на сервер, где он уже находится, обновит его разрешения без удаления. Вы не потеряете никакие данные или настройки.

2\. Привилегированные намерения шлюза​

На Портале разработчиков → ваше приложение → Bot → Privileged Gateway Intents включите все три: Намерение| Назначение
---|---
Presence Intent| Определение статуса пользователя (в сети/не в сети)
Server Members Intent| Преобразование имён пользователей в DISCORD_ALLOWED_USERS в числовые ID (условно)
Message Content Intent| Чтение содержимого текстовых сообщений в каналах
Message Content Intent обязателен. Server Members Intent нужен только если ваш список DISCORD_ALLOWED_USERS использует имена пользователей — если вы используете числовые ID пользователей, его можно оставить выключенным. Привязка SSRC голосового канала к user_id поступает из опкода SPEAKING Discord через голосовой вебсокет и не требует Server Members Intent.

3\. Кодек Opus​

Библиотека кодека Opus должна быть установлена на машине, где запущен шлюз: [code] # macOS (Homebrew)
brew install opus 

# Ubuntu/Debian  
sudo apt install libopus0

[/code] Бот автоматически загружает кодек из: * macOS: /opt/homebrew/lib/libopus.dylib * Linux: libopus.so.0

4\. Переменные окружения​

[code] # ~/.hermes/.env 

# Discord бот (уже настроен для текста)  
DISCORD_BOT_TOKEN=ваш-токен-бота  
DISCORD_ALLOWED_USERS=ваш-id-пользователя

# STT — локальному провайдеру не нужен ключ (pip install faster-whisper)  
# GROQ_API_KEY=ваш-ключ            # Альтернатива: облачный, быстрый, бесплатный тариф

# TTS — опционально. Edge TTS и NeuTTS не требуют ключа.  
# ELEVENLABS_API_KEY=***      # Премиум качество  
# VOICE_TOOLS_OPENAI_KEY=***  # OpenAI TTS / Whisper

[/code]

Запуск шлюза​

[code] hermes gateway # Запуск с существующей конфигурацией

[/code] Бот должен появиться в сети в Discord в течение нескольких секунд.

Команды​

Используйте их в текстовом канале Discord, где присутствует бот: [code] /voice join Бот заходит в ваш текущий голосовой канал
/voice channel Псевдоним для /voice join
/voice leave Бот отключается от голосового канала
/voice status Показать голосовой режим и подключённый канал

[/code] info Вы должны находиться в голосовом канале перед выполнением /voice join. Бот присоединяется к тому же голосовому каналу, где и вы.

Как это работает​

Когда бот заходит в голосовой канал, он: 1. Слушает аудиопоток каждого пользователя независимо 2. Определяет тишину — 1,5 с тишины после как минимум 0,5 с речи запускает обработку 3. Транскрибирует аудио через Whisper STT (локальный, Groq или OpenAI) 4. Обрабатывает через полный конвейер агента (сессия, инструменты, память) 5. Озвучивает ответ в голосовом канале через TTS

Интеграция с текстовым каналом​

Когда бот находится в голосовом канале: * Транскрипты появляются в текстовом канале: [Voice] @user: что вы сказали * Ответы агента отправляются в виде текста в канал И озвучиваются в голосовом канале * Текстовый канал — это тот, в котором была выполнена команда /voice join

Предотвращение эха​

Бот автоматически приостанавливает прослушивание аудио во время воспроизведения TTS-ответов, предотвращая повторную обработку собственного вывода.

Контроль доступа​

Только пользователи, перечисленные в DISCORD_ALLOWED_USERS, могут взаимодействовать через голос. Аудио других пользователей молча игнорируется. [code] # ~/.hermes/.env
DISCORD_ALLOWED_USERS=284102345871466496

[/code]

Справочник по конфигурации​

config.yaml​

[code] # Голосовая запись (CLI)
voice:
record_key: "ctrl+b" # Клавиша для начала/остановки записи
max_recording_seconds: 120 # Максимальная длина записи
auto_tts: false # Автовключение TTS при запуске голосового режима
beep_enabled: true # Воспроизводить сигналы начала/остановки записи
silence_threshold: 200 # Уровень RMS (0-32767), ниже которого считается тишиной
silence_duration: 3.0 # Секунд тишины до автоостановки 

# Speech-to-Text  
stt:  
  provider: "local"                  # "local" (бесплатно) | "groq" | "openai"  
  local:  
    model: "base"                    # tiny, base, small, medium, large-v3  
  # model: "whisper-1"              # Устаревшее: используется, когда провайдер не указан

# Text-to-Speech  
tts:  
  provider: "edge"                 # "edge" (бесплатно) | "elevenlabs" | "openai" | "neutts" | "minimax"  
  edge:  
    voice: "en-US-AriaNeural"      # 322 голоса, 74 языка  
  elevenlabs:  
    voice_id: "pNInz6obpgDQGcFmaJgB"    # Adam  
    model_id: "eleven_multilingual_v2"  
  openai:  
    model: "gpt-4o-mini-tts"  
    voice: "alloy"                 # alloy, echo, fable, onyx, nova, shimmer  
    base_url: "https://api.openai.com/v1"  # опционально: переопределение для собственного хостинга или OpenAI-совместимых эндпоинтов  
  neutts:  
    ref_audio: ''  
    ref_text: ''  
    model: neuphonic/neutts-air-q4-gguf  
    device: cpu

[/code]

Переменные окружения​

[code] # Провайдеры Speech-to-Text (локальному не нужен ключ)
# pip install faster-whisper # Бесплатный локальный STT — API-ключ не нужен
GROQ_API_KEY=... # Groq Whisper (быстрый, бесплатный тариф)
VOICE_TOOLS_OPENAI_KEY=... # OpenAI Whisper (платный) 

# Продвинутые переопределения STT (опционально)  
STT_GROQ_MODEL=whisper-large-v3-turbo    # Переопределение модели Groq STT по умолчанию  
STT_OPENAI_MODEL=whisper-1               # Переопределение модели OpenAI STT по умолчанию  
GROQ_BASE_URL=https://api.groq.com/openai/v1     # Пользовательский эндпоинт Groq  
STT_OPENAI_BASE_URL=https://api.openai.com/v1    # Пользовательский эндпоинт OpenAI STT

# Провайдеры Text-to-Speech (Edge TTS и NeuTTS не требуют ключа)  
ELEVENLABS_API_KEY=***             # ElevenLabs (премиум качество)  
# VOICE_TOOLS_OPENAI_KEY выше также включает OpenAI TTS

# Голосовой канал Discord  
DISCORD_BOT_TOKEN=...  
DISCORD_ALLOWED_USERS=...

[/code]

Сравнение STT-провайдеров​

Провайдер Модель Скорость Качество Стоимость API-ключ
Локальный base Быстро (зависит от CPU/GPU) Хорошее Бесплатно Нет
Локальный small Средне Лучше Бесплатно Нет
Локальный large-v3 Медленно Лучшее Бесплатно Нет
Groq whisper-large-v3-turbo Очень быстро (~0,5 с) Хорошее Бесплатный тариф Да
Groq whisper-large-v3 Быстро (~1 с) Лучше Бесплатный тариф Да
OpenAI whisper-1 Быстро (~1 с) Хорошее Платно Да
OpenAI gpt-4o-transcribe Средне (~2 с) Лучшее Платно Да
Приоритет провайдера (автоматический переход): local > groq > openai
### Сравнение TTS-провайдеров​
Провайдер Качество Стоимость Задержка Требуется ключ
--- --- --- --- --- ---
Edge TTS Хорошее Бесплатно ~1 с Нет
ElevenLabs Отличное Платно ~2 с Да
OpenAI TTS Хорошее Платно ~1,5 с Да
NeuTTS Хорошее Бесплатно Зависит от CPU/GPU Нет
NeuTTS использует блок конфигурации tts.neutts выше.
* * *
## Устранение неполадок​
### «Аудиоустройство не найдено» (CLI)​
PortAudio не установлен:
[code]
brew install portaudio # macOS
sudo apt install portaudio19-dev # Ubuntu

[/code]

Бот не отвечает в серверных каналах Discord​

По умолчанию бот требует @упоминание в серверных каналах. Убедитесь, что вы: 1. Набираете @ и выбираете пользователя бота (с #дискриминатором), а не роль с тем же именем 2. Или используете ЛС — упоминание не требуется 3. Или установите DISCORD_REQUIRE_MENTION=false в ~/.hermes/.env

Бот заходит в голосовой канал, но не слышит меня​

  • Проверьте, что ваш ID пользователя Discord есть в DISCORD_ALLOWED_USERS
  • Убедитесь, что вы не в режиме «Заглушён» в Discord
  • Боту нужно событие SPEAKING от Discord, прежде чем он сможет сопоставить ваше аудио — начните говорить в течение нескольких секунд после подключения

Бот слышит меня, но не отвечает​

  • Проверьте доступность STT: установите faster-whisper (ключ не нужен) или настройте GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
  • Проверьте, что LLM-модель настроена и доступна
  • Просмотрите логи шлюза: tail -f ~/.hermes/logs/gateway.log

Бот отвечает текстом, но не в голосовом канале​

  • Возможно, TTS-провайдер не работает — проверьте API-ключ и квоту
  • Edge TTS (бесплатно, без ключа) используется по умолчанию как запасной вариант
  • Проверьте логи на наличие ошибок TTS

Whisper возвращает мусорный текст​

Фильтр галлюцинаций ловит большинство случаев автоматически. Если вы всё ещё получаете ложные транскрипты: * Используйте более тихое окружение * Отрегулируйте silence_threshold в конфиге (выше = менее чувствительно) * Попробуйте другую STT-модель