Голосовой агент «Гемма» (Rus)

Голосовой офлайн‑агент на Windows с распознаванием речи (Vosk), TTS (pyttsx3) и локальной LLM (llama‑cpp‑python, модель Gemма 3 1B). Управляет приложениями, громкостью, напоминаниями, делает веб‑поиск и отвечает на вопросы.

Возможности

• Активация по слову: настраивается в config.json (activation_word, по умолчанию «Гемма»).
• Запуск/закрытие приложений: строго по преднастроенным командам из config.json (commands).
• Подброс монетки: "подбрось монетку", "орёл или решка".
• Громкость: «громкость 1..10» (10–100%) или «громкость 70%».
• Питание: «перезагрузи/выключи компьютер», «спящий режим».
• Время: «сколько времени», «который час».
• Таймеры/напоминания: «таймер N минут», «напомни через 10 минут …», «напоминание на 14:30 …», удаление по времени.
• Веб‑поиск: «найди …» (DuckDuckGo Lite + краткий ответ на основе извлечённого контента).
• LLM‑ответы: краткие ответы при отсутствии явной команды.

Требования

• Windows 10/11 x64.
• Python 3.10+ (рекомендуется x64).
• Микрофон и устройство вывода звука.

Установка

1. Клонируйте/распакуйте проект и перейдите в каталог.
2. Установите зависимости:

   pip install -r requirements.txt

3. Скачайте и поместите модели (см. ниже) рядом с agent.py или укажите пути в config.json.

Модели

• Gemma 3 1B Instruct (GGUF) — требуется GGUF‑файл (например, gemma-3-1B-it-QAT-Q4_0.gguf).

  • Найти и скачать: Hugging Face (поиск «gemma 3 1b gguf»): https://huggingface.co/google/gemma-3-1b-it
  • Укажите путь в config.json → model.path.

• Vosk Russian — vosk-model-small-ru-0.22.

  • Страница моделей (Alpha Cephei / Vosk): https://alphacephei.com/vosk/models
  • Прямая ссылка на модель RU small 0.22 (zip): https://alphacephei.com/vosk/models/vosk-model-small-ru-0.22.zip
  • Распакуйте папку vosk-model-small-ru-0.22 в корень проекта (рядом с agent.py).

Важно: установка llama‑cpp‑python

Библиотека llama-cpp-python может собираться из исходников и требует C++‑инструменты.

• Репозиторий и инструкции: https://github.com/abetlen/llama-cpp-python

• Для Windows обычно нужны:

  • Microsoft Visual C++ Build Tools (MSVC) — установите «Desktop development with C++»: https://visualstudio.microsoft.com/visual-cpp-build-tools/
  • CMake (если требуется): https://cmake.org/download/

После установки инструментов перезапустите терминал и выполните:

pip install --upgrade pip setuptools wheel
pip install llama-cpp-python==0.2.76

При наличии готовых колёс (wheels) под вашу версию Python сборка может не требоваться. Для CPU‑режима дополнительных CUDA‑пакетов не нужно.

Конфигурация (config.json)

Ключевые поля:

• model
  • path — путь к GGUF модели Gemma 3 1B Instruct.
  • ctx_size — размер контекста LLM.
  • Параметры генерации: temperature, top_p, top_k, repeat_penalty, max_tokens, seed.
• activation_word — слово активации (например, «Гемма»).
• silence_timeout — таймаут тишины (сек) при ожидании продолжения команды.
• tts — voice_index, rate, volume для pyttsx3.
• commands — словарь команд приложений:

  "браузер": {
    "open": "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
    "close": "msedge"
  }

  • open: путь к исполняемому файлу + аргументы (поддерживается подстановка ${USER}).
  • close: имя процесса для завершения (лучше точное имя exe).
• web_search — лимиты по поиску: max_sources, таймауты и ограничения на размер извлечённого текста.

Примечание: агент ИЗНАЧАЛЬНО не поддерживает «универсальное открытие любого приложения». Работает только со списком, определённым в commands.

Запуск

python agent.py

• После запуска скажите слово активации (по умолчанию «Гемма»).
• Можно говорить сразу с командой: «Гемма, открой браузер». Если сказано только «Гемма», агент спросит, что сделать.

Примеры фраз

• Приложения: «Гемма, открой браузер», «Гемма, закрой телеграм».
• Подброс монетки: «Гемма, подбрось монетку», «Гемма, орёл или решка».
• Громкость: «Гемма, громкость 7», «Гемма, громкость 30 процентов».
• Питание: «Гемма, перезагрузи компьютер», «Гемма, спящий режим».
• Время: «Гемма, который час?»
• Таймер: «Гемма, таймер 5 минут».
• Напоминание (через): «Гемма, напомни через 10 минут проверить чайник».
• Напоминание (на время): «Гемма, напоминание на 14:30 созвон».
• Удаление напоминаний: «Гемма, удали напоминание на 14:30».
• Поиск: «Гемма, найди погоду в Москве на выходные».

Советы и ограничения

• Для close используйте точное имя исполняемого файла из Диспетчера задач (уменьшает риск завершить лишний процесс).
• Если TTS звучит слишком быстро/медленно — подберите tts.rate и tts.voice_index.
• Если распознавание запаздывает — уменьшите blocksize в коде (по умолчанию 8000) и/или используйте другое устройство ввода.
• Для стабильной работы LLM убедитесь в корректности пути к GGUF и достаточной памяти.

Структура проекта

• agent.py — основной цикл: STT (Vosk) → активация → маршрутизация команд → TTS.
• lang_ru.py — словари числительных и единиц времени.
• config.json — настройки модели/tts/команд/поиска.
• requirements.txt — список зависимостей Python.
• vosk-model-small-ru-0.22/ — папка модели Vosk (после распаковки).
• *.gguf — файл LLM‑модели Gemma 3 1B Instruct.