GigaSTT — книга рецептов
Сценарные рецепты для gigastt — локального сервера русской речи-в-текст на базе GigaAM v3. Каждая глава устроена одинаково: сценарий → предпосылки → рецепт → проверка результата → частые ошибки → ссылки.
Это поваренная книга, а не справочник. Канонические справочники остаются в
docs/ — книга ссылается на них, а не дублирует.
Документировано против gigastt 2.18.x. В install-скриптах предпочитайте
резолв latest-тега (gh api …/releases/latest), а не устаревшие миноры.
Я хочу…
| Цель | Время | Глава |
|---|---|---|
| Первый транскрипт на этой машине | ~5–15 мин | Начало работы |
| Пакет папки / watch / async jobs | ~15–30 мин | CLI и пакетная обработка |
| АТС / Opus / raw telephony; стерео-спикеры | ~20 мин | Телефония и VoIP |
| Live-субтитры или voice-bot по WebSocket | ~30 мин | Стриминг по WebSocket |
| macOS / Electron / mobile приложение | ~30–60 мин | Десктоп и встраивание |
| Прод с метриками, апгрейдами, hot-reload модели | ~45 мин | Развёртывание и эксплуатация |
| Выбрать голову / INT8 / GPU / pool / punct / hotwords | ~20 мин | Модели и бэкенды |
| Метки спикеров на mono-встречах | (в гл. 3) | Телефония — диаризация |
| Расшифровать HTTP/WS код ошибки | ~2 мин | Приложение A — Коды ошибок |
| Air-gapped / offline | ~30 мин | Приложение B — Offline-чеклист |
| Установка на Windows | ~10 мин | Начало работы — Windows |
Главы
- Начало работы — установка (macOS/Linux/Windows/Docker/air-gap), первая транскрибация. Новичок · ~5–15 мин
- CLI и пакетная обработка — CLI, batch и watch. Новичок · ~15–30 мин
- Телефония и VoIP — G.711/G.722/Opus, АТС, stereo split и диаризация. Средний · ~20 мин
- Стриминг по WebSocket — живые partials (буферизованный RNN-T; VAD-эндпоинтинг, session caps). Средний · ~30 мин
- Десктоп и встраивание — Swift/SPM, sidecar, Electron, UniFFI. Средний · ~30–60 мин
- Развёртывание и эксплуатация — прод, мониторинг, апгрейды, admin reload. Ops · ~45 мин
- Модели и бэкенды — головы, квантование, EP, пунктуация/ITN, hotwords. Средний · ~20 мин
Приложения
- A — Коды ошибок — jump table REST/WS/close
- B — Offline-чеклист — air-gapped операторский список
Английская версия — каноническая; эта книга зеркалирует её глава в главу.
Какой API?
| У вас | Берите | Не берите |
|---|---|---|
| Файл на диске, важен WER | REST /v1/transcribe или CLI transcribe — 01, 02 | Живой WebSocket (WER хуже на ~11–15 п.п.) |
| Папка / drop box | transcribe-batch / watch — 02 | transcribe в цикле |
| Длинный файл, нельзя ждать | /v1/jobs (--enable-jobs) — 02 | Один блокирующий REST без плана по таймауту |
| Микрофон / нога звонка, partials во время речи | WebSocket /v1/ws — 04 | REST; не цитируйте 1000-рядную таблицу WER для этого пути |
| Клиент под OpenAI | /v1/audio/transcriptions — docs/api.md | Свой WS, если клиент умеет только multipart |
| Приложение in-process (без сервера) | Биндинги — 05 | serve, если не нужна изоляция падений |
Остальная документация
Полная карта справочников (API, CLI, бенчмарки, runbook, бэкенды) — docs/README.md. Книга ссылается наружу и не копирует эти страницы.
Правила для контрибьюторов
- Книга содержит рецепты;
docs/api.md,docs/cli.mdи схемы AsyncAPI/OpenAPI остаются каноническими справочниками. Ссылайтесь на них — не копируйте содержимое. - Каждая команда и пример в главе должны быть проверены перед мерджем.
- Внутри книги (глава ↔ глава, глава ↔ intro) — только относительные ссылки
на
.md, они работают и на GitHub, и в собранной книге. Ссылки из книги на файлы репозитория (docs/,crates/, …) — только абсолютные GitHub-URL, относительные на опубликованном сайте ведут в 404. Никакой mdBook-специфичной шаблонизации. - Новые главы следуют структуре
_template.md. - Английская версия — каноническая. Русская книга (
docs/workbook/ru/) зеркалирует её с идентичными именами файлов; обе версии правятся в одном PR. - Когда фича меняет документируемую поверхность (CLI-флаги, коды ошибок,
аудиоформаты), обновляйте главу, оглавление книги
SUMMARY.mdи канонические справочники в том же PR — и держите docs-drift gate зелёным:python3 scripts/check-docs-drift.py(пока advisory в CI; сверяет с кодом CLI-флаги, коды ошибок WS, аудиоформаты, оглавления mdBook, паритет числа заголовков EN/RU, относительные ссылки, пути OpenAPI, версии в SECURITY.md, пины крейтов, актуальность версии и обязательные рецепты воркбука). Свежесть перевода — обязанность ревью: гейт считает только строки^#{1,6}(markdown-заголовки и#-комментарии в начале строки внутри блоков кода). Этот гейт расширять не нужно. Перед мерджем для каждой изменённой главы прочитайте другую локаль и проверьте:- те же заголовки, блоки Verify, флаги, env, пути и коды ошибок
- те же измеренные цифры (RAM, RTF, размеры) — не выдумывайте значения
- то же число
#-комментариев в начале строки (иначе гейт паритета падает) - нет пинов предыдущего минора (резолв latest через
TAG/VER, либоvX.Y.0только как пример в комментарии)