> For the complete documentation index, see [llms.txt](https://docs.mikopbx.com/mikopbx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mikopbx.com/mikopbx/modules/miko/module-a-i-supervisor.md). # Модуль ИИ Супервайзер **Модуль ИИ Супервайзер** анализирует готовые расшифровки звонков MikoPBX и превращает их в рабочую панель контроля качества: краткие и подробные сводки, причины обращения, итоги, следующие действия, темы, риски, тональность, оценки риска и качества, а также очередь звонков, которые нужно проверить руководителю. Сам модуль MikoPBX не запускает языковую модель. Он хранит настройки, ключи доступа, очередь заданий и результаты анализа, а обработку выполняет приложение **MIKO AI Worker** на Mac через локальную среду, например Ollama. Звонки и расшифровки остаются внутри вашей инфраструктуры. {% hint style="info" %} На данный момент серверная часть доступна только на OSx, в будущем планируется расширение и под другие платформы. В данной статье представлено ограниченное описание работы приложения-обработчика: более подробную версию можно найти в подстатье - [здесь](/mikopbx/modules/miko/module-a-i-supervisor/miko-ai-worker.md). {% endhint %}

Главная страница модуля

### Что делает модуль * Импортирует события `transcript.completed` из модуля распознавания речи. * Создает очередь ИИ-анализа для расшифровок, по которым еще нет результата. * Передает задания только локальным обработчикам с отдельным токеном контроля звонков. * Позволяет выбрать профиль локальной модели, язык результата, глубину анализа, время ожидания и повторы. * Поддерживает компоненты анализа: сводка, голосовые метрики, обогащение эмоций и акустические сигналы. * Сохраняет результат: сводку, причину обращения, исход, следующие действия, темы, риски, доказательства, тональность, оценку риска и оценку качества. * Показывает звонки, которые требуют внимания: высокий риск, низкое качество, негативная тональность или проблемные отметки ИИ. * Ведет разбор обращения: статус, ответственный, приоритет, срок, заметки, причина закрытия и история действий. * Показывает обзор, выводы, очередь анализа, диагностику, состояние интеграции с расшифровками и журнал событий. ### Как устроен анализ Решение состоит из трех частей: 1. **Модуль распознавания речи** создает расшифровку звонка и публикует событие `transcript.completed`. 2. **Модуль ИИ Супервайзер** импортирует ссылку на расшифровку, создает задание и сохраняет результат анализа. 3. **MIKO AI Worker на Mac** забирает задания, готовит локальную модель, анализирует текст и отправляет результат обратно в MikoPBX. Обычный цикл выглядит так: 1. Звонок завершился, запись была расшифрована модулем распознавания речи. 2. ИИ Супервайзер импортирует событие о готовой расшифровке. 3. Модуль создает задание `call_summary` и помещает его в очередь. 4. Обработчик на Mac получает задание через API `/jobs:getNext`. 5. Обработчик подготавливает локальную модель, анализирует расшифровку и при необходимости отправляет промежуточные результаты. 6. Итоговый JSON-результат возвращается в PBX и проходит проверку на стороне модуля. 7. Результат появляется в разделах **Звонки**, **Обзор** и **Выводы**. {% hint style="info" %} Доказательства в результате ИИ должны ссылаться на реальные `segment_id` из расшифровки. Это позволяет открыть подтверждающий фрагмент разговора и не полагаться только на свободный пересказ модели. {% endhint %} ### Требования * MikoPBX **2025.1.1** или новее. * Установленный и включенный **модуль распознавания речи**. * Готовые расшифровки звонков в модуле распознавания речи. * Установленный и включенный **Модуль ИИ Супервайзер**. * Приложение **MIKO AI Worker** на Mac. * Сетевой доступ от Mac к веб-интерфейсу MikoPBX. * Доступ в интернет при первом запуске для установки локальной среды и загрузки модели, если она еще не установлена. * Достаточно места на Mac для локальной модели. Для профиля `qwen3:8b` ориентируйтесь примерно на 5 ГБ, для `qwen3:14b` нужен больший запас. {% hint style="warning" %} ИИ Супервайзер не анализирует аудио напрямую. Если в модуле распознавания речи нет готовой расшифровки звонка, ИИ-разбор для такого звонка не появится. {% endhint %} ### Установка модуля 1. Откройте веб-интерфейс MikoPBX. 2. Перейдите в раздел **"Модули"** → **"Маркетплейс модулей"**.

Раздел "Маркетплейс модулей"

3. Найдите **Модуль ИИ Супервайзер** и установите его. 4. Перейдите в список установленных модулей и включите модуль.

Включение модуля "ИИ Супервайзер"

5. Откройте страницу модуля, нажав на иконку **"Настройки"** справа от версии модуля.

Переход в настройки модуля "ИИ Супервайзер"

### Вкладка "Обзор" Вкладка **Обзор** показывает состояние контроля звонков за выбранный период.

Вкладка "Обзор" в модуле "ИИ Супервайзер"

Основные показатели: | Показатель | Что означает | | ------------------------- | -------------------------------------------------------------------------------------------------------- | | **Звонки с расшифровкой** | Сколько импортированных расшифровок попало в выбранный период. | | **Разобрано ИИ** | Доля звонков, по которым уже сохранен результат анализа. | | **Средняя длительность** | Средняя длительность звонков в выбранном периоде. | | **Требуют внимания** | Открытая очередь звонков с рисками, низким качеством, негативной тональностью или проблемными отметками. | Ниже отображаются графики динамики звонков, распределение по сотрудникам, направления звонков, тон общения и короткая очередь проверки. Нажатие на показатели открывает соответствующий фильтр в разделе **Звонки** или **ИИ-анализ**. ### Вкладка "Звонки" Вкладка **Звонки** - основная рабочая область супервайзера. Здесь отображаются импортированные звонки с расшифровкой и результатом ИИ, если он уже готов.

Вкладка "Звонки" в модуле "ИИ Супервайзер"

Доступны фильтры: | Фильтр | Назначение | | ------------------- | -------------------------------------------------------------------------------------- | | **Период** | Быстрые периоды `1 день`, `7 дней`, `30 дней` или ручной диапазон дат. | | **Поиск** | Поиск по номеру, сотруднику, теме или `call_id`. | | **Статус проверки** | Открытые или закрытые обращения. | | **Разбор** | Статусы разбора обращения: открыт, в работе, ожидание, эскалация, закрыт или отклонен. | | **Срок** | Просроченные, на сегодня или без срока. | | **Направление** | Внутренние, внешние или звонки по конкретному номеру. | | **Сотрудник** | Фильтр по внутреннему номеру или имени сотрудника. | | **Тональность** | Позитивная, нейтральная, нейтрально-негативная, негативная. | | **Качество** | Высокое, среднее или низкое качество обслуживания. | | **Риск** | Высокий, средний или низкий риск. | В таблице видны дата, участники, длительность, тема, статус разбора и действия. Можно выбрать несколько строк и массово перевести обращения в работу, закрыть или вернуть в непроверенные. #### **Карточка звонка** Откройте строку звонка, чтобы увидеть карточку разбора. В карточке отображаются: * краткая и подробная сводка; * причина обращения и итог звонка; * следующие действия; * темы и риски; * подтверждающие фрагменты расшифровки; * ключевые моменты с переходом по времени; * речевые сигналы и голосовые метрики, если они включены; * оценка риска, качества и тональности; * блок разбора обращения с ответственным, приоритетом, сроком, заметками и причиной закрытия. Если запись доступна, можно открыть связанную карточку расшифровки из модуля распознавания речи.

Карточка звонка в модуле "ИИ Супервайзер"

### Вкладка "Выводы" Вкладка **Выводы** строит сводную аналитику по сохраненным результатам ИИ.

Вкладка "Выводы" в модуле ИИ Супервайзер

Здесь доступны: * краткое управленческое резюме за период; * изменения относительно предыдущего периода; * топ проблем; * причины попадания в очередь внимания; * главные темы звонков; * причины негативной тональности; * очередь звонков, требующих проверки.

Вкладка "Выводы" в модуле ИИ Супервайзер

Каждый блок можно использовать как вход в фильтр раздела **Звонки**: например, открыть все звонки по конкретной теме или проблеме.

Пример поиска по фильтру

### Вкладка "ИИ-анализ" Вкладка **ИИ-анализ** показывает очередь обработки и позволяет вручную запускать разбор новых звонков или повторять ошибочные задания.

Вкладка "ИИ Анализ" в модуле ИИ Супервайзер

**Состояние обработки** | Статус | Что означает | | ------------------ | ---------------------------------------------------------------------------------- | | **Новые звонки** | Импортированные расшифровки, по которым еще нет ИИ-разбора. | | **Ожидают** | Задания созданы и ждут свободного обработчика на Mac. | | **В работе** | Задание закреплено за обработчиком. Закрепление продлевается сигналами активности. | | **Нужны действия** | Задания с ошибкой или задания, которые можно вернуть в очередь. | | **Готово** | Разбор сохранен в MikoPBX. | | **Пропущено** | Пустые, малоинформативные или не подлежащие анализу расшифровки. | Доступные действия: | Действие | Назначение | | ---------------------------------- | -------------------------------------------------------------------------------------------------------- | | **Запустить анализ новых звонков** | Вручную начаит поиск импортированных расшифровок без результата и создать задания (обычно не требуется). | | **Повторить ошибочные** | Вернуть задания с ошибкой в очередь после проверки причины сбоя. | | **Повторить** | Вернуть конкретное задание в очередь. | | **Открыть звонок** | Перейти к связанному звонку в разделе **Звонки**. | В карточке задания отображаются номер задания, тип, `call_id`, попытки, время создания, время обновления, обработчик, ссылка на расшифровку, результат ИИ и текст ошибки. ### Вкладка "Настройки" Вкладка **Настройки** разделена на несколько подразделов. #### **Старт** Раздел **Старт** показывает карту готовности: | Блок | Что проверяется | | ---------------------- | ---------------------------------------------------------- | | **Доступ обработчика** | Есть ли токен контроля звонков для обработчика на Mac. | | **Импорт расшифровок** | Доступен ли модуль распознавания речи и включен ли импорт. | | **ИИ-анализ** | Создаются ли задания анализа для новых расшифровок. | | **Правила внимания** | Порог риска, порог качества и включенные правила отбора. | | **Справочник рисков** | Системные и пользовательские типы рисков. |

Раздел "Старт" в настройках модуля

Здесь же можно включить импорт, включить ИИ-анализ, запустить импорт вручную и выбрать срок хранения данных: `3 месяца`, `6 месяцев`, `1 год`, `2 года` или **Бессрочно**. #### **Подключение** В разделе **Подключение** создаются ключи доступа для MIKO AI Worker. Нажмите **Создать ключ доступа** и сразу скопируйте значение из поля **Показан один раз**. После обновления страницы полный ключ больше не отображается: в списке будет виден только замаскированный ключ. В таблице ключей отображаются: * ключ; * дата создания; * последнее использование; * количество привязанных обработчиков; * права доступа; * кнопка удаления. {% hint style="warning" %} ИИ Супервайзер использует отдельный токен контроля звонков. Не вставляйте сюда токен обработчика речи из модуля распознавания речи: он предназначен только для распознавания речи. {% endhint %}

Раздел "Подключение" в настройках модуля

#### **ИИ-анализ** Раздел **ИИ-анализ** управляет тем, какие задания будут отправляться локальному обработчику и как он должен их выполнять.

Раздел "ИИ-анализ" в настройках модуля

| Настройка | Значение по умолчанию | Описание | | ----------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------- | | **Сводка** | включено | Структурированный разбор: сводка, риски, темы, качество и следующие действия. | | **Обрабатывать внутренние звонки** | выключено | Если выключено, звонки между сотрудниками остаются в списке, но не отправляются на ИИ-анализ. | | **Подставлять имена из телефонной книги** | выключено | Если установлен модуль "Телефонная книга", внешние номера можно показывать именами контактов. | | **Язык результата** | **Как в звонке** | Можно оставить автоматически или принудительно выбрать русский/английский. | | **Голосовые метрики** | включено | Добавляет детерминированные сигналы темпа, пауз, перебиваний и баланса участников. | | **Анализ эмоций** | выключено | Ограниченное обогащение эмоций по фрагментам голоса. | | **Акустический анализ** | выключено | Асинхронно добавляет просодические и акустические признаки к сохраненному результату. | **Профили моделей** | Профиль | Модель | Когда выбирать | | ------------------------ | ----------- | ---------------------------------------------------------------------------- | | **Qwen3 8B Instruct Q4** | `qwen3:8b` | Рекомендуемый повседневный вариант для русских звонков, сводок. | | **Gemma 3 4B IT Q4** | `gemma3:4b` | Легкий профиль для не самых мощных Mac и большого потока коротких звонков. | | **Qwen3 14B Quality** | `qwen3:14b` | Более качественный, но более тяжелый вариант для длинных и сложных диалогов. | В блоке **Какие звонки здесь чаще всего?** выберите типовую длину звонков: **Короткие**, **Средние** или **Длинные**. Этот выбор влияет на размер контекста и фрагмента, который получит обработчик. В раскрытом блоке **Экспертные параметры обработки** доступны формулировки, удержание модели в памяти, время ожидания и количество повторов. #### **Внимание** Раздел **Внимание** определяет, какие звонки попадут в очередь проверки супервайзера.
| Настройка | Значение по умолчанию | Описание | | ------------------------------- | --------------------- | ---------------------------------------------------------------------------- | | **Чувствительность к риску** | `60` | Звонок требует внимания, если оценка риска не ниже порога. | | **Чувствительность к качеству** | `55` | Звонок требует внимания, если оценка качества ниже порога. | | **Негативная тональность** | включено | Звонки с негативной тональностью клиента попадают на проверку. | | **Проблемные отметки ИИ** | включено | Риски, проблемы и предупреждения, найденные ИИ, попадают в очередь внимания. | #### **Справочник рисков** В разделе **Справочник рисков** можно расширить системный каталог типами проблем вашей компании. Системные типы: * **Повторное обращение** * **Срок не назначен** * **Проблема не решена** * **Угроза отмены** * **Нужна эскалация** * **Ошибка оператора** * **Негативная тональность** * **Неэффективное общение** * **Нарушение регламента** * **Другой риск** Свои типы добавляются отдельно: укажите название, код типа, синонимы, категорию, важность по умолчанию и короткую инструкцию для модели. Системные типы нельзя переопределять. Ниже находится **Справочник тем компании**. Он помогает приводить разные формулировки ИИ к вашим бизнес-категориям: например, `техническая поддержка`, `оплата`, `запрос документов`.

Раздел "Справочник рисков" в настройках модуля

#### **Диагностика** Раздел **Диагностика** показывает техническое состояние модуля: * доступность модуля распознавания речи; * доступность сервиса интеграции с расшифровками; * очередь событий распознавания речи; * текущий `stt_event_cursor`; * профиль модели, контекст, размер фрагмента и правила повторов; * базовые маршруты API обработчика; * покрытие анализа; * последние события журнала. В раскрытом блоке **Дополнительные настройки импорта** доступны размер пакета импорта, источник расшифровок и позиция чтения событий. Эти параметры обычно меняют только при диагностике или восстановлении импорта.

Раздел "Диагностика" в настройках модуля

### REST API для интеграций Базовый путь API: ``` /pbxcore/api/v3/module-ai-supervisor ``` Основные методы для интерфейса и интеграций: | Метод | Адрес | Описание | | ------- | ------------------------------- | -------------------------------------------------------------------- | | `GET` | `/health` | Проверка состояния интеграции с расшифровками и модуля. | | `GET` | `/settings` | Текущие настройки модуля. | | `PATCH` | `/settings` | Изменение настроек модуля. | | `GET` | `/dashboard` | Данные обзора и выводов. | | `POST` | `/imports:run` | Ручной запуск импорта расшифровок. | | `GET` | `/calls` | Список импортированных звонков с фильтрами. | | `GET` | `/calls/{id}` | Детальная карточка звонка. | | `PATCH` | `/calls/{id}:review` | Отметить звонок проверенным или вернуть в проверку. | | `PATCH` | `/calls/{id}:workflow` | Изменить статус, ответственного, приоритет, срок и причину закрытия. | | `POST` | `/calls/{id}:note` | Добавить заметку к обращению. | | `GET` | `/calls/{id}:history` | Получить историю разбора обращения. | | `POST` | `/calls:bulkWorkflow` | Массово обновить разбор обращения по нескольким звонкам. | | `GET` | `/jobs` | Список заданий ИИ-анализа и счетчики очереди. | | `POST` | `/jobs:enqueue` | Создать задания для новых расшифровок. | | `POST` | `/jobs:retryFailed` | Вернуть ошибочные задания в очередь. | | `GET` | `/logs` | Последние события журнала модуля. | | `GET` | `/connection` | Состояние ключей доступа обработчиков. | | `POST` | `/connection:generateApiKey` | Создать ключ доступа для обработчика. | | `POST` | `/connection/{id}:deleteApiKey` | Удалить ключ доступа. | Основные методы обработчика на Mac: * `POST /workers:register` * `GET /jobs:getNext?worker_uid=...` * `GET /jobs/{id}:downloadRecording?worker_uid=...&download_token=...` * `POST /jobs/{id}:heartbeat` * `POST /jobs/{id}:release` * `POST /jobs/{id}:submitPartial` * `POST /jobs/{id}:submitResult` * `POST /jobs/{id}:submitVoiceAnalytics` * `POST /jobs/{id}:submitError` {% hint style="info" %} Для новых интеграций используйте REST API, а не прямое чтение таблиц модуля. Так интеграция останется совместимой с будущими изменениями структуры хранения. {% endhint %} ### Типовые сценарии **Начать анализировать только новые звонки** 1. Убедитесь, что модуль распознавания речи уже создает расшифровки. 2. В **Настройки** → **Старт** включите импорт расшифровок и ИИ-анализ. 3. В **Настройки** → **Подключение** создайте ключ доступа для обработчика. 4. Подключите MIKO AI Worker на Mac. 5. Откройте **ИИ-анализ** и нажмите **Запустить анализ новых звонков**, если нужно начать сразу. **Догнать уже накопленные расшифровки** 1. В **Настройки** → **Диагностика** проверьте состояние интеграции с расшифровками. 2. Нажмите **Запустить импорт** в разделе **Старт**. 3. Откройте **ИИ-анализ** и нажмите **Запустить анализ новых звонков**. 4. Следите за счетчиками **Ожидают**, **В работе**, **Готово** и **Нужны действия**. **Уменьшить количество звонков в очереди внимания** 1. Откройте **Настройки** → **Внимание**. 2. Выберите более спокойные пороги риска и качества. 3. При необходимости выключите правило **Негативная тональность** или **Проблемные отметки ИИ**. 4. Сохраните настройки. Новые правила применяются к построению очереди и фильтров. Уже сохраненные результаты анализа не пересчитываются автоматически. ### Если что-то не работает **В разделе "Звонки" пусто** * Проверьте, что установлен и включен модуль распознавания речи. * Убедитесь, что в модуле распознавания речи есть готовые расшифровки. * Откройте **Настройки** → **Диагностика** и проверьте статус интеграции с расшифровками. * Нажмите **Запустить импорт**. **Задания не появляются** * Проверьте, что включен **ИИ-анализ**. * Нажмите **Запустить анализ новых звонков** на вкладке **ИИ-анализ**. * Если внутренние звонки должны анализироваться, включите **Обрабатывать внутренние звонки**. * Проверьте, не попали ли расшифровки в **Пропущено** из-за пустого или малоинформативного текста. **Обработчик не подключается** * Убедитесь, что в MIKO AI Worker вставлен именно токен контроля звонков. * Проверьте адрес PBX и доступность MikoPBX с Mac. * Если используется собственный HTTPS-сертификат, проверьте настройки TLS и файл CA в обработчике. * Если ключ доступа удаляли, создайте новый ключ и вставьте его в обработчик. **Модель не готовится** * Проверьте доступ в интернет при первой загрузке модели. * Откройте в MIKO AI Worker раздел **Модели ИИ** и нажмите **Проверить среду** или **Проверить модель**. * Убедитесь, что на Mac достаточно свободного места. * Для слабого Mac выберите профиль **Gemma 3 4B IT Q4** вместо **Qwen3 8B** или **Qwen3 14B**. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.mikopbx.com/mikopbx/modules/miko/module-a-i-supervisor.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.