> 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 создает очередь заданий, а отдельное приложение **Local STT Worker** скачивает назначенную запись, распознает ее локально через 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="/files/fR3MUQpuvLb0EnIqG2Wz" alt=""><figcaption><p>Пример результата транскрибации</p></figcaption></figure>

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

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

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

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

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

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

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

<figure><img src="/files/5YieJLPTR2xWxDqDsV2O" alt=""><figcaption><p>Маркетплейс модулей</p></figcaption></figure>

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

<figure><img src="/files/9SkH1YplFUXW5lTdUECV" alt=""><figcaption><p>Включение модуля</p></figcaption></figure>

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

<figure><img src="/files/k0DJXoLKD0VArSM0s71H" alt=""><figcaption><p>Переход на страницу модуля</p></figcaption></figure>

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

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

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

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

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

<figure><img src="/files/kmw0wlKhtQhYmjppp3VL" alt=""><figcaption><p>Раздел настроек модуля</p></figcaption></figure>

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

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

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

<figure><img src="/files/CYSO0LDtPGKg3yYisRcm" alt=""><figcaption><p>Термины для распознавания</p></figcaption></figure>

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

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

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

Здесь выбирается модель, которую PBX передает в новые задания.

| Модель             | Когда выбирать                               | Особенности                                               |
| ------------------ | -------------------------------------------- | --------------------------------------------------------- |
| **Base**           | Тесты и слабые Mac                           | Самая быстрая, но менее точная на шуме и коротких фразах. |
| **Small**          | Большая очередь                              | Быстрая модель с приемлемым качеством.                    |
| **Medium**         | Повседневные звонки                          | Баланс качества и нагрузки.                               |
| **Large V3 Turbo** | Рабочая транскрибация (рекомендуемая модель) | Рекомендуемый баланс качества и скорости.                 |
| **Podlodka Turbo** | Русская разговорная речь                     | Core ML-модель `smkrv/whisper-podlodka-turbo-coreml`.     |
| **Large V3**       | Максимальное качество                        | Самая ресурсоемкая и медленная модель.                    |

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

<figure><img src="/files/IQhbspGO9fRqxQT2o1hg" alt=""><figcaption><p>Выбор модели</p></figcaption></figure>

#### Пользовательская модель Hugging Face

Можно добавить собственную WhisperKit/Core ML-совместимую модель. Укажите репозиторий `owner/repository`, имя runtime-модели, название, язык, лицензию, ярлыки, ссылку и описание.

{% hint style="warning" %}
Обычная модель Hugging Face без подготовленных Core ML-артефактов не подойдет для Local STT Worker.
{% endhint %}

<figure><img src="/files/ag1BodRyViuKpeOT9Q3P" alt=""><figcaption><p>Добавление модели Hugging Face</p></figcaption></figure>

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

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

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

<figure><img src="/files/WXAJcY4iDykOf3AIHvbo" alt=""><figcaption><p>Вид очереди в интерфейсе модуля</p></figcaption></figure>

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

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

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

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

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

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

<figure><img src="/files/u3QlNkNlyv8GjAmEoB6P" alt=""><figcaption><p><mark style="color:$danger;">Прежний вид вкладки обработчиков</mark></p></figcaption></figure>

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

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

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

<figure><img src="/files/fTfAiImy1809J6iecMWG" alt=""><figcaption><p>Список расшифровок</p></figcaption></figure>

<figure><img src="/files/fR3MUQpuvLb0EnIqG2Wz" 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` и простой текст.

#### Worker API v2

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

| Операция            | 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}`      |


---

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