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

Эта интеграция позволяет персонажам ИИ управлять настоящими устройствами умного дома прямо из чата, например светом, климатом, шторами и медиаплеерами. Кроме того, автоматизации Home Assistant смогут отправлять сообщения в приложение Marinara Engine. Home Assistant – это бесплатная платформа с открытым исходным кодом для устройств умного дома. Если вы ею не пользуетесь, это руководство вам не нужно.

Что добавляет интеграция

Интеграция – это небольшая программа, которая устанавливается внутрь Home Assistant и связывает его с вашим сервером Marinara. При первой настройке она сама создает все перечисленное ниже. Копировать адреса инструментов или настраивать инструменты вручную не нужно.

Инструменты умного дома в разделе Functions (функции) панели Presets. См. Собственные инструменты и вызов функций.
Одного агента с названием Home Assistant – помощника ИИ, который работает рядом с вашим чатом. См. Агенты: помощники ИИ в чатах.
Сущности Home Assistant (устройства, датчики и элементы управления), чтобы следить за приложением Marinara и управлять им из Home Assistant.

Что нужно заранее

Home Assistant версии 2024.1.0 или новее.
Установленный в Home Assistant HACS. HACS – это Home Assistant Community Store, инструмент для установки сторонних интеграций.
Запущенное приложение Marinara, доступное с машины, где работает Home Assistant. Адрес по умолчанию – localhost:7860.
Строка WEBHOOK_LOCAL_URLS_ENABLED=true в файле .env сервера Marinara.

Файл .env – это обычный текстовый файл настроек сервера Marinara. Где он лежит, описано в руководстве Настройки сервера: справочник. Интеграция использует вебхук – веб-адрес, через который одно приложение отправляет данные другому. Вебхук Home Assistant – это локальный адрес с обычным http, а такие адреса Marinara из соображений безопасности по умолчанию блокирует. Эта настройка их разрешает. Добавьте эту строку и сохраните файл. Она начинает действовать без перезапуска, обычно в течение нескольких секунд (максимум примерно через 30 секунд):

WEBHOOK_LOCAL_URLS_ENABLED=true

Если Home Assistant работает на другом устройстве

Интеграция подключается без имени пользователя и пароля, и в форме настройки их негде указать.

Та же машина: подключение работает сразу.
Другое устройство: Marinara по умолчанию его блокирует. Добавьте IP-адрес этого устройства (его числовой адрес в вашей сети) в IP_ALLOWLIST в файле .env. В полностью доверенной домашней сети вместо этого можно задать ALLOW_UNAUTHENTICATED_PRIVATE_NETWORK=true.
Если в Marinara заданы BASIC_AUTH_USER и BASIC_AUTH_PASS (вход), интеграция не сможет войти. Тогда она работает только с той же машины или с устройства из IP_ALLOWLIST.

Какой вариант выбрать, описано в руководстве Удаленный доступ: вход и список разрешенных адресов.

Установка интеграции

Добавление в HACS

В Home Assistant откройте HACS.
Откройте меню из трех точек и нажмите Custom repositories (сторонние репозитории).
В поле репозитория введите https://github.com/Pasta-Devs/Marinara-Engine.
Задайте категорию Integration (интеграция) и нажмите Add (добавить).
Найдите Marinara Engine и установите.
Перезапустите Home Assistant.

Настройка

Откройте Settings → Devices & Services (настройки → устройства и службы) и нажмите Add Integration (добавить интеграцию).
Найдите Marinara Engine.
Укажите в полях Host (адрес) и Port (порт), где работает Marinara. По умолчанию это localhost и 7860.
Нажмите Submit (отправить).

Если не получилось: когда Home Assistant не может связаться с Marinara, он показывает ошибку. См. Устранение неполадок.

После успешной настройки интеграция регистрирует в Home Assistant частный вебхук, создает в разделе Functions приложения Marinara инструменты, нацеленные на этот вебхук, создает агента Home Assistant со списком всех включенных инструментов и создает сущности, описанные ниже.

Добавление агента в чат

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

Откройте чат и нажмите Chat Settings (настройки чата).
Откройте раздел Agents (агенты).
Добавьте агента Home Assistant.

Он работает в чатах Roleplay, Conversation и Game. После добавления инструменты доступны ИИ в этом чате. Больше ничего включать не нужно.

Проверка работы

В этом чате напишите обычную просьбу, например Turn on the office lights, и отправьте ее.
ИИ должен вызвать инструмент, например ha_turn_on, свет должен включиться, а ИИ подтвердит это.

Если ничего не произошло, проверьте, что задано WEBHOOK_LOCAL_URLS_ENABLED=true, и см. Устранение неполадок.

Выбор инструментов, доступных ИИ

Инструменты разделены на восемь категорий. Чтобы выбрать, какие из них может использовать Marinara, откройте Settings → Devices & Services, нажмите Marinara Engine, затем Configure (настроить). Здесь два параметра:

Primary Chat (основной чат): чат по умолчанию, на который направлены службы Home Assistant.
Exposed Tool Categories (открытые категории инструментов): категории, которые может использовать Marinara.

Категория	По умолчанию	Инструменты
Lights & Switches	Включено	ha_turn_on, ha_turn_off, ha_toggle, ha_set_brightness, ha_set_color, ha_set_color_temp
Climate	Включено	ha_set_temperature, ha_set_hvac_mode
Covers (Blinds & Garage)	Включено	ha_open_cover, ha_close_cover, ha_set_cover_position
Locks	Выключено	ha_lock, ha_unlock
Media Players	Включено	ha_media_play, ha_media_pause, ha_set_volume
Scenes & Scripts	Включено	ha_activate_scene, ha_run_script
Query	Включено	ha_get_state, ha_list_areas, ha_list_entities, ha_notify
Generic Service Calls (Advanced)	Выключено	ha_call_service

Предупреждение: Generic Service Calls (Advanced) позволяет ИИ вызвать любую службу Home Assistant. Locks позволяет ему запирать и отпирать двери. Обе категории по умолчанию выключены. Включайте их, только если они вам действительно нужны.

Большинство инструментов принимает одно устройство или название комнаты. Если указано название комнаты, инструмент срабатывает для всех подходящих устройств в этой комнате. Изменения категорий вступают в силу после нажатия Marinara Sync HA Tools (синхронизировать инструменты HA) или перезапуска Home Assistant.

Сущности в Home Assistant

Интеграция создает эти сущности в устройстве с названием Marinara Engine.

Сущность	Тип	Что делает
Marinara Chat Count	Sensor	Общее число чатов Marinara
Marinara Active Agent Count	Sensor	Сколько агентов Marinara включено
Marinara Active Chat	Select	Выбирает чат, на который направлены службы
Marinara Agent: (name)	Switch	Включает или выключает одного агента, по одному переключателю на агента
Marinara Abort Generation	Button	Отменяет любой ответ ИИ, который сейчас генерируется
Marinara Sync HA Tools	Button	Заново отправляет все инструменты и пересобирает агента Home Assistant

Интеграция проверяет Marinara на новые чаты и агентов каждые 30 секунд, поэтому то, что вы только что создали, может появиться с задержкой до 30 секунд.

Синхронизация после изменения настроек

Нажмите Marinara Sync HA Tools на странице устройства Marinara Engine. Кнопка обновляет существующие инструменты на месте, пересобирает агента Home Assistant, если вы его удалили, и выключает (но не удаляет) инструменты из категорий, которые вы отключили. Не правьте инструменты Home Assistant в Marinara вручную. Следующая синхронизация перезапишет ваши правки и снова включит инструменты.

Управление Marinara из автоматизаций

Интеграция добавляет две службы Home Assistant для автоматизаций. Они работают внутри Home Assistant, а не в Marinara. По умолчанию обе направлены на ваш Primary Chat.

Служба Send Message (marinara_engine.send_message)

message: текст сообщения. Обязательное поле.
chat_id: в какой чат отправить. Если оставить поле пустым, используется Primary Chat.
role: user, assistant, system или narrator. По умолчанию – user.
trigger_generation: если true, ИИ еще и отвечает. По умолчанию – false.

Эта автоматизация сообщает ИИ, когда открывается входная дверь:

automation:
  trigger:
    platform: state
    entity_id: binary_sensor.front_door
    to: "on"
  action:
    service: marinara_engine.send_message
    data:
      message: "Someone has arrived at the front door."
      trigger_generation: true

Служба Trigger Generation (marinara_engine.trigger_generation)

Она запускает ответ ИИ без видимого сообщения.

chat_id: какой чат. Если оставить поле пустым, используется Primary Chat.
user_message: необязательное сообщение, которое добавляется к ходу с ответом.

Устранение неполадок

Форма настройки сообщает, что не может подключиться

Убедитесь, что Marinara запущена и что Host и Port совпадают с адресом, на котором она слушает (по умолчанию localhost и 7860). Если Home Assistant работает на другом устройстве, Marinara блокирует его, пока это устройство не добавлено в IP_ALLOWLIST. Интеграция не умеет передавать пароль, поэтому Marinara, защищенная входом, тоже ее отклоняет. См. Удаленный доступ: вход и список разрешенных адресов. Эти правила действуют и после настройки. Если Marinara позже заблокирует устройство, датчики и список чатов молча перестанут обновляться.

ИИ пытается вызвать инструмент устройства, но ничего не происходит

Скорее всего, обращение к вебхуку заблокировано. Добавьте WEBHOOK_LOCAL_URLS_ENABLED=true в .env и сохраните файл. Без этой настройки вызовы инструментов могут завершаться ошибкой о том, что http не разрешен, или об отказе для частного адреса. Если Marinara и Home Assistant работают на одной машине, интеграция автоматически использует внутренний адрес. Если Marinara работает на другом устройстве, проверьте, что локальный адрес Home Assistant с него доступен.

Инструменты не появляются в Functions

Нажмите Marinara Sync HA Tools или перезапустите Home Assistant, затем проверьте Functions в панели Presets.

Агента Home Assistant нет в моем чате

Проверьте, что агент есть в Marinara в разделе Agents. Если его нет, нажмите Marinara Sync HA Tools, чтобы пересобрать его. Затем добавьте его в Chat Settings → Agents.

Как найти адрес вебхука вручную

Это редко нужно, потому что адрес уже есть в каждом инструменте. Откройте в Home Assistant Settings → Devices & Services → Marinara Engine. Вебхук строится по такому шаблону, где 8123 – порт Home Assistant по умолчанию:

http://<homeassistant-ip>:8123/api/webhook/<webhook-id>

Удаление интеграции

Удалите интеграцию в Home Assistant в Settings → Devices & Services → Marinara Engine. Это убирает сущности. Инструменты в разделе Functions приложения Marinara и агент Home Assistant остаются. Если они больше не нужны, удалите их вручную в Marinara.

Смежные руководства

Собственные инструменты и вызов функций
Агенты: помощники ИИ в чатах
Настройки сервера: справочник
Удаленный доступ: вход и список разрешенных адресов