queen detection

Обнаружение королевы — техническая документация

🎯 Обзор

Система обнаружения пчелиных маток на базе искусственного интеллекта, использующая модели машинного обучения для идентификации пчелиных маток на загруженных фотографиях кадров. В настоящее время для обнаружения используется Clarifai API, и планируется разработать внутреннюю модель для повышения точности. Часть автоматизированного конвейера анализа кадров, запускаемая при загрузке фотографии.

🏗️ Архитектура

Компоненты

  • DetectionOverlay: компонент Canvas отображает обнаруженные ферзи в виде ограничивающих рамок.
  • QueenIndicator: компонент пользовательского интерфейса, показывающий статус присутствия королевы.
  • FrameAnalysisPanel: боковая панель, отображающая количество обнаружений и достоверность.

Услуги

  • image-splitter: организует конвейер обнаружения, сохраняет результаты.
  • Clarifai API: внешняя служба ML для обнаружения королев (текущая реализация).
  • models-bee-detector: внутренний сервис моделей (поддерживает маток, но низкая точность ~60%).
  • swarm-api: хранит метаданные присутствия королевы, связанные с кадрами.

📋 Технические характеристики

Конвейер обнаружения

1. Frame photo uploaded → image-splitter
2. Create detection job (type: detect_queens)
3. Job processor invokes detection:
   a. Primary: Clarifai API call
   b. Fallback: models-bee-detector (if enabled)
4. Parse detection response (boxes + confidence)
5. Store detections in MySQL
6. Publish Redis event
7. Update queen presence in swarm-api

GraphQL API

type QueenDetection {
  id: ID!
  frameSideId: ID!
  bbox: BoundingBox!
  confidence: Float!
  verifiedByUser: Boolean
  createdAt: DateTime!
}

type BoundingBox {
  x: Int!
  y: Int!
  width: Int!
  height: Int!
}

type FrameSide {
  id: ID!
  url: String!
  queenDetections: [QueenDetection!]
  hasQueen: Boolean
}

query frameSide($id: ID!) {
  frameSide(id: $id) {
    id
    queenDetections {
      id
      bbox {
        x
        y
        width
        height
      }
      confidence
    }
  }
}

mutation verifyQueenDetection($detectionId: ID!, $verified: Boolean!) {
  verifyQueenDetection(detectionId: $detectionId, verified: $verified) {
    id
    verifiedByUser
  }
}

🔧 Детали реализации

Фронтенд

  • Framework: Реагируйте с помощью TypeScript.
  • Визуализация: холст HTML5 для наложения обнаружения.
  • Визуализация: желтая ограничительная рамка с меткой оценки достоверности.
  • Взаимодействие: нажмите, чтобы подтвердить или отклонить обнаружение.
  • Состояние: кэш Apollo для данных обнаружения.

Серверная часть (image-splitter)

  • Язык: TypeScript/Node.js.
  • Служба обнаружения: клиент Clarifai gRPC.
  • Резервный вариант: Внутренние модели-детектор пчел REST API
  • Обработка заданий: асинхронная очередь с логикой повтора.
  • Хранение: результаты обнаружения сохраняются в виде данных JSON bbox.

Интеграция Clarifai

async function detectQueens(imageUrl: string): Promise<Detection[]> {
  const stub = ClarifaiStub.grpc();
  
  const metadata = new grpc.Metadata();
  metadata.set("authorization", `Key ${CLARIFAI_API_KEY}`);

  const request = {
    userAppId: {
      userId: CLARIFAI_USER_ID,
      appId: CLARIFAI_APP_ID
    },
    inputs: [{
      data: {
        image: { url: imageUrl }
      }
    }]
  };

  const response = await stub.PostModelOutputs(request, metadata);
  
  return response.outputs[0].data.regions.map(region => ({
    bbox: {
      x: region.regionInfo.boundingBox.leftCol * imageWidth,
      y: region.regionInfo.boundingBox.topRow * imageHeight,
      width: region.regionInfo.boundingBox.width * imageWidth,
      height: region.regionInfo.boundingBox.height * imageHeight
    },
    confidence: region.value,
    type: 'queen'
  }));
}

Внутренняя модель (models-bee-detector)

  • Рамка: YOLOv5 (Ultralytics)
  • Вес: модель обнаружения медоносных пчел Мэтта Нуди.
  • Набор данных: набор данных юниверса Roboflow.
  • Точность: ~60% для ферзей (низкая точность).
  • Классы: рабочий, трутень, королева, варроа.
  • Проблемы: высокий уровень ложноположительных результатов для маток.

⚙️ Конфигурация

Переменные среды

CLARIFAI_API_KEY=xxx
CLARIFAI_USER_ID=clarifai
CLARIFAI_APP_ID=main

MODELS_BEE_DETECTOR_URL=http://models-bee-detector:8700
MODELS_BEE_DETECTOR_ENABLED=false

QUEEN_DETECTION_CONFIDENCE_THRESHOLD=0.6

🧪 Тестирование

Модульные тесты

  • Местоположение: /test/detection/queens.test.ts
  • Охват: анализ обнаружения, расчет bbox, доверительная фильтрация.
  • Высмеивает: ответы Clarifai API.

Интеграционные тесты

  • Местоположение: /test/integration/queen-detection-flow.test.ts
  • Тесты:
    • Полный конвейер обнаружения (загрузка → обнаружение → сохранение → запрос)
    • Интеграция Clarifai API
    • Возврат к внутренней модели
    • Рабочий процесс проверки пользователя

Ручное тестирование

Тестовые изображения доступны в:

  • /test/fixtures/queens/ - Известные изображения королевы
  • Примеры изображений из набора данных с проверенными королевами.

📊 Вопросы производительности

Метрики

  • Задержка Clarifai API: 2–5 секунд на изображение.
  • Порог достоверности обнаружения: 0,6 (настраиваемый)
  • Уровень ложноположительных результатов: ~30% (Clarifai), ~50% (внутренняя модель)
  • Доля истинно положительных результатов: ~70% (Clarifai), ~60% (внутренняя модель)

Узкие места

  • Ограничение скорости Clarifai API: 10 запросов в секунду.
  • Внешняя зависимость API (задержка сети)
  • Большие изображения требуют более длительной обработки.
  • Стоимость: 0,0012 доллара США за прогноз Clarifai.

Планы оптимизации

  • Обучение внутренней модели с более высокой точностью.
  • Реализация ансамбля моделей (голосование нескольких моделей)
  • Кэшировать результаты для идентичных изображений
  • Пакетная обработка нескольких кадров

🚫 Технические ограничения

Текущие ограничения

  • Точность: уровень обнаружения 60–70 % (не готов к производству для принятия критически важных решений)
  • Ложные срабатывания: высокий показатель требует ручной проверки.
  • Отмеченные ферзи: невозможно обнаружить помеченных ферзей по-другому (пятна краски сбивают с толку модель).
  • Качество изображения: плохое освещение или фокусировка значительно снижают точность.
  • Зависимость Clarifai: внешняя зависимость API для достижения наилучших результатов.
  • Стоимость: стоимость каждого обнаружения для Clarifai API.
  • Без отслеживания: невозможно отследить одну и ту же королеву на нескольких фотографиях.

Известные проблемы

  • Модель путает крупных рабочих пчел с матками.
  • Помеченные ферзи (с точками краски) часто промахиваются
  • Часто встречается несколько ложных срабатываний на изображение
  • Нет достоверной калибровки (оценки не калиброваны должным образом)
  • Смещение набора данных: обучение в основном на светлых королевах.

🔗 Сопутствующая документация

📚 Ресурсы для разработки

Репозитории GitHub

Ключевые файлы

  • Задание по обнаружению: /src/jobs/detect-queens.ts
  • Клиент Clarifai: /src/integrations/clarifai.ts
  • Наложение frontend: /src/page/hive/frameSide/DetectionOverlay.tsx.

Ресурсы для обучения моделей

💬 Технические примечания

  • Текущая точность (~60-70%) ненадежна для автоматических оповещений без проверки пользователя.
  • Используется Clarifai, поскольку внутреннее обучение модели не завершено.
  • План на будущее: обучение внутренней модели с использованием более крупного набора данных по конкретной королеве.
  • Рассмотрите ансамблевый подход: несколько моделей голосуют за более высокую степень достоверности.
  • Отзывы пользователей о проверке могут быть использованы для переобучения модели.
  • Помеченные королевы (окрашенные) требуют отдельного класса обнаружения.
  • Обнаружение королевы более ценно в сочетании с временной шкалой управления королевой.
  • Ложноположительные результаты менее критичны, чем ложноотрицательные (отсутствующая королева хуже)

Дорожная карта улучшений

  1. Соберите более крупный набор данных по конкретным маткам (более 1000 помеченных маток).
  2. Обучите внутреннюю модель YOLOv8 с помощью трансферного обучения.
  3. Внедрить модельный ансамбль (Clarifai + внутреннее + голосование)
  4. Добавьте цикл обратной связи с пользователем для улучшения модели.
  5. Обнаружение меченых и немаркированных ферзей отдельно.
  6. Внедрить доверительную калибровку
  7. Добавьте отслеживание королевы на нескольких фотографиях.

Последнее обновление: 5 декабря 2025 г.