> 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-local-speech-to-text.md).

# Локальная транскрибация

Локальная транскрибация звонков в MikoPBX: записи остаются внутри PBX, распознавание выполняется на Mac-обработчике, а готовые расшифровки доступны в интерфейсе модуля и через API.

**Модуль локальной транскрибации** распознает речь в записанных звонках MikoPBX и сохраняет готовую расшифровку как диалог. Аудиофайлы не отправляются во внешние облачные сервисы: PBX создает очередь заданий, а отдельное приложение **Local STT Worker** скачивает назначенную запись, распознает ее локально через выбранный в MikoPBX движок Parakeet или WhisperKit и отправляет результат обратно в MikoPBX.

{% hint style="info" %}
PBX-модуль работает внутри MikoPBX. Отдельное приложение Local STT Worker выпускается для Mac на Apple Silicon. Подробное описание приложения приведено в статье [Local STT Worker](/mikopbx/modules/miko/module-local-speech-to-text/miko-ai-worker.md).
{% endhint %}

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FTYl2BFU3tQZmbhBjhQ6Q%2FSTTModuleTranscriptCard.png?alt=media&amp;token=d01921a1-4a2b-4d7b-a1b1-de9219f23015" alt=""><figcaption><p>Пример результата транскрибации</p></figcaption></figure>

### Как проходит обработка

1. Звонок завершается, и MikoPBX сохраняет запись разговора.
2. Фоновый процесс модуля находит запись и создает задание.
3. Local STT Worker получает lease задания.
4. PBX отдает назначенному обработчику файл записи.
5. Worker подготавливает аудио, запускает указанный в задании движок и Core ML-модель, затем формирует сегменты расшифровки.
6. Модуль фильтрует результат, сохраняет расшифровку и публикует событие для интеграций.

Если Worker перестает продлевать lease, задание возвращается в очередь.

### Требования и совместимость

* MikoPBX **2025.1.1** или новее.
* macOS **14.0** или новее на Mac с Apple Silicon.
* Включенная запись разговоров для нужных маршрутов, очередей или сотрудников.
* Сетевой доступ от Mac к веб-интерфейсу MikoPBX.
* Интернет при первой загрузке выбранной модели и ее служебных файлов. После загрузки модели для обработки достаточно доступа к PBX.

### Установка модуля

1. Откройте веб-интерфейс MikoPBX.
2. Перейдите в раздел **Модули** → **Маркетплейс модулей**.

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FmxR3E47vRwk4is6vayNM%2FMikoPBXModuleMarketplace.png?alt=media&amp;token=13a28fc5-173b-4251-bfd9-d362dcd73a6b" alt=""><figcaption><p>Маркетплейс модулей</p></figcaption></figure>

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

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2Ft0qmpS8ZminKzHV82iyk%2FSTTModuleInstalledModulesSection.png?alt=media&amp;token=f78715a4-614d-4f42-8d36-98e956befa74" alt=""><figcaption><p>Включение модуля</p></figcaption></figure>

5. Нажмите кнопку настроек справа от версии модуля.

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FOJNPbd9N4CPH72ZrmMCN%2FSTTModuleOpen.png?alt=media&amp;token=f4d9b0b5-8d48-4984-9b2c-26fbe54cfbf7" alt=""><figcaption><p>Переход на страницу модуля</p></figcaption></figure>

### Вкладка «Настройки»

| Настройка                                                 | По умолчанию  | Назначение                                                                                                 |
| --------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| **Язык по умолчанию**                                     | Автоматически | Языковая подсказка для движка распознавания. В автоматическом режиме Worker определяет язык по результату. |
| **Базовый интервал проверки, сек.**                       | `30`          | Интервал сканирования новых CDR-записей. Диапазон: `30`–`3600`.                                            |
| **Максимальная длительность распознаваемой записи, мин.** | `60`          | Записи с известной длительностью выше лимита пропускаются. Диапазон: `1`–`1440`.                           |
| **Звонков за один проход**                                | `50`          | Количество CDR, проверяемых за один цикл. Диапазон: `1`–`1000`.                                            |
| **Время ожидания задания, сек.**                          | `1800`        | Срок lease без успешного продления. Диапазон: `60`–`86400`.                                                |
| **Период обработки записей**                              | `30 дней`     | За какой период искать завершенные звонки с записью: 1, 7, 30, 90, 180, 365 дней или все записи.           |
| **Срок хранения расшифровок**                             | `1 год`       | Через сколько удалять результаты транскрибации: 30, 90, 180, 365 дней или никогда.                         |
| **Термины для распознавания**                             | пусто         | Названия компаний, продуктов, систем и другие слова-подсказки.                                             |

Период обработки не может превышать срок хранения расшифровок. Срок хранения отсчитывается от завершения распознавания; CDR и исходные аудиозаписи не удаляются.

{% hint style="info" %}
При изменении периода обработки позиция сканирования сбрасывается, чтобы модуль пересмотрел историю в новом диапазоне.
{% endhint %}

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2F5TquJrLzZZ2QkRI7YazD%2FSTTModuleMain.png?alt=media&amp;token=852fb709-e2a9-4fe1-9a38-c4b02efc91ff" alt=""><figcaption><p>Раздел настроек модуля</p></figcaption></figure>

#### Термины для распознавания

Термины можно вводить через запятую, точку с запятой или с новой строки, а также загрузить из TXT-файла. Модуль удаляет дубликаты и передает Worker до 100 терминов длиной до 120 символов каждый.

Кнопка **Скачать шаблон** сохраняет пример TXT-файла.

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2F2vfWKwxFbAQRyQCuyZVz%2FSTTTerminology.png?alt=media&amp;token=aad86f9c-3329-441b-84ce-a037a9d253b7" alt=""><figcaption><p>Термины для распознавания</p></figcaption></figure>

#### Параметры обработки аудио

Параметры декодирования моделей WhisperKit, нормализация, VAD, максимальная длительность сегмента и перекрытие централизованно хранятся в MikoPBX и передаются зарегистрированным обработчикам. В текущей версии расширенный блок этих параметров скрыт, поэтому настраивать их через интерфейс модуля или Worker нельзя.

### Вкладка «Каталог моделей»

Здесь выбирается модель, которую PBX передает в новые задания. Выбор применяется централизованно ко всем обработчикам и отображается в Local STT Worker после синхронизации настроек.

{% hint style="warning" %}
Parakeet поддерживает 25 языков: болгарский, хорватский, чешский, датский, нидерландский, английский, эстонский, финский, французский, немецкий, греческий, венгерский, итальянский, латышский, литовский, мальтийский, польский, португальский, румынский, словацкий, словенский, испанский, шведский, русский и украинский. Для другого языка выберите модель WhisperKit либо смените модель перед обработкой таких звонков.
{% endhint %}

| Модель                     | Когда выбирать                          | Особенности                                                                                   |
| -------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Parakeet TDT 0.6B v3**   | Большинство звонков                     | Модель по умолчанию. Быстро распознает длинную речь на 25 языках через движок Parakeet.       |
| **Whisper Large V3 Turbo** | Нужна проверенная универсальная модель  | Хороший баланс скорости и качества для обычных многоязычных звонков через WhisperKit.         |
| **Whisper Podlodka Turbo** | Почти все разговоры проходят на русском | Дообученная версия Whisper для русской речи из `smkrv/whisper-podlodka-turbo-coreml`.         |
| **Whisper Large V3**       | Качество важнее скорости                | Самая тяжелая модель каталога для сложных и неразборчивых записей. Работает через WhisperKit. |

После выбора нажмите **Сохранить модель**.

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FUNSsllHJtmPawMnM6TLG%2FSTTNEWModelMarketplace4RU.png?alt=media&amp;token=33b3da77-a0ab-4613-8987-c2e35c285441" alt=""><figcaption><p>Выбор модели</p></figcaption></figure>

#### Состав каталога

Каталог содержит только четыре проверенные модели из таблицы выше. Добавление произвольных пользовательских репозиториев через интерфейс больше не поддерживается: Worker принимает только согласованные сочетания движка и Core ML-артефакта, переданные модулем.

{% hint style="warning" %}
Сохраненные ранее пользовательские модели не расширяют текущий каталог. После обновления выберите одну из поддерживаемых моделей и сохраните выбор.
{% endhint %}

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2F9iHCbSZegS3j39OjNzoP%2FSTTModuleAddHuggingFaceModel.png?alt=media&amp;token=6db6c3b3-214e-413a-9ca8-8a14406b4072" alt=""><figcaption><p>Добавление модели Hugging Face</p></figcaption></figure>

### Вкладка «Очередь»

| Статус                  | Значение                                                       |
| ----------------------- | -------------------------------------------------------------- |
| **В очереди**           | Задание ждет свободный Worker.                                 |
| **В работе**            | Задание закреплено за Worker действующим lease.                |
| **Готово сегодня**      | Задания, завершенные за текущий день.                          |
| **Ошибки**              | Неуспешные задания, которые можно вернуть в очередь.           |
| **Ожидают файл записи** | CDR найден, но файл еще не появился или недоступен для чтения. |
| **Пропущенные записи**  | Записи, которые не будут обработаны без изменения условий.     |

Причины пропуска включают превышение максимальной длительности, невозможность подтвердить длительность слишком длинной по данным CDR записи, превышение фиксированного предела 500 MiB, отсутствие файла по истечении срока ожидания и выход звонка за период обработки. Неизвестная или нулевая длительность CDR сама по себе не блокирует создание задания. Если длительность CDR превышает лимит, модуль перепроверяет фактическую длительность файла через `ffprobe` с ограничением времени выполнения.

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FjnUGVvWP4ylPV9kffMQ6%2FSTTWorkerQueue.png?alt=media&amp;token=e67d3b43-75f9-4b60-ae8b-63e8977b3ed6" alt=""><figcaption><p>Вид очереди в интерфейсе модуля</p></figcaption></figure>

### Вкладка «Обработчики»

На этой вкладке создаются ключи доступа, отображаются зарегистрированные Mac и проверяется их совместимость.

Ключ показывается только один раз после создания. Один ключ не может быть привязан сразу к нескольким `worker_uid`; для нескольких Mac создайте отдельные ключи. После удаления ключа связанный Worker необходимо зарегистрировать с новым токеном.

Таблица обработчиков показывает имя, UID, IP, выбранную в MikoPBX модель, версию приложения, состояние и последнюю активность. Версия Worker API и отдельная колонка совместимости больше не выводятся. Несовместимый Worker отображается офлайн; ссылка на инструкцию по обновлению остается под таблицей.

<mark style="color:$danger;">В верхней части вкладки предусмотрен блок загрузки приложения для macOS. Пока сборка не опубликована в этом блоке, кнопка загрузки остается недоступной.</mark>

<mark style="color:red;">Устарело</mark>

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FbxY0OZrCV8HUXrTKVTsE%2FSTTModuleCreatingANewWorkerKey.png?alt=media&amp;token=4fcd14b2-7ed9-40ba-84b5-c3a4992f436f" alt=""><figcaption><p><mark style="color:$danger;">Прежний вид вкладки обработчиков</mark></p></figcaption></figure>

### Вкладка «Расшифровки»

Список можно фильтровать по диапазону дат звонков. В таблице отображаются дата, `call_id`, номер задания, файл, язык, длительность, модель и время создания результата.

Карточка диалога содержит проигрыватель и скачивание записи, реплики с таймкодами, отдельные колонки каналов для стерео, сгруппированную диагностику, исходную техническую информацию и JSON расшифровки. Нажатие на реплику переводит проигрыватель к соответствующему моменту.

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FSjVFDGA0Yi3TtgtCjXMp%2FSTTModuleTranscripts.png?alt=media&amp;token=980bfeae-9837-4390-a01e-c6d3eef89b12" alt=""><figcaption><p>Список расшифровок</p></figcaption></figure>

<figure><img src="https://3704471835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPK4TuzRBnP7rt8htho-887967055%2Fuploads%2FTYl2BFU3tQZmbhBjhQ6Q%2FSTTModuleTranscriptCard.png?alt=media&amp;token=d01921a1-4a2b-4d7b-a1b1-de9219f23015" alt=""><figcaption><p>Вид карточки расшифровки</p></figcaption></figure>

### Вкладка «Журнал»

Журнал содержит структурированные технические события модуля и обработчиков без расшифровок, аудиозаписей и секретов. Доступны периоды `1h`, `3h`, `12h`, `1d` и весь журнал, фильтры по уровню и компоненту, полнотекстовый поиск и обновление списка. В интерфейсе показывается не более 1000 последних подходящих событий.

### Обновление модуля и Worker

При переходе на Worker API v2 соблюдайте порядок:

1. Обновите ModuleLocalSpeechToText до версии 1.45.
2. Старые обработчики временно станут несовместимыми и офлайн; активные lease v1 вернутся в очередь без увеличения числа попыток.
3. Обновите Local STT Worker до версии 1.7 build 34.
4. Откройте **Диагностика** или **Настройки** Worker и повторите проверку подключения.

Очередь, готовые результаты, настройки, UID обработчиков и существующие API-ключи сохраняются. Обновление MikoPBX Core сверх версии 2025.1.1 для этого перехода не требуется.

### REST API

Базовый путь:

```
/pbxcore/api/v3/module-local-speech-to-text
```

#### Расшифровки для интеграций

* `GET /transcripts?limit=50&offset=0&date_from=YYYY-MM-DD&date_to=YYYY-MM-DD`
* `GET /transcripts/{result_id}`
* `GET /transcripts/events?cursor=created_at:event_id&limit=100`
* `GET /call-transcripts/{call_transcript_id}?revision={revision}`
* `GET /call-transcripts/events?cursor={cursor}&limit=100`

`transcripts/events` публикует идемпотентные события `transcript.completed`. Детальная расшифровка содержит стабильные `segment_id`, исходные сегменты, объединенные реплики `turns` и простой текст.

`call-transcripts` объединяет несколько записей одного логического звонка в версионную расшифровку. Манифест частей сохраняет `cdr_start_ms` и `cdr_end_ms`, а сегменты содержат относительные и абсолютные таймкоды. Соседние сегменты одного участника и канала объединяются в одну реплику без потери исходных `segment_id`.

#### Worker API v2

Worker сначала вызывает `GET /worker-api-contract`, а затем передает заголовок `X-MikoPBX-Worker-API-Version: 2` во всех запросах Worker API.

Ответ `GET /worker-processing-settings` содержит централизованный профиль обработки и объект `selected_model` с идентификатором, репозиторием, движком, типом Core ML-артефакта и отображаемым названием модели. Задание также содержит `model_engine` и `model_artifact_type`, по которым Worker выбирает Parakeet или WhisperKit. Произвольные сочетания движка, модели и артефакта отклоняются.

| Операция            | Endpoint                          |
| ------------------- | --------------------------------- |
| Регистрация         | `POST /workers`                   |
| Профиль обработки   | `GET /worker-processing-settings` |
| Получение lease     | `POST /job-leases`                |
| Скачивание записи   | `GET /job-recordings/{job_id}`    |
| Продление lease     | `PATCH /job-leases/{job_id}`      |
| Освобождение lease  | `DELETE /job-leases/{job_id}`     |
| Отправка результата | `PUT /job-results/{job_id}`       |
| Отправка ошибки     | `PUT /job-failures/{job_id}`      |

Устаревшие endpoints Worker API v1 удалены. Local STT Worker 1.7 не переключается на v1 и при несовместимой версии модуля останавливается с инструкцией по обновлению.


---

# 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-local-speech-to-text.md?ask=<question>&goal=<endgoal>
```

`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.