Установка на macOS / Apple Silicon

September 20, 2026 · View on GitHub

Инструкция рассчитана на macOS, Python 3.12 и Apple Silicon. Все распознавание и NLI выполняются локально; сеть нужна только для скачивания весов и, при желании, для удалённого агента.

1. Проверить микрофон

Подключите микрофон и разрешите Terminal доступ:

System Settings → Privacy & Security → Microphone → Terminal.

Проверьте доступные устройства:

python -c "import sounddevice as sd; print(sd.query_devices())"

Запомните индекс или устойчивенную часть имени входного устройства. Не полагайтесь на индекс как на постоянный: он может поменяться после переподключения USB.

2. Создать окружение

python3.12 -m venv .venv

source .venv/bin/activate

python -m pip install --upgrade pip

python -m pip install -r requirements.txt

webrtcvad работает с 16-bit mono PCM. Для примера используйте 16 кГц, 30-мс фреймы: это 480 сэмплов на фрейм.

3. Скачать модели локально

Установите CLI Hugging Face:

python -m pip install "huggingface_hub[cli]"

Скачайте OpenJev, Whisper и, если нужен фильтр аудиосцены, AST отдельно. Веса исключены из Git и могут занимать много места.

HF_HUB_DISABLE_XET=1 hf download AlexWortega/openjev --local-dir models/openjev

HF_HUB_DISABLE_XET=1 hf download mlx-community/whisper-large-v3-turbo --local-dir models/whisper-large-v3-turbo

HF_HUB_DISABLE_XET=1 hf download MIT/ast-finetuned-audioset-10-10-0.4593 --local-dir models/ast-audioset

При ошибке Xet оставьте HF_HUB_DISABLE_XET=1: это переключает загрузку на обычный HTTP-путь.

4. Проверить OpenJev отдельно

python src/jev_gate.py --model-dir models/openjev --text 'Подскажи, какая сегодня погода?'

Проверка должна напечатать JSON с оценками yes_score и no_score. Первый запуск грузит около 9 ГБ весов и занимает заметно больше времени. В production держите модель загруженной внутри длительно работающего процесса; не запускайте Python для каждого фрагмента речи.

5. Добавить VAD и ASR

Минимальный цикл:

  1. Читайте sounddevice.RawInputStream как mono int16, 16 kHz.
  2. Передавайте каждый 30-мс фрейм в webrtcvad.Vad(2).
  3. Начинайте фразу после 4 подряд voiced-фреймов.
  4. Завершайте её после примерно 1 секунды тишины.
  5. До Whisper проверяйте минимум 20 voiced-фреймов и RMS сигнала.
  6. Передавайте float32 сэмплы в mlx_whisper.transcribe.
  7. Отбрасывайте сегменты со слабыми метриками Whisper; см. gating.md.

Не держите аудиофайлы по умолчанию. В отладке сохраняйте только транскрипт, числовые метрики и решение; включайте запись аудио лишь с явного согласия всех говорящих.

6. Автозапуск

На macOS фоновый пользовательский процесс обычно оформляют как LaunchAgent. Сначала отладьте listener в foreground: убедитесь, что он получает фреймы и корректно переживает отключение микрофона. Затем создайте plist с RunAtLoad, KeepAlive, отдельными stdout/stderr журналами и абсолютными путями к venv и скрипту.

Не заявляйте, что сервис «слушает», только по PID. Подтверждайте это реальным получением фрейма от RawInputStream и явным статусом listening.