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