admin
b5c083e06f
Some checks failed
CodeQL / Analyze (go) (push) Successful in 6m28s
Docker Image / build-docker (push) Failing after 13m26s
Lint and Testing / lint (push) Successful in 11m17s
Lint and Testing / test (push) Successful in 11m17s
Lint and Testing / golangci (push) Successful in 2m40s
130 lines
4.6 KiB
Markdown
130 lines
4.6 KiB
Markdown
# go-whisper-api
|
||
|
||
HTTP-сервер распознавания речи на базе [whisper.cpp](https://github.com/ggerganov/whisper.cpp): совместимость с **SPR** (`/spr/*`) и **OpenAI Whisper API** (`/v1/*`) для Open WebUI и других клиентов.
|
||
|
||
## Модели Whisper (ggml)
|
||
|
||
См. [каталог моделей на Hugging Face](https://huggingface.co/ggerganov/whisper.cpp/tree/main).
|
||
|
||
```sh
|
||
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`):
|
||
|
||
```sh
|
||
cp config.yaml.example config.yaml
|
||
```
|
||
|
||
Если `--config` не указан и в текущем каталоге есть `config.yaml`, он подгружается автоматически.
|
||
|
||
Промежуточные файлы (загрузки, конвертация) — только в `/tmp`, удаляются после обработки. Форматы **wav, mp3, flac, ogg, m4a, mp4, aac** декодируются на чистом Go (без ffmpeg).
|
||
|
||
## Запуск
|
||
|
||
```sh
|
||
go-whisper-api serve --config config.yaml
|
||
# или с флагами (перекрывают YAML):
|
||
go-whisper-api --models-dir ./models --addr :8080
|
||
```
|
||
|
||
Docker:
|
||
|
||
```sh
|
||
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/](http://localhost:8080/)
|
||
|
||
## VAD (детекция речи)
|
||
|
||
```sh
|
||
make download-vad-model
|
||
```
|
||
|
||
```yaml
|
||
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`.
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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) |
|
||
|
||
```yaml
|
||
api:
|
||
default_model: ggml-large-v3-turbo
|
||
```
|
||
|
||
## CI/CD
|
||
|
||
Workflows в `.gitea/workflows/` (`lint.yml`, `docker.yml`). Секрет `GITEA_TOKEN` с `write:package` для push образов.
|
||
|
||
```sh
|
||
docker build -f docker/Dockerfile.ci -t go-whisper-api .
|
||
```
|