# whisper.cpp server: локальный HTTP API для транскрибации WAV

Источник: https://modelium.tech/zhurnal/whisper-cpp-server/

whisper.cpp содержит отдельный HTTP-сервер `whisper-server`: он принимает WAV как multipart-поле `file` на `/inference` и может вернуть JSON с текстом. Для русского примера нужен многоязычный GGML-вариант без `.en` и явный `language=ru`, поскольку настройки сервера по умолчанию ориентированы на английский. Привяжите сервер к loopback, проверьте `/health` и сопоставьте ответ со своей записью; работа модели и безопасность конфигурации Modelium не тестировались.

На 6 октября 2026 года проект whisper.cpp содержит самостоятельный `whisper-server` с HTTP-маршрутом `/inference`; это не тот же путь, что его `whisper-cli`, и не универсальный OpenAI-совместимый API. Ниже — одноузловой пример для доверенного Linux-хоста: локальный WAV, многоязычная модель, проверка JSON-ответа и границы сетевого доступа. Версия исходников — Git `60c0be6ac8fa71b1a2ae2dd938a31a34a508e774`; Modelium бинарник не собирал и аудио не обрабатывал. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

## Когда нужен сервер вместо CLI

Если приложение на том же компьютере должно многократно отправлять записи через HTTP, `whisper-server` принимает multipart-запросы с полем `file` и выводит текст распознавания в JSON. Для разового локального файла проще начать с [основного гайда по whisper.cpp](/zhurnal/whisper-cpp/) и CLI: это уменьшает сетевую поверхность. Маршрут сервера — `**/inference**`, а не `/v1/audio/transcriptions`; поле запроса — `file`, а не ссылка на облачное хранилище. [s1](#src-s1) [s2](#src-s2)

Предположения примера: права на обработку тестовой записи, доступ к исходному репозиторию и модели, компилятор C/C++ и CMake. Параметры скорости, рабочей памяти и пригодности конкретного CPU/GPU не выводятся из размера весов и не измерены Modelium. Код whisper.cpp опубликован с лицензией MIT, но разрешения для обработки записи и условия каждого набора весов проверяйте отдельно. [s3](#src-s3) [s4](#src-s4) [s6](#src-s6)

## Как собрать сервер и выбрать модель для русского языка

Зафиксируйте репозиторий на указанном commit и из его корня выполните `cmake -B build -DWHISPER_BUILD_SERVER=ON`, затем `cmake --build build -j --config Release`. Корневой README подтверждает стандартную сборку CMake; исходный CMake-файл включает опцию `WHISPER_BUILD_SERVER`, а серверный target создаёт `whisper-server` в `build/bin`. Закрепление commit важно: команды и параметры могут отличаться у следующего выпуска. GPU-бэкенд этим примером не включается; реальную аппаратную совместимость проверяйте на своей сборке. [s3](#src-s3) [s5](#src-s5) [s1](#src-s1)

Не оставляйте серверный вариант по умолчанию: код задаёт `models/ggml-base.en.bin` и `language=en`. Суффикс `.en` в списке моделей обозначает только английский, тогда как `base` многоязычная. Для русского возьмите `ggml-base.bin` и явно укажите `-m models/ggml-base.bin -l ru`; размер файла из каталога моделей не равен минимальному объёму оперативной памяти. [s2](#src-s2) [s4](#src-s4)

Скрипт проекта `sh ./models/download-ggml-model.sh base` получает готовый файл с Hugging Face по изменяемой ветке `main`; на закреплённом снимке HF `5359861c739e955e79d9a303bcbc70fb988958b1` файл `ggml-base.bin` существует. Для воспроизводимого набора скачайте `ggml-base.bin` именно с этой ревизии либо после выполнения скрипта сравните SHA-1 полученного файла с указанным в каталоге проекта `465707469ff3a37a2b9b8d8f89f2f99de7299dac` командой `sha1sum models/ggml-base.bin`; если хэш не совпал, не используйте файл в примере. SHA-1 здесь — контроль состава по версии каталога, не универсальная гарантия безопасности. Репозиторий модели и реализация сервера имеют разные ревизии. [s4](#src-s4) [s7](#src-s7) [s8](#src-s8)

## Как отправить WAV и проверить ответ API

Из корня репозитория на **доверенном локальном хосте** запустите `./build/bin/whisper-server -m models/ggml-base.bin -l ru --host 127.0.0.1 --port 8080`. По коду `127.0.0.1:8080` — значение по умолчанию, но явное указание помогает не перепутать стенд с конфигурацией, опубликованной на сетевом интерфейсе. В другом терминале проверьте `curl -i http://127.0.0.1:8080/health`: успешный ответ с `{"status":"ok"}` означает загруженную модель, **не** успешную транскрипцию. [s1](#src-s1) [s2](#src-s2)

Подготовьте собственный короткий WAV с русской речью. README показывает преобразование в PCM 16-bit, 16 кГц, mono: `ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le test-ru.wav`. Если запись уже соответствует этим условиям, повторная конвертация не нужна; не включайте серверный `--convert` без необходимости, поскольку тогда пример вызывает `ffmpeg` над загруженным файлом на сервере. Для чувствительного аудио не используйте случайный публичный файл или внешний конвертер. [s3](#src-s3) [s1](#src-s1) [s2](#src-s2)

Отправьте `curl -sS -f http://127.0.0.1:8080/inference -F file=@test-ru.wav -F language=ru -F response_format=json`. `curl -F` самостоятельно выставляет multipart boundary — вручную писать `Content-Type: multipart/form-data` без boundary не надо. Ответ на этой ревизии содержит поле `text`; сохраните исходный WAV, точный commit, модель и параметры, затем вручную сопоставьте имена, числа и пропущенные слова с аудио. HTTP 200 с непустым `text` — контроль прохождения API, но не оценка точности; если `text` пуст, это не подтверждение успешной расшифровки. [s1](#src-s1) [s2](#src-s2)

## Какие ошибки и границы доступа проверить

Если `/health` не даёт `ok`, проверьте путь `-m` и загрузку модели в журнале сервера; GET `/health` показывает `503` при загрузке. Если `/inference` даёт `400` и `no 'file' field`, проверьте имя multipart-поля; при `failed to read audio data` сверяйте кодек/заголовок WAV и повторите локальную конвертацию. При английском тексте вместо русского перепроверьте, что модель не `.en`, а язык установлен `ru`. Всё это — диагностический путь по исходникам, не воспроизведённый запуск. [s2](#src-s2) [s3](#src-s3) [s4](#src-s4)

**Не открывайте этот учебный сервер во внешнюю сеть.** Исходник добавляет заголовок `Access-Control-Allow-Origin: *`, принимает загружаемые файлы и имеет отдельный POST `/load`, который получает путь к локальному файлу модели. README прямо предупреждает не запускать сервер с административными правами и использовать sandbox. Loopback снижает доступность извне, но не защищает от других локальных процессов, браузерных запросов или ошибочного проксирования; для общего сервиса нужна отдельная архитектура изоляции, контроль разрешённых клиентов и тест с другого хоста. После проверки остановите процесс Ctrl+C, удалите тестовую запись по своей политике данных и проверьте, что порт закрыт. [s1](#src-s1) [s2](#src-s2)

Следующий шаг — [проверка локальной транскрипции на своих записях](/zhurnal/raspoznavanie-rechi-lokalno/): сравните результат с исходником, а не только с кодом HTTP. Для выбора модели и языка смотрите [варианты Whisper](/zhurnal/whisper-modeli/); в бизнес-процессе решение о хранении аудио и передаче текста принимайте отдельно. [s4](#src-s4) [s2](#src-s2)

## Источники

1. [whisper.cpp: README серверного примера и предупреждение о sandbox](https://github.com/ggml-org/whisper.cpp/blob/60c0be6ac8fa71b1a2ae2dd938a31a34a508e774/examples/server/README.md) — получено 2026-10-06
2. [whisper.cpp: исходный код HTTP-сервера, маршруты, поля запроса, CORS](https://github.com/ggml-org/whisper.cpp/blob/60c0be6ac8fa71b1a2ae2dd938a31a34a508e774/examples/server/server.cpp) — получено 2026-10-06
3. [whisper.cpp: корневой README, сборка и конвертация WAV](https://github.com/ggml-org/whisper.cpp/blob/60c0be6ac8fa71b1a2ae2dd938a31a34a508e774/README.md) — получено 2026-10-06
4. [whisper.cpp: модели GGML, многоязычность и SHA-1 base](https://github.com/ggml-org/whisper.cpp/blob/60c0be6ac8fa71b1a2ae2dd938a31a34a508e774/models/README.md) — получено 2026-10-06
5. [whisper.cpp: опция сборки WHISPER_BUILD_SERVER](https://github.com/ggml-org/whisper.cpp/blob/60c0be6ac8fa71b1a2ae2dd938a31a34a508e774/CMakeLists.txt) — получено 2026-10-06
6. [whisper.cpp: лицензия исходного кода MIT](https://github.com/ggml-org/whisper.cpp/blob/60c0be6ac8fa71b1a2ae2dd938a31a34a508e774/LICENSE) — получено 2026-10-06
7. [Hugging Face API: ggml-base.bin на закреплённой ревизии](https://huggingface.co/api/models/ggerganov/whisper.cpp/revision/5359861c739e955e79d9a303bcbc70fb988958b1) — получено 2026-10-06
8. [whisper.cpp: скрипт загрузки готовых GGML-моделей](https://github.com/ggml-org/whisper.cpp/blob/60c0be6ac8fa71b1a2ae2dd938a31a34a508e774/models/download-ggml-model.sh) — получено 2026-10-06