> 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/windows-worker.md).

# Windows-обработчик

Windows-обработчик для локальной транскрибации: установка службы из MSI или ZIP, подключение к MikoPBX, проверка работы, обновление и удаление.

**Windows-обработчик** - служба Windows для локального распознавания записей звонков на вашем компьютере или сервере. Она берет задания из очереди модуля **Локальная транскрибация**, скачивает запись, распознает ее выбранной в MikoPBX моделью и отправляет на станцию сегменты с таймкодами и техническую диагностику. Записи не покидают вашу сеть.

У обработчика нет графического интерфейса: он работает как служба **MikoPBX Local STT Worker**, а настраивается и управляется программой `LocalSTTWorker.exe` из командной строки администратора.

Windows-обработчик работает одновременно с [Local STT Worker для macOS](/mikopbx/modules/miko/module-local-speech-to-text/miko-ai-worker.md) и [Docker-обработчиком](/mikopbx/modules/miko/module-local-speech-to-text/docker-worker.md): у каждой платформы своя модель, выбранная на вкладке **Каталог моделей**, и каждый обработчик получает задания с моделью своей платформы.

### Требования

| Компонент  | Минимум                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------- |
| ОС         | Windows 10/11 или Windows Server 2019 и новее, 64-битная (x64)                                     |
| Память     | 8 ГБ                                                                                               |
| Диск       | около 0,3 ГБ для программы и место для выбранной модели (до 2,5 ГБ)                                |
| Компоненты | [Среда выполнения Visual C++ 2015-2022 x64](https://aka.ms/vs/17/release/vc_redist.x64.exe)        |
| MikoPBX    | 2025.1.1 или новее, модуль **Локальная транскрибация** с платформой **Windows** в каталоге моделей |
| Сеть       | исходящий HTTPS до MikoPBX и huggingface.co (для первой загрузки модели)                           |

Распознавание выполняется на процессоре, видеокарта не нужна.

{% hint style="warning" %}
Без среды выполнения Visual C++ установщик MSI не запустится. Установите `vc_redist.x64.exe` заранее.
{% endhint %}

### Модели

Модель выбирается в MikoPBX: **Модули** → **Локальная транскрибация** → вкладка **Каталог моделей**, платформа **Windows**. Обработчик скачивает модель при первом задании и хранит ее локально. Каждая модель закреплена на конкретной версии, а обработчик сверяет SHA-256 каждого файла.

| Модель                                   | Языки                                                 | Когда выбирать                                         | Размер |
| ---------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------ | ------ |
| **GigaAM v3** (по умолчанию)             | русский                                               | Русские звонки: лучшая точность, пунктуация, цифры     | 0,9 ГБ |
| **Parakeet TDT 0.6B v3**                 | 25 европейских                                        | Европейские языки, язык определяется автоматически     | 2,5 ГБ |
| **GigaAM Multilingual**                  | казахский, киргизский, узбекский, русский, английский | Языки Средней Азии, без пунктуации                     | 0,9 ГБ |
| **Whisper Large V3 Turbo (whisper.cpp)** | около 99 языков                                       | Любые языки и смешанные звонки; самая медленная на CPU | 1,6 ГБ |

{% hint style="info" %}
GigaAM v3 распознает только русскую речь: оставьте язык по умолчанию в настройках модуля автоматическим или русским. Список терминов из MikoPBX пока применяет только модель Whisper.
{% endhint %}

### Шаг 1. Подготовка MikoPBX

1. Откройте **Модули** → **Локальная транскрибация** → вкладка **Каталог моделей**.
2. Переключите платформу на **Windows** и выберите модель, например **GigaAM v3**.
3. Перейдите на вкладку **Обработчики** и выберите платформу **Windows**.
4. Нажмите **Создать ключ доступа** и скопируйте ключ: он показывается один раз и после обновления страницы больше не будет доступен.

### Шаг 2. Скачивание обработчика

На вкладке **Обработчики** для платформы **Windows** есть две кнопки загрузки:

| Пакет   | Файл                                          | Когда выбирать                                                            |
| ------- | --------------------------------------------- | ------------------------------------------------------------------------- |
| **MSI** | `MikoPBX-LocalSTTWorker-<версия>-x64.msi`     | Рекомендуется: устанавливает и запускает службу автоматически             |
| **ZIP** | `MikoPBX-LocalSTTWorker-<версия>-win-x64.zip` | Ручная установка в выбранную папку; службу регистрирует команда `install` |

MikoPBX скачивает последнюю версию обработчика с сервера выпусков MIKO по лицензии станции. Если загрузка недоступна, проверьте, что лицензия MikoPBX активна. Установщик MSI и программа подписаны цифровой подписью.

### Шаг 3. Установка

Все команды выполняются в **командной строке или PowerShell от имени администратора**.

{% tabs %}
{% tab title="MSI (рекомендуется)" %}
Запустите установщик двойным щелчком или из командной строки:

```powershell
msiexec /i MikoPBX-LocalSTTWorker-<версия>-x64.msi /qn /l*v install.log
```

Установщик копирует программу в `C:\Program Files\MikoPBX\LocalSTTWorker`, регистрирует службу **MikoPBX Local STT Worker** (`MikoPBXLocalSTTWorker`) и запускает ее. Пока обработчик не настроен, служба работает и ждет настроек.

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

{% hint style="warning" %}
После установки из MSI не выполняйте `LocalSTTWorker.exe install`: служба уже зарегистрирована.
{% endhint %}
{% endtab %}

{% tab title="ZIP" %}
Распакуйте архив, например в `C:\Program Files\MikoPBX\LocalSTTWorker`. Не изменяйте файлы в папке `Tools`: обработчик сверяет их контрольные суммы и не запустится при расхождении.

Служба регистрируется после настройки, в шаге 4.
{% endtab %}
{% endtabs %}

### Шаг 4. Подключение к MikoPBX (setup)

Перейдите в папку программы и запустите мастер настройки:

```powershell
cd "C:\Program Files\MikoPBX\LocalSTTWorker"
.\LocalSTTWorker.exe setup
```

Мастер спросит:

1. **Адрес MikoPBX** - `https://<адрес-mikopbx>`, при необходимости с портом, без пути.
2. **Принимать ли самоподписанный сертификат MikoPBX** - по умолчанию нет (см. раздел TLS).
3. **UID обработчика** - по умолчанию `windows-<имя-компьютера>`; ключ привязывается к одному UID.
4. **Имя обработчика** - как он будет показан на вкладке **Обработчики**, по умолчанию `Windows STT Worker (<имя-компьютера>)`.
5. **Ключ обработчика** - ключ из шага 1, ввод скрыт.

Затем мастер проверит подключение и зарегистрирует обработчик. Пример успешного результата:

```
MikoPBX Local STT Worker setup
Data folder: C:\ProgramData\MikoPBX\LocalSTTWorker

PBX address (https://host[:port]): https://pbx.example.com
Accept a self-signed PBX certificate? Only on a trusted network [y/N]: y
Worker UID (letters, digits, '.', '_', '-') [windows-office-pc]:
Worker name shown in the module [Windows STT Worker (OFFICE-PC)]:
Worker API key from the module's Workers tab (leave empty to keep the stored one):

Settings saved. Checking the connection...
[ OK ] Bundled tools verified (ffmpeg, whisper.cpp, ONNX assets).
[ OK ] Settings: https://pbx.example.com as 'windows-office-pc'.
[ OK ] Worker API key is stored.
[ OK ] Module <версия>, worker API v2, Windows platform supported.
[ OK ] Worker key accepted; worker registered.
[ OK ] Selected model 'GigaAM v3' is supported; it is downloaded on the first job.

The running service picks up the new settings within 30 seconds.
```

{% tabs %}
{% tab title="MSI" %}
Служба уже работает и подхватит настройки в течение 30 секунд, перезапуск не нужен.
{% endtab %}

{% tab title="ZIP" %}
Зарегистрируйте и запустите службу:

```powershell
.\LocalSTTWorker.exe install
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Чтобы изменить адрес, ключ или имя, запустите `setup` еще раз. Нажмите Enter, чтобы оставить текущее значение; пустой ключ оставляет сохраненный. Запущенная служба подхватит изменения в течение 30 секунд.
{% endhint %}

<details>

<summary>Настройка без ввода ключа с клавиатуры (для скриптов)</summary>

Мастер может читать ответы из стандартного ввода, по одной строке на вопрос и в том же порядке: адрес, самоподписанный сертификат, UID, имя, ключ. Пустая строка оставляет значение по умолчанию. С флагом `--token-stdin` ключ тоже читается из стандартного ввода. Ключ никогда не передается в командной строке.

Создайте файл `answers.txt`:

```
https://<адрес-mikopbx>
y


<ключ-обработчика>
```

и передайте его мастеру:

```powershell
Get-Content .\answers.txt | .\LocalSTTWorker.exe setup --token-stdin
Remove-Item .\answers.txt    # ключ уже сохранен в защищенном хранилище
```

</details>

### Шаг 5. Проверка работы

```powershell
.\LocalSTTWorker.exe status
```

При первом задании обработчик скачивает модель (GigaAM v3 - около 0,9 ГБ) и проверяет ее контрольные суммы, после чего начинает распознавать. Поэтому первое задание выполняется на несколько минут дольше остальных.

1. В MikoPBX на вкладке **Обработчики** появился обработчик со статусом **Онлайн**, платформой **Windows**, его IP и моделью.
2. `status` показывает состояние службы и обработчика и растущий счетчик заданий:

```
Service      : RUNNING
Worker state : polling
Updated      : 2026-10-20 16:02:40 (0 s ago)
Worker UID   : windows-office-pc
Version      : 0.1.22
Model        : GigaAM v3
Jobs         : 3 done, 0 failed, 0 released, 7.2 min of audio
Last job     : #847, 141.1 s audio in 48.0 s (RTF 0.340)
Logs         : C:\ProgramData\MikoPBX\LocalSTTWorker\Logs
```

3. В журнале обработчика `C:\ProgramData\MikoPBX\LocalSTTWorker\Logs\worker-ГГГГММДД.log` видно каждое задание:

```
[info] worker job #853: Claimed job #853 (call mikopbx-1792307715.71) for model 'GigaAM v3'.
[info] worker job #853: Submitted result for job #853: 74 segment(s), duration 251030 ms, processed in 85.4 s.
```

4. В карточке звонка появилась расшифровка, а в ее технической информации - модель, время обработки и RTF.

**RTF** - отношение времени обработки к длительности записи. Например, RTF 0,1 означает, что 10-минутный звонок распознается за минуту. Для ориентира: GigaAM v3 на Intel Xeon E5-2670 (2012 года, без AVX2) работает с RTF около 0,34, то есть 10-минутный звонок распознается примерно за 3,5 минуты.

| Состояние (`Worker state`)                       | Значение                                                                           |
| ------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `not_configured`                                 | Обработчик не настроен: выполните `setup`.                                         |
| `negotiating`, `registering`, `loading_settings` | Подключение к MikoPBX и получение настроек.                                        |
| `polling`                                        | Обработчик ждет задания в очереди.                                                 |
| `processing`                                     | Выполняется задание.                                                               |
| `waiting_for_windows_model`                      | MikoPBX не выдает модель для Windows: обновите модуль (см. «Диагностика проблем»). |
| `unsupported_model`                              | Выбранная модель не поддерживается этой версией обработчика.                       |
| `stopped`, `failed`                              | Служба остановлена или завершилась с ошибкой; см. `Last error` и журнал.           |

### Управление

| Задача                       | Команда                                               |
| ---------------------------- | ----------------------------------------------------- |
| Состояние                    | `.\LocalSTTWorker.exe status`                         |
| Проверить подключение и ключ | `.\LocalSTTWorker.exe check`                          |
| Остановить службу            | `.\LocalSTTWorker.exe stop`                           |
| Запустить службу             | `.\LocalSTTWorker.exe start`                          |
| Изменить настройки           | `.\LocalSTTWorker.exe setup`                          |
| Запустить в консоли          | `.\LocalSTTWorker.exe run` (при остановленной службе) |

Команды выполняются в папке программы от имени администратора. Службой можно управлять и через оснастку **Службы** (`services.msc`). Служба запускается автоматически (отложенный запуск) от имени LocalSystem и перезапускается после сбоя: первые два раза через минуту, затем через пять минут. При остановке текущее задание завершается или возвращается в очередь MikoPBX, новые звонки ждут в очереди.

### Обновление

{% tabs %}
{% tab title="MSI" %}
Скачайте новую версию на вкладке **Обработчики** и запустите установщик так же, как при установке. Старая версия удаляется, новая устанавливается и запускается. Настройки, ключ, модели и журналы сохраняются.

Установить более старую версию поверх новой нельзя: сначала удалите обработчик.
{% endtab %}

{% tab title="ZIP" %}

```powershell
.\LocalSTTWorker.exe stop
```

Замените файлы в папке программы содержимым нового архива и запустите службу:

```powershell
.\LocalSTTWorker.exe start
```

{% endtab %}
{% endtabs %}

### Удаление

{% tabs %}
{% tab title="MSI" %}
Удалите **MikoPBX Local STT Worker** в **Параметры** → **Приложения** или из командной строки администратора:

```powershell
msiexec /x MikoPBX-LocalSTTWorker-<версия>-x64.msi /qn /l*v uninstall.log
```

Не удаляйте службу, установленную из MSI, командой `LocalSTTWorker.exe uninstall`.
{% endtab %}

{% tab title="ZIP" %}

```powershell
.\LocalSTTWorker.exe uninstall
```

Затем удалите папку программы.
{% endtab %}
{% endtabs %}

Папка `C:\ProgramData\MikoPBX\LocalSTTWorker` с настройками, ключом, моделями и журналами при удалении сохраняется специально: при повторной установке модель не придется скачивать заново. Чтобы удалить все, удалите эту папку. Затем в MikoPBX на вкладке **Обработчики** удалите ключ доступа этого обработчика.

### TLS

Проверка сертификата по умолчанию включена: обработчик подключается только к MikoPBX с доверенным сертификатом. Если у станции самоподписанный сертификат или вы обращаетесь к ней по IP-адресу, ответьте **y** на вопрос о самоподписанном сертификате в `setup`. Трафик при этом все равно шифруется. Делайте это только в доверенной сети.

Чтобы обработчик доверял собственному центру сертификации, установите его корневой сертификат в хранилище **Доверенные корневые центры сертификации** компьютера.

### Диагностика проблем

Для проверки выполните `.\LocalSTTWorker.exe check`: команда проверяет файлы программы, настройки, ключ, совместимость с модулем, регистрацию и выбранную модель.

| Симптом                                                                      | Причина и решение                                                                                                                         |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `'setup' needs administrator rights`                                         | Командная строка запущена без прав администратора. Откройте ее через **Запуск от имени администратора**.                                  |
| Установщик MSI сообщает, что нет Visual C++                                  | Установите [среду выполнения Visual C++ 2015-2022 x64](https://aka.ms/vs/17/release/vc_redist.x64.exe) и запустите установщик снова.      |
| `status`: `not_configured`                                                   | Обработчик не настроен. Выполните `setup`.                                                                                                |
| `PBX rejected the worker API token` или `PBX refused the worker credentials` | Ключ удален, введен с ошибкой или уже привязан к другому обработчику. Создайте новый ключ на вкладке **Обработчики** и запустите `setup`. |
| `update ModuleLocalSpeechToText` или `status`: `waiting_for_windows_model`   | Версия модуля не поддерживает платформу Windows. Обновите **Локальную транскрибацию**.                                                    |
| `status`: `unsupported_model`                                                | Выбранная модель не поддерживается этой версией обработчика. Обновите обработчик или выберите другую модель.                              |
| Ошибка TLS при подключении                                                   | Сертификат MikoPBX недоверенный. Разрешите самоподписанный сертификат в `setup` или установите свой CA (см. раздел TLS).                  |
| Модель не скачивается                                                        | Нет доступа к huggingface.co. Откройте исходящий HTTPS для компьютера или прокси.                                                         |
| `The status is stale: the service is not running or is hung`                 | Служба не обновляла состояние больше 10 минут. Проверьте службу в `services.msc` и журнал обработчика.                                    |

Предупреждения и ошибки обработчика также записываются в журнал Windows **Приложение** с источником **MikoPBX Local STT Worker** (просмотр событий, `eventvwr.msc`).

### Данные и безопасность

Все данные хранятся в `C:\ProgramData\MikoPBX\LocalSTTWorker`. Доступ к папке есть только у SYSTEM и администраторов.

| Данные          | Где хранятся                                                      |
| --------------- | ----------------------------------------------------------------- |
| Программа       | `C:\Program Files\MikoPBX\LocalSTTWorker`                         |
| Настройки       | `settings.json`: адрес MikoPBX, UID и имя обработчика             |
| Ключ            | `secrets\worker-token.bin`, зашифрован DPAPI на уровне компьютера |
| Модели          | `Models\`, по папке на модель и версию                            |
| Журналы         | `Logs\worker-ГГГГММДД.log`, хранятся 14 дней                      |
| Состояние       | `status.json`, обновляется не реже раза в минуту                  |
| Временное аудио | `Temporary\`, удаляется после задания                             |

Обработчик подключается к MikoPBX только исходящими HTTPS-запросами, получает записи только назначенных ему заданий и не хранит их после обработки. Ключ обработчика дает доступ только к API модуля транскрибации и не передается в командной строке.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mikopbx.com/mikopbx/modules/miko/module-local-speech-to-text/windows-worker.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.