go-whisper-api/README.md

go-whisper-api

HTTP-сервер распознавания речи на базе whisper.cpp: совместимость с SPR (/spr/*) и OpenAI Whisper API (/v1/*) для Open WebUI и других клиентов.

Модели Whisper (ggml)

См. каталог моделей на Hugging Face.

make download-model
# или вручную:
curl -LJ https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin \
  --output models/ggml-small.bin

Веса STT: *.bin в корне api.models_dir (список — GET /spr/models). Подкаталоги models/vad/, models/punctuation/ и т.п. в список моделей не входят.

Конфигурация

Шаблон в репозитории — config.yaml.example. Рабочий файл создайте локально (он в .gitignore):

cp config.yaml.example config.yaml

Если --config не указан и в текущем каталоге есть config.yaml, он подгружается автоматически.

Промежуточные файлы (загрузки, конвертация) — только в /tmp, удаляются после обработки. Форматы wav, mp3, flac, ogg, m4a, mp4, aac декодируются на чистом Go (без ffmpeg).

Запуск

go-whisper-api serve --config config.yaml
# или с флагами (перекрывают YAML):
go-whisper-api --models-dir ./models --addr :8080

Docker:

docker run -p 8080:8080 \
  -v $PWD/models:/app/models \
  -v $PWD/config.yaml:/app/config.yaml \
  ghcr.io/appleboy/go-whisper-api:latest \
  serve --config /app/config.yaml

Swagger UI: http://localhost:8080/

VAD (детекция речи)

make download-vad-model

api:
  models_dir: ./models
  vad:
    enabled: true
    model: ggml-silero-v6.2.0.bin

Полезно на длинных записях с тишиной или музыкой в начале/конце.

Пунктуация

Уровень	Параметр	Эффект
Мастер	punctuation.enabled: false	Пунктуация отключена
API по умолчанию	api.default_punctuation: true	Если нет ?punctuation=
На запрос	?punctuation=1 / ?punctuation=0	Только при enabled: true

Движки: heuristic, xlm, sherpa, sherpa-online, http, off.

curl -X POST "http://localhost:8080/spr/stt/ggml-small?punctuation=1" -F "wav=@audio.wav"

Сборка XLM: make download-xlm-punctuation-model && make build-xlm. Продакшен: make package-runtime-xlm — в git не коммитятся lib/*.so (см. .gitignore).

Фильтр артефактов: api.garbage (по умолчанию *выбая*), отключить: garbage: [].

HTTP API

• SPR (/spr/*) — очередь, waveform, импорт/экспорт моделей
• OpenAI (/v1/*) — синхронный STT

Пример SPR:

curl -X POST "http://localhost:8080/spr/stt/ggml-small?async=0" -F "wav=@audio.wav"

По умолчанию STT асинхронный: POST /spr/stt/{id} → taskID, опрос GET /spr/queue/{taskID}, результат GET /spr/result/{taskID}. Кэш: ./cache/waiting/ и ./cache/ready/.

Язык по умолчанию — ru (?language=en, ?language=auto).

Endpoint	Метод	Описание
/spr/models	GET	Список моделей
/spr/stt/{id}	POST	Транскрипция
/spr/result/{taskID}	GET	Результат
/spr/queue	GET	Все задачи
/spr/queue/{taskID}	GET / DELETE	Статус / удаление
/v1/audio/transcriptions	POST	OpenAI-совместимая транскрипция
/v1/models	GET	Список моделей

Open WebUI

Параметр	Значение
Engine	OpenAI
API Base URL	http://<host>:6183/v1
API Key	любая непустая строка
STT Model	whisper-1 (см. api.default_model в config)

api:
  default_model: ggml-large-v3-turbo

CI/CD

Workflows в .gitea/workflows/ (lint.yml, docker.yml). Секрет GITEA_TOKEN с write:package для push образов.

docker build -f docker/Dockerfile.ci -t go-whisper-api .