Обзор

Mevratek — облачная платформа, которая выступает «мозгом» для любого парка устройств. Устройства — тонкие клиенты: они передают кадры с камеры, телеметрию и текущую задачу, а облако возвращает структурированные команды действий. Всё принятие решений выполняется в облаке через AI Decision Engine (поддержка YandexGPT, GigaChat, Claude и локальных моделей).

Базовый URL API: https://api.mevratek.ru/api/v1 · Интерактивный API: Swagger / OpenAPI

Архитектура

Чистая слойная архитектура. Логические сервисы:

  • API-шлюз — аутентификация устройств, маршрутизация.
  • Движок решений — собирает промпт из capabilities устройства, вызывает AI-движок, возвращает строгий JSON.
  • Реестр устройств — id, тип, доступные команды, статус подключения.
  • Движок задач — назначение / очередь / выдача / завершение задач.
  • Память — история решений и задач, результаты.
  • Телеметрия — заряд, скорость, координаты, ошибки.

Устройство описывается полностью данными (его тип + capabilities), поэтому новые типы устройств не требуют изменений ядра.

Быстрый старт

Подключите устройство за три вызова (SDK не обязателен):

# 1. Register (once) — returns a bearer token
curl -X POST https://api.mevratek.ru/api/v1/robots/register \
  -H "Content-Type: application/json" \
  -d '{"name":"rover-01","robot_type":"rover",
       "capabilities":[{"type":"move_forward"},{"type":"stop"}]}'

# 2. Ask the brain for the next actions
curl -X POST https://api.mevratek.ru/api/v1/brain/decision \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"task":"approach the bottle","state":{"battery":80}}'

Или используйте Python SDK, либо попробуйте вживую в Симуляторе.

Устройства и реестр

Устройство регистрируется один раз: имя, robot_type и список capabilities — команд, которые оно понимает, каждая с необязательными ограничениями значения:

{
  "name": "scout-01",
  "robot_type": "rover",
  "capabilities": [
    {"type": "move_forward",
     "value": {"type": "number", "min": 0, "max": 1, "unit": "m"}},
    {"type": "turn_left",
     "value": {"type": "number", "min": 0, "max": 180, "unit": "deg"}},
    {"type": "stop"}
  ]
}

Регистрация возвращает token (bearer) и одноразовый api_key. Мозг возвращает только команды из списка capabilities самого устройства. Присутствие (онлайн/офлайн) отслеживается по heartbeat.

Движок решений

POST /brain/decision принимает задачу, необязательный кадр (image_b64 или frame_url) и текущее состояние. Мозг собирает промпт из capabilities устройства и недавних решений, вызывает AI-движок со строгой JSON-схемой, валидирует ответ и отбрасывает неподдерживаемые команды. Именно этот вызов разработчик встраивает в код своего устройства (через SDK bot.decide(...) или обычный HTTP) — Симулятор просто демонстрирует его в интерфейсе.

Движок задач

Задачи создаются сверху (оператор/API назначает их устройству с приоритетом) или снизу — из собственного запроса решения устройства. Устройства забирают следующую задачу из очереди и отчитываются о результате.

# Assign a task (priority: higher is dequeued first)
POST /tasks            {"robot_id":"...","description":"bring the box","priority":5}

# Robot pulls its next queued task (marks it in_progress)
GET  /tasks/next       (Authorization: Bearer <token>)  -> task | 204

# Robot reports the outcome
POST /tasks/{id}/result {"status":"completed","result":"delivered"}

Телеметрия

Устройства шлют показания в POST /telemetry: заряд, скорость, координаты (x/y/z), список ошибок и любые дополнительные сенсоры. Последние значения показываются на странице устройства.

Память

Каждое решение сохраняется (цель, мысль, уверенность, действия, кадр, модель, задержка) вместе с историей задач — полный журнал, доступный через GET /logs и в дашборде.

Аутентификация

Устройства аутентифицируются bearer-токеном из регистрации и действуют «от себя» — robot_id берётся из токена, а не из тела запроса. Передавайте его в каждом вызове: Authorization: Bearer <token>

Authorization: Bearer <token>

API-ключи

Каждый пользователь/приложение может сгенерировать персональный API-ключ на вкладке API. Секрет показывается один раз; хранится только хэш и короткий префикс. Ключи можно отозвать в любой момент; передаются в заголовке X-API-Key.

X-API-Key: cbk_xxxxxxxx...

Слой абстракции устройств (DAL)

DAL позволяет облаку управлять любым устройством через единый протокол. LLM никогда не выдаёт аппаратные команды — она выдаёт универсальные действия, а платформа транслирует их в собственные низкоуровневые команды устройства на основе его capabilities. Новые типы устройств подключаются без изменения ядра.

Универсальные действия

Устройство объявляет низкоуровневые capabilities (например move_forward, arm_grasp, camera_capture, speaker_say, light_on). Из них платформа выводит универсальные действия, доступные устройству (например grasp, release, inspect, say). Мозгу показываются только они, и он возвращает универсальные действия.

{
  "goal": "inspect_object",
  "actions": [
    {"type": "grasp"},
    {"type": "inspect"},
    {"type": "release"}
  ]
}

Транслятор действий

Транслятор сопоставляет каждое универсальное действие с первой поддерживаемой устройством командой, присваивая уникальный action_id (для обратной связи о выполнении). Неподдерживаемые действия отбрасываются.

grasp    -> arm_grasp       (action_id: a1b2…)
inspect  -> camera_capture  (action_id: c3d4…)
release  -> arm_release     (action_id: e5f6…)

Устройство получает только выполнимые команды; в ответе есть и actions (команды устройства), и universal_actions (что решил мозг).

Профиль устройства

GET /robots/{id}/profile возвращает единое описание устройства:

  • robot_type
  • capabilities (низкоуровневые команды)
  • supported_commands
  • supported_actions (универсальные действия)
  • firmware_version, protocol_version

Задайте firmware_version / protocol_version при регистрации.

Обратная связь о выполнении

После выполнения команды устройство сообщает результат в POST /executions (action_id, status: success|failed, duration_ms, error).

{"action_id": "123", "status": "success", "duration_ms": 450}
// or
{"action_id": "123", "status": "failed", "error": "object_not_found"}

Свежая обратная связь подаётся в следующее решение — мозг учится на том, что произошло на самом деле.

Память и обучение

Каждое решение сохраняется со всем контекстом для обучения: входное состояние, решение (универсальные + транслированные команды устройства) и связанные результаты выполнения. Эта история питает краткосрочный контекст и адаптацию со временем.

Маршрутизатор моделей

Движок решений не зависит от конкретного вендора. Переключайте движок настройкой LLM_PROVIDER без изменения API:

  • claude — Anthropic (или туннель через ANTHROPIC_BASE_URL)
  • openai — OpenAI API
  • yandexgpt — YandexGPT (через OpenAI-совместимый шлюз)
  • gigachat — GigaChat (через OpenAI-совместимый шлюз)
  • local — любой OpenAI-совместимый endpoint (Ollama, vLLM, LM Studio) через OPENAI_BASE_URL
  • auto — выбор по заданным ключам; иначе детерминированный mock

Российские модели и локальный / on-prem деплой

Mevratek нейтрален к движку. YandexGPT и GigaChat поддерживаются через OpenAI-совместимый шлюз (задайте LLM_PROVIDER=yandexgpt или gigachat + OPENAI_BASE_URL / OPENAI_API_KEY). Для полностью локального / изолированного развёртывания запустите любой OpenAI-совместимый сервер (Ollama, vLLM, LM Studio) и укажите OPENAI_BASE_URL с LLM_PROVIDER=local — данные не покидают вашу инфраструктуру, а вся платформа разворачивается у вас (один backend-сервис + PostgreSQL).

Эндпоинты API

МетодПутьАвториз.Описание
POST/robots/register—Регистрация устройства
POST/robots/heartbeatтокенСигнал «жив»
GET/robots—Список устройств
GET/robots/{id}—Детали устройства
GET/robots/{id}/profile—Профиль устройства (DAL)
POST/robots/{id}/pause—Остановить устройство
POST/robots/{id}/resume—Запустить устройство
POST/brain/decisionтокенПолучить решение
POST/executionsтокенОтправить результат выполнения
GET/executions—Запросить результаты выполнения
POST/telemetryтокенПринять телеметрию
POST/tasks—Назначить задачу
GET/tasks/nextтокенЗабрать следующую задачу
POST/tasks/{id}/resultтокенОтчитаться о задаче
GET/logs—Логи решений
POST/GET/DELETE/api-keys—Управление API-ключами

Полный интерактивный справочник: Swagger UI.

Формат решения

Мозг всегда возвращает строгий JSON — без свободного текста:

{
  "goal": "approach the object",
  "thought": "bottle detected on the table",
  "confidence": 0.91,
  "actions": [
    {"type": "move_forward", "value": 0.5},
    {"type": "turn_left", "value": 15}
  ]
}

SDK

Официальный Python SDK оборачивает все эндпоинты. См. вкладку SDK для установки и примеров. Подходит и любой язык с HTTP-клиентом.

Дашборд

  • Устройства — обзор парка и статус в реальном времени.
  • Логи решений — все решения мозга.
  • Задачи — назначение задач и очередь.
  • Симулятор — регистрация устройства и запрос решения.
  • API — генерация и отзыв API-ключей.
  • SDK — установка и использование.
  • Клик по устройству — его задачи, решения, телеметрия и кнопка Стоп/Запустить.

Развёртывание

Деплой из GitHub как один backend-сервис + PostgreSQL (Redis не нужен; объектное хранилище опционально). Задайте SECRET_KEY, DATABASE_URL (postgresql+asyncpg://…) и AI-движок (ANTHROPIC_API_KEY / OPENAI_* / LLM_PROVIDER). Дашборд — необязательный второй сервис с NEXT_PUBLIC_API_BASE_URL.

Частые вопросы

Нужно ли добавлять устройства вручную?

Нет. Устройства сами регистрируются через API из своего кода (Симулятор — только для тестов).

Что если AI-движок не настроен?

Мозг работает в детерминированном mock-режиме, поэтому платформа работает офлайн. Настройте любой движок (YandexGPT, GigaChat, Claude, OpenAI или локальную модель), чтобы получать реальные решения.

Могут ли подключаться разные типы устройств?

Да — устройство определяется данными capabilities; ядро не меняется.