See description in English below 👇

VK Cloud Vision для Home Assistant

Интеграция добавляет поддержку облачного распознавания объектов и текста через VK Cloud Vision.
Используйте возможности компьютерного зрения для создания автоматизаций на основе анализа изображений с камер видеонаблюдения.

Возможности

• Распознавание объектов (людей, животных) и автомобильных номеров.
• Распознавание лиц: определение уже знакомых людей и автоматическое добавление новых лиц в базу.
• Распознавание текста: например, надписей на автомобилях и других объектах.
• Сохранение стоп-кадров с разметкой обнаруженных объектов.
• Blueprints для реализации распространённых сценариев.

VK Cloud Vision — это облачный сервис, плата за который взимается в соответствии с тарифами. При первой регистрации можно получить приветственные бонусы.

Установка и настройка

Подготовка

1. Зарегистрируйтесь в VK Cloud.
2. Получите Идентификатор клиента и Секретный ключ в разделе «Доступ через идентификатор клиента и секретный ключ».
3. Сохраните полученные данные.

Установка

1. Скачайте интеграцию через HACS.
2. Перезапустите Home Assistant.
3. Перейдите в Настройки → Устройства и службы → Добавить интеграцию или используйте кнопку настройки.
4. Введите Идентификатор клиента и Секретный ключ, полученные в личном кабинете VK Cloud.

Использование на практике

Интеграция с motionEye

Интеграция с VK Cloud Vision занимается только распознаванием объектов, и ей нужен внешний триггер, который запустит распознавание. Про использование motionEye в качестве такого триггера можно почитать тут.

Охранная сигнализация с облачным распознаванием объектов

Активирует сигнализацию при обнаружении людей или транспортных средств, игнорируя ложные срабатывания (например, движение веток или животных).

Основные функции:

• Активация только в выбранных режимах охраны;
• Проверка на наличие важных объектов («Человек», «Автомобиль», «Грузовик», «Автобус»);
• Сохранение стоп-кадров с разметкой объектов;
• Логирование результатов обнаружения.

Система контроля доступа для транспорта

Автоматическое открытие ворот и выполнение других действий для «своих» машин и спецтранспорта.

Основные функции:

• Распознавание номеров «своих» автомобилей;
• Идентификация спецтранспорта (скорая, спасатели, пожарные);
• Обнаружение служебного транспорта (курьеры, доставка);
• Гибкая настройка действий для разных категорий.

Распознавание лиц: идентификация и пользовательские действия

Распознаёт лица знакомых и незнакомых людей, позволяя гибко настраивать сценарии под каждого.

Основные функции:

• Идентификация людей по базе сохранённых лиц;
• Настраиваемые действия для знакомых (например, приветствие, открытие замка);
• Отдельные действия для незнакомцев (например, оповещение, запись видео);
• Переопределение режима обучения для автоматического добавления новых лиц.

Первоначальная настройка

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

1. Перейдите в Настройки → Устройства и службы → VK Cloud Vision → Настроить → Распознавание лиц.
2. В разделе «Режим обучения» включите «Добавлять новые лица» и «Обновлять сохранённые образцы».
3. Сохраните настройки.

Все новые лица, попадающие в кадр, будут автоматически сохраняться в базу. Каждому новому человеку будет присвоен тег с порядковым номером (например, person1, person2).

Important

Не забудьте отключить автоматическое обучение, когда все нужные лица будут добавлены — иначе посторонние и гости тоже попадут в базу.

Tip

Если со временем лицо стало распознаваться хуже (например, из-за смены причёски, очков или бороды) — включите флаг «Обновлять сохранённые образцы» на несколько дней. Интеграция обновит векторное представление лица под текущую внешность.

Ручное обучение

Для обучения по произвольному фото:

1. Перейдите в Настройки → Устройства и службы → VK Cloud Vision → Настроить → Ручное обучение.
2. Загрузите фото с лицом.
3. Выберите пространство (по умолчанию 0).
4. Укажите псевдоним (будет использоваться вместо person1).
5. Сохраните настройки.

Оповещение при обнаружении объектов

Отправляет push-уведомления при обнаружении заданных объектов с прикреплением стоп-кадра и списком распознанных объектов. Логирует все обнаруженные объекты в журнал (logbook).

Доступные сервисы

Интеграция предоставляет несколько действий для анализа изображений с камер:

vkcloud_vision.detect_objects

Обнаруживает объекты, сцены или автомобильные номера на изображениях с камеры. Позволяет сохранять стоп-кадры с рамками вокруг обнаруженных объектов.

Параметры:

• modes (необязательное, по умолчанию ["multiobject"]) — режимы распознавания. Доступные варианты:
  • multiobject: Искать на изображении мультиобъекты — объекты и все множество боксов всех найденных объектов.
  • car_number: Распознавание автомобильных номеров.
  • object: Искать на изображении объекты.
  • object2: Искать на изображении объекты (версия модели v2 — распознает объекты, принадлежащие большему количеству классов).
  • scene: Распознавание сцен.
  • pedestrian: Искать на изображении людей (более точно определяет множество боксов всех людей на изображении).
  • selfie: Определение селфи.
• prob_threshold (необязательное, по умолчанию 0.1): Минимальная вероятность (от 0 до 1) для включения обнаруженных объектов в результаты. Например, значение 0.1 означает, что будут учитываться только объекты с точностью обнаружения не менее 10%.
• file_out (необязательное): Путь для сохранения стоп-кадра с разметкой (например, /config/www/vkcloud_vision_snapshot.jpg).
• bounding_boxes (необязательное, по умолчанию rus): Стиль отображения рамок:
  • none: Не отображать рамки;
  • no_labels: Только рамки без подписей;
  • rus: Подписи на русском языке;
  • eng: Подписи на английском языке.
• num_snapshots (необязательное, по умолчанию 1): Количество последовательных стоп-кадров, снимаемых с камеры заданным интервалом. Повышает точность распознавания, особенно для движущихся объектов.
• snapshot_interval_sec (необязательное, по умолчанию 0.5): Интервал в секундах между стоп-кадрами.
• max_retries (необязательное, по умолчанию 3): Количество попыток повторного выполнения запросов к API в случае таймаутов или временных ошибок.

Пример использования:

action: vkcloud_vision.detect_objects
target:
  entity_id: camera.front_door
data:
  modes:
    - multiobject
    - car_number
  file_out: /config/www/vkcloud_vision_snapshot.jpg
  bounding_boxes: rus

vkcloud_vision.recognize_faces

Определяет лица на изображении, сравнивает их с сохранёнными в базе, а при включённом режиме обучения автоматически сохраняет новые лица.

Параметры:

• space (обязательное) — числовой идентификатор пространства. В каждом пространстве хранится свой набор лиц, что удобно для разделения сценариев: например, space 0 для домашних, а space 1 для офиса.
• create_new (необязательное) — если true, то новые лица будут автоматически добавляться в пространство. Значение по умолчанию зависит от соответствующей настройки в разделе «Режим обучения».
• update_embedding (необязательное) — если true, то векторное представление лица обновляется при каждом совпадении, улучшая точность распознавания в будущем. Отключите для изображений низкого качества. Значение по умолчанию зависит от соответствующей настройки в разделе «Режим обучения».
• confidence_threshold (необязательное, по умолчанию 0.1): Минимальная степень уверенности детектора (от 0 до 1) в том, что обнаруженное изображение является лицом. Например, значение 0.1 означает, что будут учитываться только обнаружения с уверенностью не менее 10%.
• max_retries (необязательное, по умолчанию 3): Количество попыток повторного выполнения запросов к API в случае таймаутов или временных ошибок.

Действие возвращает структурированный ответ со списком найденных лиц, координатами, степенью похожести и дополнительными атрибутами (пол, возраст, эмоции).

Пример использования:

action: vkcloud_vision.recognize_faces
target:
  entity_id: camera.front_door
data:
  space: 0

Настройка режима обучения

Режим обучения настраивается в параметрах интеграции (Настройки → Устройства и службы → VK Cloud Vision → Настроить → Распознавание лиц). Можно независимо включить опции для автоматического добавления новых лиц и обновления векторных представлений. Эти настройки определяют значения по умолчанию для параметров create_new и update_embedding. Вы по-прежнему можете переопределить их в явном виде при вызове действия.

vkcloud_vision.recognize_text

Распознает текст на снимках с камеры (например, надписи на автомобилях и других объектах).

Параметры:

• lang (необязательное): Язык текста для повышения точности распознавания. Доступные значения: rus (русский), eng (английский). По умолчанию используется автоопределение.
• max_retries (необязательное, по умолчанию 3): Количество попыток повторного выполнения запросов к API в случае таймаутов или временных ошибок.

Пример использования:

action: vkcloud_vision.recognize_text
target:
  entity_id: camera.front_door
data:
  lang: rus

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

Если интеграция оказалась полезной, вы можете угостить автора чашечкой кофе. Ваша благодарность ценится!

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

Огромное спасибо всем, кто поддерживает этот проект:

Уведомление

Данная интеграция является неофициальной и не связана с VK Cloud. VK Cloud Vision — это сервис, предоставляемый VK Cloud.

Данная интеграция не является официальным продуктом VK Cloud и не поддерживается VK.

Лицензия

Код интеграции распространяется на условиях Mozilla Public License Version 2.0.

Включает шрифт Tuffy Bold Тэтчера Ульриха. Сам шрифт находится в общественном достоянии.

---

VK Cloud Vision for Home Assistant

This integration brings cloud-based object and text recognition to Home Assistant using the VK Cloud Vision service. Leverage computer vision to create automations based on image analysis from surveillance cameras.

Key Features

• Object and license plate detection using the vkcloud_vision.detect_objects action.
• Face recognition with person identification and automatic enrollment of new faces.
• Text recognition on scene photos (e.g., vehicle inscriptions) using the vkcloud_vision.recognize_text action.
• Create automations based on image analysis from surveillance cameras.
• Save snapshots with annotations of detected objects.

Installation and Setup

Prerequisites

1. Sign up at VK Cloud.
2. Get Client ID and Client Secret in the dashboard.
3. Save the keys for integration setup.

Installation

1. Open HACS → Integrations.
2. Click the three-dot menu in the top right and select Custom repositories.
3. Add the repository: https://github.com/black-roland/homeassistant-vkcloud-vision, select Integration as the category.
4. Find and install the VK Cloud Vision integration.
5. Restart Home Assistant.

Configuration

1. Go to Settings → Devices & Services → Add Integration or use the configuration button.
2. Enter the Client ID and Client Secret obtained from VK Cloud.
3. Save the configuration and restart Home Assistant if prompted.

Face Recognition

Training Mode Configuration

The training mode settings are configured in the integration settings (Settings → Devices & Services → VK Cloud Vision → Configure → Face Recognition). In the "Training Mode" section, you can independently enable two options:

• "Create New Faces" (create_new) — automatically add unrecognized faces to the database.
• "Update Embeddings" (update_embedding) — update stored face references to improve future recognition accuracy.

These settings define the default values for the create_new and update_embedding parameters in the vkcloud_vision.recognize_faces service. You can still override them explicitly when calling the service.

Donations

If this integration has been useful to you, consider buying the author a coffee. Your gratitude is appreciated!

Thank you

Notice

This is a community project, not affiliated with VK Cloud. VK Cloud Vision is a service provided by VK Cloud.

This integration is not an official VK Cloud product and is not supported by VK.

License

This integration is released under the Mozilla Public License Version 2.0.

Includes the Tuffy Bold font by Thatcher Ulrich, which is in the public domain.