fix(transcription): empty whisperPrompt default to stop English bias (#47 )

## Что сделано

- `DEFAULTS.whisperPrompt` изменён с 107-символьного английского списка
терминов на пустую строку (`src/config.ts:8`). Английский промпт уводил
русский аудио в английский (особенно на turbo) — нарушает документацию
Groq: «Use the same language as the language of the audio file».
- `tests/config.test.ts` — 2 устаревших теста (`non-empty
whisperPrompt`, `under 120 characters`) заменены на 1: `should have
empty whisperPrompt by default`.
- Version bump 1.0.4 → 1.0.5 в `vite.config.ts:11` и `package.json:3`.
- ADR-0007 (`docs/decisions/0007-pr-46-empty-whisper-prompt.md`) —
фиксирует решение, контекст (PR #43 + баг), последствия (`buildFormData`
falsy-check), альтернативы (двуязычный промпт, смена модели — обе
отвергнуты).
- README — секция troubleshooting «Wrong Language (English instead of
Russian)» добавлена в EN и RU секции после температурного блока.
Инструкция очистить Whisper Prompt через меню Tampermonkey.

## Почему

PR #43 добавил английский biasing-промпт для технических терминов. На
практике английский промпт + русский аудио = модель возвращает
английский текст, перебивая явный `language=ru`. Пользователь подтвердил
баг на turbo. Параметр `prompt` Whisper — это seed-контекст декодера,
модель стремится продолжить его язык. Пустой default = чистый
auto-detect без biasing. Поле и menu command остаются для юзеров с
узкопрофильной терминологией.

## Watch out

- **Обратная совместимость**: существующие юзеры со старым
107-символьным значением в `GM_getValue("whisperPrompt")` сохраняют его
— новый default применяется только к свежим установкам и к тем, кто
очистил поле через `Set Whisper Prompt`. Миграции нет намеренно (не
ломаем сохранённые настройки).
- `buildFormData` использует falsy-check `if (config.whisperPrompt)` —
пустая строка не отправляет поле `prompt` в Groq API вообще.
- `transcribe.test.ts` использует mock `whisperPrompt: "Software
development discussion."` — валидный mock для тестирования
prompt-передачи, НЕ тронут (не путать с DEFAULTS).
- `DEFAULTS.model` (`whisper-large-v3`), `DEFAULTS.language` (`""`),
`DEFAULTS.temperature` (`0`), `DEFAULTS.endpoint` — не менялись. Смена
модели на turbo была альтернативой, отвергнута (v3 лучше для русского,
баг в промпте не в модели).
- Touchpoints ровно 7: `src/config.ts`, `tests/config.test.ts`,
`vite.config.ts`, `package.json`, `docs/decisions/0007-*.md` (новый),
`README.md` (2 вставки EN+RU). `src/transcribe.ts` и остальные src-файлы
не тронуты.

## Pending

- CI на push-ветке (vitest, biome, tsc, knip) — все зелёные локально
(55/55 tests, 22 файла biome-clean, tsc чист, knip чист).
- После merge — ADR-0007 ссылается на PR #46 (номер уже известен из
issue).

Closes #46

---------

Co-authored-by: opencode-agent <agent@opencode.local>

2026-08-04 15:13:01 +03:00

4.4 KiB

Raw Blame History

ADR 0007: Empty whisperPrompt default (PR #46)

Date: 2026-08-04
PR: 46
Issue: #46

Статус

Accepted.

Контекст

PR #43 добавил DEFAULTS.whisperPrompt — 107-символьный английский список терминов (opencode, voice, dictation, transcribe, command, terminal, commit, branch, pull, push, merge, issue, prompt). Целью было biasing-смещение модели в сторону технической терминологии userscript-а.

Документация Groq для параметра prompt (Whisper API) явно указывает: «Use the same language as the language of the audio file». Параметр prompt — это не системный промпт, а seed-контекст для декодера: модель стремится продолжить стиль и язык промпта в транскрипции.

Практический баг: английский промпт + русский аудио = модель уводит транскрипт в английский. Особенно заметно на whisper-large-v3-turbo (turbo более чувствителен к prompt biasing). Пользователь подтвердил: language=ru + turbo всё равно возвращает английский текст, потому что английский промпт перебивает явный language параметр.

Решение

DEFAULTS.whisperPrompt = "" (пустая строка).

Поле whisperPrompt в AppConfig остаётся. Menu command Set Whisper Prompt (registerMenuCommands) остаётся — пользователи с узкопрофильной терминологией (медицина, право, конкретный стек) могут задать свой промпт на нужном языке. Меняется только default: пустая строка вместо английского biasing-промпта.

Последствия

buildFormData в src/transcribe.ts использует falsy-check if (config.whisperPrompt) — пустая строка не отправляет поле prompt в Groq API вообще. Модель работает в чистом auto-detect режиме без prompt biasing.
Обратная совместимость: существующие юзеры, установившие скрипт в версии 1.0.4 (PR #43) и не менявшие whisperPrompt через меню, имеют в GM_getValue("whisperPrompt") старое 107-символьное значение — оно сохранится и продолжит отправляться. Новый default применяется только к свежим установкам и к юзерам, очистившим поле через Set Whisper Prompt.
README обновлён секцией troubleshooting «Wrong Language» (EN+RU) — инструкция очистить Whisper Prompt через меню.
Версия bumped 1.0.4 → 1.0.5 (vite.config.ts + package.json).

Альтернативы

1. Двуязычный промпт (английский + русский термины)

Плюс: biasing в обе стороны.
Минус: усложнение. Промпт нужно поддерживать при добавлении новых языков (сейчас language поддерживает ru/en/auto). При auto модель может растеряться от двуязычного промпта. Отвергнуто.

2. Смена модели на turbo по умолчанию

Плюс: turbo быстрее.
Минус: баг был в промпте, не в модели. whisper-large-v3 лучше для русского (точность выше, turbo оптимизирован под английский). Смена модели не решила бы проблему английского biasing-а. Отвергнуто.

Источники

src/config.ts — DEFAULTS.whisperPrompt до/после
src/transcribe.ts — buildFormData falsy-check if (config.whisperPrompt)
Groq Whisper API docs — prompt parameter: «Use the same language as the language of the audio file»
PR #43 — добавление DEFAULTS.whisperPrompt (107 символов)
Issue: #46

4.4 KiB Raw Blame History Unescape Escape