Irene-Voice-Assistant

Голосовой ассистент Ирина

Ирина - русский голосовой ассистент для работы оффлайн. Требует Python 3.5+ (зависимость может быть меньше, но в любом случае Python 3)

Поддерживает плагины (скиллы).

Статья на Хабре | Вторая статья на Хабре | Третья статья на Хабре | Четвертая статья на Хабре - про 12 версию и ИИ-плагины | Группа в Телеграм

Через сервис VseGPT.ru, еще один проект автора Ирины:

• Поддерживает общение с ChatGPT, GPT-4, Claude 3.
• Поддерживает получение справочной информации из Интернета (команда справка) с помощью специальных моделей Perplexity Online.
• Поддерживает TTS от OpenAI (если сложно установить что-то локально) (Инструкция по настройке плагина). (Также можно использовать любой OpenAI-совместимый endpoint)

Установка

Самая быстрая установка под Windows

Зайдите в https://github.com/janvarev/Irene-VA-win-installer, скачайте код (Code/Download ZIP) и следуйте инструкциям.

После установки будут доступны следующие команды: "ирина привет", "ирина подбрось монетку", "ирина подбрось кубик", "ирина игра больше меньше", "ирина таймер три минуты"

Для донастройки или решения проблем запустите start-settings-manager.bat для запуска менеджера настроек - вы сможете донастроить плагины, и узнаете дополнительные команды.

Ещё доки по донастройке этот варианта: docs/INSTALL_WIN_COMPACT.md

Самая быстрая установка под Windows 2 (устарело)

1. Зайдите в релизы: https://github.com/janvarev/Irene-Voice-Assistant/releases
2. Скачайте релиз и следуйте инструкции. Python и GIT идут в релизе, ничего ставить не нужно.

После установки будут доступны оффлайн-команды (т.к. это дефолтовая конфигурация). Пример: "ирина привет", "ирина подбрось монетку", "ирина подбрось кубик", "ирина игра больше меньше", "ирина таймер три минуты"

Как донастроить этот вариант: docs/INSTALL_WIN_COMPACT.md

Установка / быстрый старт

Вам потребуется установленный Python (ориентировочно 3.7-3.11).

1. Для быстрой установки всех требуемых зависимостей можно воспользоваться командой: pip install -r requirements.txt

Если вы хотите установить зависимости с фиксированными проверенными версиями (для более стабильной работы), используйте: pip install -r requirements_fixed.txt

(Для Linux и macOS - предварительно установите пакеты для audioplayer)

2. Для запуска запустите файл runva_vosk.py из корневой папки. По умолчанию он запустит оффлайн-распознаватель vosk для распознавания речи с микрофона, и pyttsx движок для озвучивания ассистента Подробнее о pyttsx здесь.

3. После запуска проверить можно простой командой - скажите "Ирина, привет!" в микрофон

Папка с настройками options появится после первого запуска Ирины, в ней можно поправить настройки.

Более пошаговая инфа про установку на Win (в особенности Win 7): docs/INSTALL_WIN.md

Решение некоторых проблем при установке под Linux: docs/INSTALL_LINUX.md

Решение некоторых проблем при установке под Mac: docs/INSTALL_MAC.md

Принципы отладки при проблемах при установке: docs/INSTALL_DEBUG.md

Баги можно писать в ISSUES, обсуждать - в Телеграм

Менеджер настроек

C версии 9.0 доступен веб менеджер настроек через gradio.

Для запуска запустите файл runva_settings_manager.py из корневой папки.

Версия 13.0 - VOSK streaming STT 0.56, распознавание уровня Whisper

В версии 13.0 добавлена опция запуска с моделью vosk-stt-0.56 Эта модель значительно новее (сентябрь 2025 года), и по данным бенчмарка в общем-то даже лучше Whisper - но при этом работает

• в стриминговом режиме (минимальная задержка)
• у вас на компьютере локально (а не в сети)

Для сравнения - процент ошибок распознавания (WER) на бенчмарке Sova devices (меньше - лучше)

• vosk-small-0.22 (старая модель) - 29.89 источник
• vosk-0.54 (у нас 0.56, вероятно, чуть лучше) - 11.6 источник
• Whisper Large V3 - 15.9 источник

Для запуска:

• Требует: pip install sherpa-onnx sherpa-onnx-bin (для CPU)
• Или больше вариантов (для GPU и пр.) https://k2-fsa.github.io/sherpa/onnx/python/install.html
• После чего запустите runva_vosk_sherpa.py

Способы уменьшения потребления ресурсов:

• Модель по умолчанию полная (https://huggingface.co/alphacep/vosk-model-streaming-ru).
• Вы можете там же скачать квантизацию до int8 (8 бит на вес нейросети вместо 32) - это ухудшит качество, но уменьшит потребление памяти
• Или вы можете скачать более маленькую модель отсюда: https://huggingface.co/alphacep/vosk-model-small-streaming-ru

Пока в бета-версии:

• работает только с одним (первым) микрофоном на локальном девайсе
• вариант "по сети" не поддерживаются

Желающие могут доработать для работы в сети - сделать клиенты и прочее.

ИИ-плагины

Бета с версии 12.0

- Ирина, установи таймер на два с половиной часа
- Ставлю таймер на 2 часа 30 минут

ИИ-плагины позволяют вызывать функции текстом в свободной форме. Для реализации используется вызов tools у LLM, см. https://vsegpt.ru/Docs/API#tools. Если по-простому, вызывается большая языковая модель типа ChatGPT, и мы её просим определить, какой именно плагин с какими именно параметрами нужно вызвать на основании нашего словесного ввода в свободной форме.

Вам потребуется доступ к LLM:

• В формате OpenAI-compatible
• Которая поддерживает вызов tools

Для дистанционного варианта вы можете воспользоваться проектом автора https://vsegpt.ru/ - там будут быстрые LLM (OpenAI gpt-4o-mini и другие), которые хорошо это поддерживают. Каждый вызов модели будет тарифицирован, но обычно обойдется всего в несколько копеек для openai/gpt-4o-mini, которая установлена по дефолту. Также есть бесплатное демо на несколько рублей - хватит, чтобы попробовать.

Вы также можете использовать локальные LMStudio или Ollama с моделями, поддерживающими tools. Это, вероятно, будет медленнее, но тоже будет работать. Желающие могут написать инструкцию, и положить её в docs данного проекта.

Для работы вам потребуется: Установить параметры в core для коннекта к моделям, а также список плагинов - например, "ai". ИИ-плагины могут работать и в связке с обычными плагинами, тогда используйте "classic,ai". В приоритете всегда будут классические плагины.

"plugin_types": "default", # список разрешенных ТИПОВ плагинов через ,
# например: classic, ai, или "classic,ai"

"openai_base_url": "https://api.vsegpt.ru/v1",
"openai_key": "",
"openai_tools_model": "openai/gpt-4o-mini",
"openai_tools_system_prompt": "",
"openai_generic_model": "openai/gpt-4o-mini",
"openai_generic_system_prompt": "",

Во-вторых, вам потребуется ИИ-плагин(ы). Вы можете скопировать демо-плагин plugin_ai_timer из папки plugins_inactive

Пока это все для энтузиастов, поэтому инфы мало, подробнее будет позже

Установка через Докер

Если хотите ВСЁ запустить через Докер: docs/INSTALL_DOCKER.md (там же есть образы докера для ARM (малинок и пр.) от Ivan-Firefly)

Если хотите только сложные ключевые компоненты запустить через Докер: docs/INSTALL_DOCKER_COMP.md

Общая логика

Запуск всех команд начинается с имени ассистента (настраивается в options/core.json, по умолчанию - Ирина). Так сделано, чтобы исключить неверные срабатывания при постоянном прослушивании микрофона. Далее будут описываться команды без префикса "Ирина".

В движок встроена поддержка локального управления через веб-интерфейс плейером MPC-HC, так что при прочих равных рекомендуется использовать его. Его можно настроить в options/core.json

Плагины

Поддержка плагинов сделана на собственном движке Jaa.py - минималистичный однофайловый движок поддержки плагинов и их настроек.

Плагины располагаются в папке plugins и должны начинаться с префикса "plugins_".

Настройки плагинов, если таковые есть, располагаются в папке "options" (создается после первого запуска).

Готовые плагины/скиллы (уже в папке plugins)

Для каждого плагина написано, требуется ли онлайн. Для отключения удалите из папки plugins

Полная информация: docs/PLUGINS.md

Сторонние плагины

Если вы хотите узнать:

• какие еще есть плагины от других разработчиков
• запостить ссылку на свой сделанный плагин

Посетите: https://github.com/janvarev/Irene-Voice-Assistant/issues/1

Менеджер плагинов

(С версии 10.0.0) Для запуска запустите runva_plugin_installer.py

ВНИМАНИЕ: Предложенные плагины поддерживаются сторонними разработчиками и они могут дополняться и изменяться! Автор Ирины не несёт ответственности за их содержание!

Для разработчиков: если вы хотите добавить свой плагин в этот список для упрощенной установки, вам нужно будет сделать следующее:

1. Разместить плагин на Гитхабе
2. В корне должны лежать файлы типа plugin_x.py. Может быть несколько
3. Если нужно установить дополнительные модули, должен лежать файл requirements.txt
4. Протестируйте возможность установки, запустив runva_plugin_installer, выбрав пункт 0 (Самостоятельно задать адрес Github-проекта с плагином) и установите свой плагин
5. После всего запостите ссылку на ваш в Issue или сделайте pull request, поменяв plugins_catalog.json, в котором содержатся ссылки на известные допплагины.

Пример оформления плагина: https://github.com/janvarev/irene_plugin_boltalka2_openai

Интеграция с Home Assistant

Есть хороший сторонний плагин, позволяющий запускать сценарии Home Assistant через Ирину: https://github.com/timhok/IreneVA-hassio-script-trigger-plugin

Настройки ядра (core.json)

Настройки конкретных плагинов лучше смотреть в плагинах

{
    "contextDefaultDuration": 10, # Время в секундах, пока Ирина находится в контексте (контекст используется в непрерывном чате, играх и пр.; в контексте не надо использовать слово Ирина)
    "contextRemoteWaitForCall": false, # должна ли Ирина ждать от клиентов сингнала "Проигрывание ответа закончена, запускаем время для контекста?"
    "contextExitCommand": "", # команда для досрочного выхода из контекста (если пусто, то контекст завершается только по таймауту) 
    # официальные клиенты поддерживают contextRemoteWaitForCall, рекомендуется true
    "fuzzyThreshold": 0.5, # (ПРО) Порог уверенности при использовании плагинов нечеткого распознавания команд
    "isOnline": true, # при установке в false будет выдавать заглушку на команды плагинов, требующих онлайн. Рекомендуется, если нужен только оффлайн.
    "linguaFrancaLang": "ru", # язык для конвертации чисел в lingua-franca. Смените, если будете работать с другим языком
    "logPolicy": "cmd", # all|cmd|none . Когда распознается речь с микрофона - выводить в консоль всегда | только, если является командой | никогда
    "mpcHcPath": "C:\\Program Files (x86)\\K-Lite Codec Pack\\MPC-HC64\\mpc-hc64_nvo.exe", # путь до MPC HC, если используете
    "mpcIsUse": true, # используется ли MPC HC?
    "mpcIsUseHttpRemote": true, # MPC HC - включено ли управление через веб-интерфейс?
    "playWavEngineId": "audioplayer", # плагин проигрыша WAV-файлов. Некоторые WAV требуют sounddevice.
    "replyNoCommandFound": "Извини, я не поняла", # ответ при непонимании
    "replyNoCommandFoundInContext": "Не поняла...", # ответ при непонимании в состоянии контекста
    "replyOnlineRequired": "Нужен онлайн", # ответ при вызове в оффлайн функции плагина, требующего онлайн 
    "tempDir": "temp", # папка для временных файлов
    "ttsEngineId": "pyttsx", # используемый TTS-движок
    "ttsEngineId2": "", # 2 используемый TTS-движок. Работает только на локальную озвучку - например, буфера обмена. Вызывается командой say2
    "useTTSCache": false, # при установке true в папке tts_cache будет кэшировать .wav файлы со сгенерированными TTS-движком ответами
    "v": "1.7", # версия плагина core. Обновляется автоматически, не трогайте
    "voiceAssNames": "ирина|ирины|ирину", # Если это появится в звуковом потоке, то дальше будет команда. (Различные имена помощника, рекомендуется несколько)
    "voiceAssNameRunCmd": { # если вы обратитесь к помощнику по этому имени, то в начало вашей команды будет подставлено соответствующее слово
        "альбина": "чатгпт"
    },
    "log_console": True,  # Вывод логов в консоль
    "log_console_level": "WARNING",
    # Записываются в лог сообщения с уровнем равным или выше этого уровня: NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL
    "log_file": False,  # Вывод в лог-файл
    "log_file_level": "DEBUG",  # NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL
    "log_file_name": "log.txt",  # имя лог-файла

    "normalization_engine": "numbers", # нормализация текста для русских TTS. 
    # Нормализация позволяет транслировать 1, 2, 3 в "один, два, три", что нужно, например, для VOSK TTS, который не знает числа
    # Добавляется плагинами. Рекомендуется runorm для качества (но runorm тяжела в обработке)
    # СОГЛАШЕНИЕ: каждый плагин TTS сам принимает решение, нужна ли ему предобработка.
    # Если нужна, он может вызвать core.normalize(text_to_speech), см. пример в plugin_tts_vosk.py
  
}

Отладка и разработка (для разработчиков)

Для отладки можно использовать запуск системы через файл runva_cmdline.py.

Она делает запуск ядра (VACore in vacore.py) через интерфейс командной строки, это удобнее, чем голосом диктовать.

• Подключить собственный навык можно, создав плагин в plugins_. Смотрите примеры.
• Подключить собственный TTS можно плагином. Как примеры, смотрите plugins_tts_console.py, plugins_tts_pyttsx.py.
• Также, создав собственный runva_ файл, можно, при желании, подключить свойт Speech-To-Text движок.

Логирование

Логирование реализовано с помощью библиотеки logging в модуле core.py.

Параметры задаются в options/core.json:

• если log_console=True, то выводится в консоль
• если log_file=True, то выводится в лог-файл

Значения по умолчанию:

• log_console=True
• log_file=False
• log_console_level="WARNING"
• log_file_level="DEBUG"
• log_file_name="log.txt"

Уровни логирования:

• NOTSET = 0
• DEBUG = 10
• INFO = 20
• WARNING = 30
• ERROR = 40
• CRITICAL = 50

По умолчанию, логи выводятся в консоль с уровнем WARNING, а в лог-файл с уровнем DEBUG. Это означает, что в лог попадают все сообщения с установленным уровнем и выше (больше). Т.е. если указан уровень WARNING, то в лог попадут сообщения с уровнем WARNING, ERROR, CRITICAL. Если уровень установлен на DEBUG, то в лог попадут сообщения с уровнем DEBUG, INFO, WARNING, ERROR, CRITICAL.

Рекомендуемое использование: В начале модуля, после всех импортов добавить следующие строки:

import logging

logger = logging.getLogger(__name__)

Добавление событий в лог осуществляется вызовом соответствующей функции:

logger.debug("debug message")  # для детальных сообщений при отладке
logger.info("info message")  # для информационных сообщений, когда всё выполняется как и задумывалось
logger.warning("warning message")  # для предупреждений, когда что-то пошло не так, но работа продолжается
logger.error("error message")  # для сообщений об ошибках и потере функционала
logger.critical("critical message")  # для сообщений о критических ошибках, при невозможности дальнейшей работы

При выводе логов в блоках try/except можно использовать следующую конструкцию:

try:
  ...
except Exception as e:
  logger.exception(e)

или так:

try:
  import some_library
except ImportError as e:
  logger.exception(e)
  logger.error("Library 'some_library' is not installed. Please install it with 'pip install some_library'")

Рекомендуется последний вариант, для обработки конкретных исключений, а не всего класса Exception. Использование logger.exception(e) обеспечивает вывод информации о трассировке стека (stack trace).

Разработка плагинов

Документация по разработке

Удаленная работа (сервер-клиент, мультимикрофонные/машинные инсталляции)

Мультиинсталляция в режиме "клиент-сервер" несколько сложнее, но позволяет управлять Ириной:

• с нескольких микрофонов
• с разных машин
• из Телеграма (с помощью телеграм-бота)

Подробнее про настройку клиент-серверного режима

Документация WEB API

Speech-to-Text через VOSK remote

Если у вас проблемы с установкой VOSK (например, на Mac), то вы можете воспользоваться работой через VOSK Auto Speech Recognition Server, который запускается через Докер.

• Запустите docker run -d -p 2700:2700 alphacep/kaldi-ru:latest (детали: https://alphacephei.com/vosk/server )
  • или как вариант, вы можете запустить vosk_asr_server.py, переопределив внутри параметры

    args.interface = os.environ.get('VOSK_SERVER_INTERFACE', "0.0.0.0")
    args.port = int(os.environ.get('VOSK_SERVER_PORT', 2700)

• Запустите runva_voskrem.py. Он будет читать данные с микрофона и отправлять на сервер для распознавания.

В случае, если надо запустить распознавание на другой машине - используйте параметр -u (--uri): runva_voskrem.py -u=ws://100.100.100.100:2700 для уточения адреса сервера.

Speech-to-Text через GigaSTT (GigaAM v3)

GigaSTT — локальный сервер распознавания русской речи на модели GigaAM v3. Работает полностью на устройстве (CPU), без облака.

• Установите сервер по инструкции из репозитория и запустите его: gigastt serve (модель скачается автоматически при первом запуске).
• Запустите runva_gigastt.py. Он будет читать данные с микрофона и отправлять на сервер для распознавания. Важно: рекомендуется запускать с параметрами gigastt serve --endpoint-mode assistant --vad --vad-min-silence-ms 1200, чтобы gigastt не резал конец фразы слишком быстро, а ждал паузы после окончания команды. Подробнее см. https://github.com/janvarev/Irene-Voice-Assistant/pull/75 , https://github.com/janvarev/Irene-Voice-Assistant/pull/76

В случае, если сервер запущен на другой машине - используйте параметр -u (--uri): runva_gigastt.py -u=ws://100.100.100.100:9876 для уточения адреса сервера.

Дополнительные параметры: -d — выбор микрофона, -r — частота дискретизации, -l — список аудиоустройств, --debug — вывод промежуточных результатов распознавания.

Обращаем внимание, что разработчики Ирины не имеют отношения к данному распознавателю GigaSTT; используйте на свой страх и риск.

Speech-to-Text через SpeechRecognition

SpeechRecognition - классический движок для запуска распознавания через Google и ряд других сервисов. Для запуска этого распознавания запустите систему через файл runva_speechrecognition.py.

Для работы потребуется:

pip install PyAudio

pip install SpeechRecognition

Если есть проблемы с установкой PyAudio, прочтите детали у EnjiRouz

Особенности: распознавание числительных. Одна и та же фраза распознается так:

• VOSK: таймер десять секунд
• SpeechRecognition (Google): таймер 10 секунд

Поддержка многоязычности

Проект в целом не предполагает поддержки многоязычности, т.к. использует кастомный парсинг слов в плагинах. Но, тем не менее, ядро (vacore.py) совершенно не привязано к языку, и вы можете собрать собственную инсталляцию на другом языке, просто переписав для них плагины.

Несколько языковых фраз, определяющих core-поведение языкового помощника (его имя, а также фразы типа "Я не поняла") настраиваются в файле конфигурации плагина core.

Нечеткая обработка фраз

C версии 7.5 поддерживает нечеткую обработку пользовательского ввода.

Для задания порога распознавания есть глобальный параметр fuzzyThreshold в core.json, он принимает значения от 0 до 1 (1 - полная уверенность в фразе)

Известные плагины, работающих с этим:

• https://github.com/janvarev/irene_plugin_fuzzy_thefuzz - через thefuzz, нечеткое сравнение строк
• https://github.com/modos189/irene_plugin_fuzzy_sklearn - через scikit-learn
• https://github.com/janvarev/irene_plugin_fuzzy_ai_sentence - семантическое сравнение строк на нейросетях (sentence_transformers)

Плагины от голосового помощника Васисуалия

С версии 8.1 в тестовом режиме сделана поддержка core-плагинов от голосового помощника Васи: https://github.com/Oknolaz/vasisualy

Для добавления:

1. Плагины надо кидать в plugins_vasi/skills (брать в https://github.com/Oknolaz/vasisualy/tree/master/vasisualy/skills )
2. от каждого плагина ожидается, что в модуле будет прописан triggers, на основании которого формируется список команд. Если нет - плагин надо доработать.

Работает в простейших случаях - протестировано на плагинах coin и crystall_ball.

Если не работает - читайте код. Поддержка сделана через плагин plugin_vasi.py.

Contributing

Если вы хотите что-то добавить в проект, хорошо ознакомиться с Политикой CONTRIBUTING.md

Коротко:

• Под плагины желательно делать отдельные Github-проекты (или размещать их где-то еще), которые вы готовы поддерживать. Ссылки можно кидать в https://github.com/janvarev/Irene-Voice-Assistant/issues/1, чтобы ваш плагин нашли другие. Кидать дополнительные плагины в этот проект не нужно - у меня нет времени и сил поддерживать то, в чём я не разбираюсь.
• Делайте точечные изменения, улучшающие функциональность или фиксящие баги (например, нерабочесть в каких-то условиях). Такие Pull Request с высокой вероятностью будут приняты.
• Массовые изменения кода (приведения стиля кода к единому, организация импортов) не будут рассматриваться и будут отклонены. Пожалуйста, не делайте их.

Благодарности

@EnjiRouz за проект голосового ассистента: https://github.com/EnjiRouz/Voice-Assistant-App, который стал основой (правда, был очень сильно переработан)

AlphaCephei за прекрасную библиотеку распознавания Vosk ( https://alphacephei.com/vosk/index.ru )

Поддержка проекта

Основная сложность в опенсорс - это не писать код. Писать код интересно.

Сложность в опенсорс - поддерживать код и пользователей в течение долгого времени.

Отвечать на вопросы. Фиксить баги. Писать статьи и документацию.

Если вы хотите поддержать мой интерес и сделать так, чтобы Ирина, как независимый от больших компаний голосовой помощник долго, поддерживалась, вы можете:

• Написать новый плагин (меня всегда это радует!)
• Закинуть денежку через подписку в https://boosty.to/irene-voice Чем больше у меня подписчиков, тем лучше я понимаю, что проект нужен.
• Рассказать кому-то об Ирине, или помочь её настроить.
• Просто сказать "спасибо" в этой ветке: https://github.com/janvarev/Irene-Voice-Assistant/issues/12