Система компьютерного зрения для контроля качества продукции на производственных линиях. Описание функциональных характеристик, инструкция по установке и руководство по эксплуатации.
Программа предназначена для автоматического визуального контроля объектов, поступающих на вход системы в форме отдельных изображений или непрерывных видеопотоков, с использованием методов глубокого обучения и компьютерного зрения. Программа обеспечивает:
Программа ориентирована на применение в широком спектре прикладных задач, требующих автоматизации визуального анализа без необходимости постоянного участия оператора.
Модуль обеспечивает обнаружение объектов в изображении или в отдельных кадрах видеопотока с использованием сверточных нейронных сетей детекции объектов, представленных в формате обмена нейросетевыми моделями ONNX и совместимых с библиотекой исполнения нейросетей ONNX Runtime, а также с библиотекой ускоренного исполнения NVIDIA TensorRT. Возможности:
Модуль обеспечивает идентификацию одних и тех же объектов в последовательных кадрах видеопотока и формирование их траекторий движения. Алгоритмическая основа: ByteTrack через библиотеку supervision. Возможности: присвоение уникальных идентификаторов, сохранение идентификатора при кратковременной потере объекта из кадра, формирование траекторий движения.
Модуль обеспечивает формирование текстовых описаний визуальной сцены на русском языке с использованием мультимодальной языковой модели (Vision-Language Model, VLM). Возможности:
Модуль определяет моменты, в которые целесообразно выполнить ресурсоёмкий семантический анализ, исходя из условий: превышение уверенности детекции установленного порога; появление в кадре нового объекта; истечение заданного временного интервала; пользовательские условия из конфигурационного файла.
Программа предоставляет интерфейс на основе архитектурного стиля REST для взаимодействия с внешними информационными системами. Реализация на базе HTTP/HTTPS и формата обмена данными JSON.
| Метод | URI | Назначение |
|---|---|---|
| GET | /health | Проверка работоспособности сервиса |
| GET | /stats | Получение статистики обработки |
| POST | /analyze/image | Анализ изображения (отдельный файл) |
| POST | /analyze/json | Анализ изображения, переданного в формате Base64 |
| POST | /analyze/vlm-only | Только семантический анализ через VLM |
| POST | /analyze/video | Анализ видеопотока (стриминговый ответ) |
| GET | /docs | Интерактивная документация API (Swagger UI) |
Унифицированный программный интерфейс детекции с адаптерами под различные аппаратные платформы — переносимость между вычислительными средами без изменения прикладного кода. Поддерживаемые платформы:
Выбор платформы осуществляется автоматически на основе доступного оборудования либо может быть задан явно в конфигурационном файле.
| Основной язык | Python версии 3.10 и выше |
|---|---|
| Типизация | Статическая типизация через аннотации (type hints) |
| Парадигма | Объектно-ориентированное программирование с элементами функционального |
| Асинхронность | Асинхронное программирование на основе библиотеки asyncio |
| Архитектурный паттерн детекции | Адаптер (Adapter) |
| Архитектурный паттерн обработки | Конвейер (Pipeline) |
| Компонент | Лицензия | Назначение |
|---|---|---|
| PyTorch | BSD-3-Clause | Фреймворк глубокого обучения |
| OpenCV | Apache 2.0 | Библиотека обработки изображений |
| NumPy | BSD-3-Clause | Численные вычисления |
| FastAPI | MIT | Каркас REST API |
| Uvicorn | BSD-3-Clause | ASGI-сервер |
| Pydantic | MIT | Валидация данных |
| supervision (Roboflow) | MIT | Трекинг объектов (ByteTrack) |
| YOLOX (Megvii BaseDetection) | Apache 2.0 | Свёрточная нейронная сеть детекции объектов (anchor-free YOLO) |
| ONNX Runtime | MIT | Среда исполнения нейросетевых моделей в формате ONNX |
| Pillow | HPND | Работа с растровыми изображениями |
| aiohttp | Apache 2.0 | Асинхронный HTTP-клиент |
| Ollama | MIT | Локальный сервер мультимодальных языковых моделей |
| PyYAML | MIT | Парсинг конфигурационных файлов |
Все перечисленные компоненты являются открытым программным обеспечением с лицензиями, разрешёнными к использованию в Российской Федерации, и не включены в список запрещённых компонентов, указанный в подпункте «б» пункта 5 Постановления Правительства Российской Федерации от 16.11.2015 № 1236.
| Модель | Тип | Лицензия весов |
|---|---|---|
| YOLOX-S / YOLOX-Tiny (Megvii BaseDetection) | Детектор объектов с архитектурой anchor-free YOLO; экспорт в ONNX для исполнения через ONNX Runtime / TensorRT / HailoRT | Apache 2.0 |
| Qwen2.5-VL-3B-Instruct | Vision-Language Model | Apache 2.0 |
Обе модели могут быть заменены на альтернативные или дообучены на пользовательских данных без изменения архитектуры программы.
Российские операционные системы (из Единого реестра российского ПО):
Общесистемные операционные системы (для разработки и сборки): Ubuntu 22.04 LTS+, Debian 12+, Microsoft Windows 10/11 (через WSL2), Raspberry Pi OS Bookworm, NVIDIA JetPack 6.0+.
Измерения проведены на эталонных моделях YOLOX-S (детекция) и Qwen2.5-VL-3B (семантический анализ) при разрешении входного изображения 640×640 пикселей:
| Платформа | Режим | Производительность (FPS) |
|---|---|---|
| NVIDIA RTX 3090 Ti | CUDA 12.x | Более 100 |
| NVIDIA RTX 3060 | CUDA 12.x | 60–80 |
| NVIDIA Jetson Orin Nano Super | TensorRT FP16 | 90 и более |
| Raspberry Pi 5 + Hailo-8L | HailoRT (NPU) | 50–60 |
| Intel Core i7 (CPU-режим) | CPU | 5–10 |
Программа допускает расширение области применения за счёт дообучения моделей детекции и семантического анализа на пользовательских данных без изменения архитектуры и базовой функциональности.
Программное обеспечение KapiVision относится к сфере искусственного интеллекта в соответствии с критериями, установленными Приказом Министерства экономического развития Российской Федерации от 29 июня 2021 года № 392.
В соответствии с Приказом Минцифры России от 22.09.2020 № 486 программное обеспечение KapiVision относится к классам:
Русский язык — для семантических описаний сцен, формируемых мультимодальной языковой моделью, для технической документации и сообщений службы технической поддержки.
Английский язык — для технических идентификаторов программного интерфейса REST (имена методов, полей JSON) в соответствии с общепринятой отраслевой практикой.
| Процессор | Не менее 4 физических ядер с поддержкой AVX2 (Intel Core i5-8xxx или AMD Ryzen 5 3xxx и выше) |
|---|---|
| Оперативная память | Не менее 8 ГБ |
| Дисковое пространство | Не менее 10 ГБ свободного места на системном диске |
| Операционная система | Ubuntu 22.04 LTS, Debian 12, Windows 10/11 (с WSL2), Raspberry Pi OS Bookworm |
| Среда исполнения | Python версии 3.10 и выше; Docker версии 24.0 и выше |
| Сетевое подключение | Доступ к сети Интернет для первоначального скачивания зависимостей и моделей |
| Процессор | Не менее 8 физических ядер |
|---|---|
| Оперативная память | Не менее 16 ГБ |
| Графический ускоритель | NVIDIA с поддержкой CUDA 11.x или 12.x, не менее 8 ГБ видеопамяти (рекомендуется RTX 3060 и выше) |
| Дисковое пространство | Не менее 30 ГБ свободного места (с учётом моделей Vision-Language) |
| Драйверы | NVIDIA CUDA Toolkit 12.x, NVIDIA Container Toolkit |
В соответствии с Методическими рекомендациями ЦКИТ ООО «КапиТех» предоставляет экземпляр программного обеспечения KapiVision одним из следующих способов:
| Протокол | HTTPS (порт 443) |
|---|---|
| Адрес экземпляра | Доступ к развёрнутому экземпляру предоставляется по запросу — обратитесь на e@kapitech.ru |
| Способ аутентификации | HTTP Basic Authentication (учётные данные предоставляются эксперту в составе подачи) |
| Сертификат TLS | действующий сертификат Let's Encrypt |
| Место физического размещения | офис ООО «КапиТех», 420043, Республика Татарстан, г. Казань, ул. Вишневского, д. 59А, корп. 3, кв. 135 |
| Режим доступности | круглосуточно, 7 дней в неделю |
Архив kapivision-1.0.tar.gz (содержит исходные тексты программы, Dockerfile, docker-compose.yml, конфигурационные файлы и скрипты развёртывания) предоставляется по запросу на электронную почту e@kapitech.ru в течение 1 рабочего дня. Архив подготавливается и хранится на инфраструктуре ООО «КапиТех» на территории Российской Федерации. Ссылка на скачивание направляется в ответном письме.
Образ формата OVA (Ubuntu 22.04 + Docker + KapiVision + модели машинного обучения) предоставляется по запросу в срок до 5 рабочих дней. Размер образа не превышает 10 ГБ. Образ может быть импортирован в VMware Workstation или Oracle VirtualBox.
Способ обеспечивает автоматическое развёртывание всех компонентов в изолированных контейнерах и является наиболее простым для первичного ознакомления с функциональностью.
Шаг 1. Распаковать полученный архив:
tar -xzf kapivision-1.0.tar.gz
cd kapivision-1.0Шаг 2. Запуск контейнеров:
docker compose -f docker/docker-compose.yml up -dВ результате будут запущены: контейнер kapivision-vlm (сервер мультимодальной языковой модели на базе Ollama, порт 11434); контейнер kapivision-api (сервер REST API программного обеспечения, порт 8000).
Шаг 3. Загрузка модели мультимодального анализа:
docker exec kapivision-vlm ollama pull qwen2.5-vl:3bШаг 4. Проверка работоспособности:
curl http://localhost:8000/healthОжидаемый ответ:
{"status": "ok", "yolo_loaded": true, "vlm_loaded": true}Способ применим для случаев интеграции в собственное приложение на Python.
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
pip install -e .[all]
ollama serve &
ollama pull qwen2.5-vl:3b
uvicorn kapivision.api.main:app --host 0.0.0.0 --port 8000bash scripts/setup_jetson.sh — сценарий выполняет установку зависимостей, экспорт модели детектора в формат TensorRT FP16 и регистрацию сервисного юнита systemd.bash scripts/setup_rpi5.shПосле завершения установки рекомендуется выполнить проверку базовой функциональности:
# Состояние сервиса
curl http://localhost:8000/health
# Детекция на тестовом изображении
curl -X POST http://localhost:8000/analyze/image \
-F file=@samples/test_image.jpg
# Доступ к Swagger UI
http://localhost:8000/docsКапитонов Евгений Александрович — Генеральный директор, руководитель разработки.
Электронная почта: e@kapitech.ru. Телефон: +7 (960) 069-81-52. Будние дни с 10:00 до 19:00 по московскому времени.
Программа предназначена для развёртывания на серверах, рабочих станциях или встраиваемых вычислительных платформах эксплуатирующей организации. Конкретные минимальные и рекомендуемые требования к аппаратному и системному программному обеспечению приведены в Разделе 2 «Установка».
Дополнительные эксплуатационные требования:
# Запуск всех контейнеров (фоновый режим)
docker compose -f docker/docker-compose.yml up -d
# Остановка
docker compose -f docker/docker-compose.yml down
# Перезапуск без удаления контейнеров
docker compose -f docker/docker-compose.yml restart
# Просмотр статуса контейнеров
docker compose -f docker/docker-compose.yml psНа платформах Linux, включая Astra Linux, ALT Linux, РЕД ОС, МСВСфера, программное обеспечение работает в виде службы systemd. Сервисный файл kapivision.service устанавливается автоматическим сценарием.
# Запуск службы
sudo systemctl start kapivision
# Остановка службы
sudo systemctl stop kapivision
# Перезапуск
sudo systemctl restart kapivision
# Включение автозапуска при загрузке системы
sudo systemctl enable kapivision
# Просмотр статуса
sudo systemctl status kapivisionНа платформе NVIDIA Jetson программное обеспечение запускается в виде службы kapivision-jetson.service. Управление производится теми же командами systemctl.
На платформе Raspberry Pi программное обеспечение запускается в виде службы kapivision-rpi.service. Управление производится теми же командами systemctl.
Программа предоставляет следующие точки получения метрик:
| Точка | Назначение | Рекомендуемая частота опроса |
|---|---|---|
GET /health | Проверка готовности (liveness/readiness probe) | каждые 30 секунд |
GET /stats | Накопленные статистики обработки (FPS, число анализов, время отклика VLM) | каждые 5 минут |
Пример штатного ответа /health:
{
"status": "ok",
"yolo_loaded": true,
"vlm_loaded": true,
"platform": "cuda",
"uptime_seconds": 86400,
"queue_depth": 2
}Журналы работы программного обеспечения сохраняются в следующих расположениях в зависимости от способа запуска:
docker compose logs -f kapivision-api и docker compose logs -f kapivision-vlm.journalctl -u kapivision -f; сохраняются в системном журнале journald.Логи имеют структурированный формат JSON и содержат поля timestamp, level, module, message, request_id. Уровень логирования настраивается параметром logging.level в конфигурационном файле (значения: DEBUG, INFO, WARNING, ERROR; по умолчанию INFO).
Журналы автоматически ротируются средствами journald (по умолчанию хранение 1 ГБ или 30 дней, в зависимости от настроек ОС). Дополнительная ротация средствами программного обеспечения не выполняется.
Поле queue_depth в ответе /health отражает количество кадров в очереди обработки. Нормальные значения — 0…4. Значения выше 10 указывают на отставание от темпа поступления кадров, что требует вмешательства администратора (см. раздел «Типовые проблемы»).
Поле fps в ответе /stats отражает текущую производительность. Резкое падение FPS относительно эталонных значений (см. таблицу производительности в Разделе 1) — признак проблем с оборудованием или с моделями.
В составе ежедневного эксплуатационного режима рекомендуется выполнять резервное копирование следующих компонентов программного обеспечения:
| Что копируется | Расположение | Частота |
|---|---|---|
| Конфигурационные файлы | configs/ | при каждом изменении |
| Кастомные модели машинного обучения (если обучались под заказчика) | models/ | при каждом изменении |
| Файлы предвычисленных аннотаций | samples/*.annotations.json | еженедельно |
| Журналы работы (если требуется длительное хранение) | системный журнал journald | в соответствии с политикой хранения логов организации |
Резервное копирование выполняется штатными средствами эксплуатирующей организации (rsync, BackupPC, Bareos, отраслевые системы резервного копирования). Восстановление производится возвратом скопированных файлов в исходные расположения и перезапуском службы.
Обновление выполняется получением новой версии архива дистрибутива и применением её на месте. Процедура:
sudo systemctl stop kapivision.# new in 1.x).sudo systemctl start kapivision.curl http://localhost:8000/health.Предобученные модели машинного обучения сохраняются в директории ~/.ollama/models (для мультимодальной языковой модели) и в директории kapivision/weights/ (для детекторов объектов). При нехватке свободного дискового пространства эти каталоги могут быть очищены; файлы моделей будут повторно загружены при следующем запуске службы.
Если экземпляр программного обеспечения опубликован через HTTPS с использованием сертификата Let's Encrypt и обратного прокси-сервера (Caddy, nginx, traefik), необходимо периодически контролировать срок действия сертификата (типичный срок — 90 дней, автоматическое продление за 30 дней до истечения). Проверка: echo | openssl s_client -connect ваш_адрес:443 2>/dev/null | openssl x509 -noout -dates.
Признак: поле queue_depth в ответе /health постоянно превышает 10; поле fps существенно ниже эталонного значения для платформы.
Возможные причины и проверки:
nvidia-smi для NVIDIA, vcgencmd measure_temp для Raspberry Pi); при необходимости улучшить охлаждение.nvidia-smi); при необходимости остановить конкурирующий процесс.Признак: поле vlm_loaded в ответе /health возвращает false; запросы /analyze/vlm-only возвращают ошибку HTTP 503.
Возможные причины и проверки:
systemctl status ollama на Linux), при необходимости перезапустить.free -h), при необходимости остановить конкурирующие процессы.ollama pull qwen2.5-vl:3b.Признак: предупреждение в журнале или сообщение мониторинга об истечении срока действия сертификата.
Возможные причины и проверки:
Признак: в журналах сообщения о невозможности подключения к URL источника; запросы анализа возвращают ошибку.
Возможные причины и проверки:
ping адрес_камеры; telnet адрес_камеры 554 для RTSP).Квалификация: высшее или среднее профессиональное образование в области информационных технологий; опыт администрирования Linux-систем и контейнеров Docker не менее 2 лет; навыки работы с системами мониторинга (Zabbix, Prometheus, Grafana или эквивалент).
Зоны ответственности:
Квалификация: базовые навыки работы с веб-интерфейсами; навыки работы с системой оповещений эксплуатирующей организации.
Зоны ответственности:
Контактные данные службы технической поддержки ООО «КапиТех»:
При обращении в службу технической поддержки рекомендуется приложить выгрузку журналов (journalctl -u kapivision --since '1 hour ago' > /tmp/kapivision.log) и ответ /health на момент возникновения проблемы.