Дополнительные сервисы (sidecars) — AiHummer Документация

Часть возможностей — речь, видео, веб-поиск, headless-браузер — не входит в сам шлюз. Они работают как дополнительные сервисы (sidecar) — сервисы, запускаемые рядом с ядром или на отдельном узле, к которым шлюз обращается по URL. Отдельный платный API-ключ для них не обязателен, но не все они локальные: например, edge-tts использует внешний онлайн-сервис Microsoft.

Что такое дополнительный сервис

Дополнительный сервис — это отдельный процесс с HTTP-API. Шлюз никогда не линкует его в себя и не запускает в своём процессе — он просто вызывает настроенный вами URL. Каждый сервис

работает под своим systemd-юнитом (напрямую в Linux, без контейнеров),
подключается к шлюзу через переменную окружения и
может быть установлен нативно рядом со шлюзом либо нацелен на уже существующий инстанс, который вы держите в другом месте.

Поскольку контракт — это просто HTTP, одна и та же конфигурация работает и когда сервис на localhost, и когда он на другом хосте.

[!NOTE] Дополнительные сервисы опциональны, но веб-поиск (SearXNG) и антидетект-браузер (CloakBrowser) ставятся из коробки: их дистрибутивы вшиты в подписанный установочный комплект и разворачиваются офлайн. Отключить их можно флагами установщика --no-search и --no-browser. Остальные возможности активны только тогда, когда настроен их URL; минимальная установка — это лишь шлюз плюс PostgreSQL.

Сервисы и их порты

Порт	Сервис	На основе	Обеспечивает	Подключение
8001	STT	faster-whisper	распознавание речи	`AIHUMMER_STT_URL`
8002	TTS	edge-tts	синтез речи	`AIHUMMER_TTS_URL`
8005	video	ffmpeg	понимание видео	`AIHUMMER_VIDEO_URL`
8888	SearXNG	SearXNG	инструмент `web_search`	ставится установщиком, настройка скрыта; внешний инстанс — `--external-search=URL`
9222	Chrome / CDP	Chrome (CDP)	инструмент `browser`	ставится установщиком, настройка скрыта; внешний инстанс — `--external-browser=URL`

Голосовые сервисы — это путь «из коробки»: STT (:8001) передаёт речь в обработку запроса, а TTS (:8002) озвучивает ответ. faster-whisper работает локально; edge-tts использует внешний онлайн-сервис Microsoft, поэтому текст для синтеза покидает ваш контур — для полностью изолированного режима подключите локальный TTS-движок. Понимание видео (:8005) — дополнительный, опциональный сервис. SearXNG (:8888) обеспечивает web_search, а endpoint Chrome/CDP (:9222) — инструмент browser.

Подключение сервисов

Укажите для шлюза URL каждого дополнительного сервиса соответствующей настройкой каталога — из веб-интерфейса (Управление → Настройки) или командой aihummer settings set. gateway.env — только для начальной загрузки и для этих ключей игнорируется. При стандартной установке голосовые сервисы (STT/TTS) настраиваются за вас; веб-поиск и браузер подключает сам установщик — их адреса оператор не задаёт и в настройках они не показываются; остальные сервисы включаете по мере необходимости.

# Голос вход/выход (STT/TTS настраиваются установщиком)
aihummer settings set AIHUMMER_STT_URL http://127.0.0.1:8001
aihummer settings set AIHUMMER_TTS_URL http://127.0.0.1:8002

# Опциональный сервис видео
aihummer settings set AIHUMMER_VIDEO_URL http://127.0.0.1:8005

[!TIP] Раз каждый дополнительный сервис — это просто URL, тяжёлые сервисы можно централизовать. Нацельте несколько шлюзов на один общий инстанс STT/TTS вместо копии на каждом хосте; для поиска и браузера то же самое делают флаги установщика --external-search=URL / --external-browser=URL.

Нативно или совместно

Каждый дополнительный сервис живёт под своим systemd-юнитом на хосте, поэтому вы управляете им как любым другим сервисом — запускаете, останавливаете и читаете журналы независимо от шлюза. Если у вас уже работает, скажем, SearXNG или endpoint Chrome/CDP, передайте установщику флаг --external-search=URL или --external-browser=URL — локальная копия не ставится, а шлюз обращается к вашему инстансу. Для голосовых сервисов и видео достаточно указать URL существующего инстанса в настройке. Способ размещения не меняет контракт: шлюз обращается к настроенному адресу.

[!WARNING] Инструменты browser (CDP) и web_search обращаются в сеть. На усиленных или изолированных (air-gapped) развёртываниях проверьте исходящие подключения и изолированный режим перед их включением — шлюз вызывает только тот сервис, который вы подключили.

Куда дальше

Как голос и инструмент браузера используются при обработке запроса: Шлюз и движок обработки запросов.
Минимальная жёсткая зависимость (PostgreSQL) и всё остальное опционально: Шлюз и движок обработки запросов.