From eaa797b1908568799fa2d1a28238697415ab038d Mon Sep 17 00:00:00 2001 From: Mik Wiseman Date: Tue, 20 Oct 2026 09:27:48 +0300 Subject: [PATCH] parakeet: honor run_params.vocabulary with phrase boosting Parakeet has no prompt slot, so it ignored transcribe_run_params::vocabulary with a WARN. The TDT and RNN-T greedy decoders now take the terms as phrase boosting over an Aho-Corasick automaton of token ids. The model's own argmax decides between blank and a token; only when it emits a token does the vocabulary re-rank the non-blank tokens, so biasing changes which word is written and never whether one is. A term earns no bonus for its first piece, a broken match gives back what it earned, and a completed term keeps its bonus. Token confidences stay the model's own, and with no terms the decoder never calls into the automaton, so output is bit-exact. The bonus defaults to 8.0 and can be overridden with TRANSCRIBE_VOCABULARY_BOOST. Streaming and CTC heads ignore terms for now. Co-Authored-By: Claude Opus 5.5 --- docs/environment-variables.md | 1 + docs/prompting.md | 18 +++++ src/CMakeLists.txt | 1 + src/arch/parakeet/decoder.cpp | 70 ++++++++++++---- src/arch/parakeet/decoder.h | 31 +++++--- src/arch/parakeet/model.cpp | 62 ++++++++++++++- src/arch/parakeet/parakeet.h | 3 + src/transcribe-phrase-boost.cpp | 137 ++++++++++++++++++++++++++++++++ src/transcribe-phrase-boost.h | 70 ++++++++++++++++ tests/CMakeLists.txt | 14 ++++ tests/phrase_boost_unit.cpp | 85 ++++++++++++++++++++ 11 files changed, 464 insertions(+), 28 deletions(-) create mode 100644 src/transcribe-phrase-boost.cpp create mode 100644 src/transcribe-phrase-boost.h create mode 100644 tests/phrase_boost_unit.cpp diff --git a/docs/environment-variables.md b/docs/environment-variables.md index 4bb0336da..ef1d083ae 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -31,6 +31,7 @@ of tests. | `TRANSCRIBE_CONV_DIRECT_DW` / `TRANSCRIBE_CONV_NO_DIRECT_DW` | Force the depthwise-conv dispatch to the direct `conv_2d_dw` path / the im2col path, overriding the per-family backend default. | | `TRANSCRIBE_CONV_DIRECT_PW` / `TRANSCRIBE_CONV_NO_DIRECT_PW` | Force the pointwise-conv dispatch to direct `mul_mat` / im2col, overriding the backend default. | | `TRANSCRIBE_NO_REPETITION_GUARD` | Turn off the stop for greedy decodes that start repeating themselves, and the trim of a repeating tail at a budget stop (see [`input-limits.md`](input-limits.md)). For byte-exact reference parity; a looping decode then runs to its budget and keeps its repeats. Read once per process. | +| `TRANSCRIBE_VOCABULARY_BOOST=` | Logit bonus per matched vocabulary token for the parakeet transducer decoders (default 8.0; see [`prompting.md`](prompting.md)). For tuning against a term-recall set; `0` keeps the automaton but adds nothing. | | `TRANSCRIBE_DUMP_DIR=` | Enable the per-stage tensor dumper; writes `.f32` + `.json` per dumped tensor into ``. The basis for the numerical-comparison harness (`scripts/compare_tensors.py`). | | `TRANSCRIBE_PERF_DEBUG` | Print a per-stage timing breakdown to stderr (DEBUG log) on the families that profile (`cohere`, `granite`, `canary`, `canary_qwen`, `moonshine`, `moonshine_streaming`, `moss`, `qwen3_asr`, `whisper`). For whisper, a value containing `cpu` or `all` additionally prints the CPU sub-section breakdown. | | `TRANSCRIBE_VOXTRAL_REALTIME_STREAM_TIMING` | Print a per-component streaming wall-time breakdown at stream finalize (voxtral_realtime). | diff --git a/docs/prompting.md b/docs/prompting.md index d908e5c2d..91f4d3e46 100644 --- a/docs/prompting.md +++ b/docs/prompting.md @@ -20,10 +20,28 @@ Probe `transcribe_model_supports()` for the matching feature bit. | Canary 180m-flash / 1b-flash / 1b-v2 | | | | yes | | Fun-ASR-Nano | yes | | | | | MOSS-Transcribe-Diarize | yes | | | | +| Parakeet (TDT and RNN-T heads) | yes | | | | Per-model formats and restrictions are in each model doc's **Prompting:** note under [`models/`](models/). +## Parakeet vocabulary + +Parakeet has no prompt slot, so its transducer decoders take vocabulary terms +as phrase boosting: each term is tokenized the way the model writes it, starting +at a word boundary, and the terms form an Aho-Corasick automaton over token +ids. The model alone decides between blank and a token on every greedy step. +When it emits a token, the vocabulary re-ranks the non-blank tokens. Once the +model has begun a term on its own, each further piece that extends the match +earns a logit bonus (8.0 by default, chosen on a held-out term set), a token +that breaks the match gives back what the unfinished match earned, and a +completed term keeps its bonus. Biasing therefore changes which word is +written, never whether one is, so it cannot invent speech on silence. The +reported token confidences stay the model's own, and with no terms decoding is +bit-exact. Terms with characters the tokenizer cannot write are skipped with a +WARN. Offline runs and batches take terms; streaming ignores them, and CTC +heads do not take them yet. + ## Limits - Over the prompt budget, `vocabulary` drops terms from the end of the list and diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 68606dcc8..9c1bcaf2d 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -24,6 +24,7 @@ add_library(transcribe transcribe-model.cpp transcribe-tokenizer.cpp transcribe-prompting.cpp + transcribe-phrase-boost.cpp transcribe-unicode.cpp transcribe-unicode-data.cpp transcribe-debug.cpp diff --git a/src/arch/parakeet/decoder.cpp b/src/arch/parakeet/decoder.cpp index 52defc38f..afd917346 100644 --- a/src/arch/parakeet/decoder.cpp +++ b/src/arch/parakeet/decoder.cpp @@ -13,6 +13,8 @@ #include "decoder.h" +#include + #include "parakeet.h" #include "transcribe-batch-util.h" #include "transcribe-debug.h" @@ -966,6 +968,31 @@ int argmax_range(const float * data, int n) { return best_i; } +// Token argmax, biased toward the vocabulary when there is one. +// +// The model alone decides between blank and a token: only when its own +// argmax emits something does the vocabulary re-rank the non-blank tokens. +// Biasing can then change which word is written but never whether one is, +// so it cannot invent speech on silence or noise. The model's own logits are +// left untouched for the confidence that follows. +static int biased_argmax(const float * token_logits, + int n_token_cls, + int blank_id, + const transcribe::PhraseBoost * boost, + int boost_state, + std::vector & scratch) { + const int unbiased = argmax_range(token_logits, n_token_cls); + if (boost == nullptr || boost->empty() || unbiased == blank_id) { + return unbiased; + } + scratch.assign(token_logits, token_logits + n_token_cls); + boost->apply(boost_state, scratch.data(), n_token_cls, blank_id); + if (blank_id >= 0 && blank_id < n_token_cls) { + scratch[static_cast(blank_id)] = -std::numeric_limits::infinity(); + } + return argmax_range(scratch.data(), n_token_cls); +} + // Entropy-based confidence over a token-logit slice. Mirrors the // reference ParakeetTDT.decode_greedy path: // @@ -1015,12 +1042,13 @@ float token_confidence(const float * token_logits, int n_token_classes, std::vec // Greedy decode driver // --------------------------------------------------------------------------- -transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, - const float * enc_out, - int T_enc, - int d_enc, - int n_threads, - std::vector & out_tokens) { +transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, + const float * enc_out, + int T_enc, + int d_enc, + int n_threads, + std::vector & out_tokens, + const transcribe::PhraseBoost * boost) { if (enc_out == nullptr || T_enc <= 0 || d_enc <= 0) { return TRANSCRIBE_ERR_INVALID_ARG; } @@ -1097,6 +1125,10 @@ transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, // the unconditional path. bool predictor_dirty = true; + // Vocabulary biasing state; untouched when no terms were given. + int boost_state = transcribe::PhraseBoost::root; + std::vector boosted; + // See ParakeetHParams::tdt_global_symbol_budget. const bool global_budget = w.tdt_global_symbol_budget; int64_t steps_remaining = static_cast(w.tdt_max_symbols) * T_enc; @@ -1131,7 +1163,7 @@ transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, const float * token_logits = logits.data(); const float * duration_logits = logits.data() + n_token_cls; - const int pred_token = argmax_range(token_logits, n_token_cls); + const int pred_token = biased_argmax(token_logits, n_token_cls, blank_id, boost, boost_state, boosted); const int decision = argmax_range(duration_logits, n_dur); const int duration = w.tdt_durations[static_cast(decision)]; @@ -1172,6 +1204,9 @@ transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, last_token = pred_token; std::swap(state, next_state); // commit predictor_dirty = true; + if (boost != nullptr) { + boost_state = boost->next(boost_state, pred_token); + } } if (global_budget) { @@ -1249,12 +1284,13 @@ transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, // duration). Matches the reference dump points (`dec.embed.0`, // `dec.lstm.{layer}.{h,c}.0`, `dec.joint.0`) emitted on iter 1. -transcribe_status decode_rnnt_greedy(const HostDecoderWeights & w, - const float * enc_out, - int T_enc, - int d_enc, - int n_threads, - std::vector & out_tokens) { +transcribe_status decode_rnnt_greedy(const HostDecoderWeights & w, + const float * enc_out, + int T_enc, + int d_enc, + int n_threads, + std::vector & out_tokens, + const transcribe::PhraseBoost * boost) { if (enc_out == nullptr || T_enc <= 0 || d_enc <= 0) { return TRANSCRIBE_ERR_INVALID_ARG; } @@ -1316,6 +1352,9 @@ transcribe_status decode_rnnt_greedy(const HostDecoderWeights & w, // RNN-T iters/token ratio. bool predictor_dirty = true; + int boost_state = transcribe::PhraseBoost::root; + std::vector boosted; + while (step < T_enc && iter < max_iters) { ++iter; @@ -1342,7 +1381,7 @@ transcribe_status decode_rnnt_greedy(const HostDecoderWeights & w, // RNNT joint output is just `n_token_cls` floats (no duration extras). const float * token_logits = logits.data(); - const int pred_token = argmax_range(token_logits, n_token_cls); + const int pred_token = biased_argmax(token_logits, n_token_cls, blank_id, boost, boost_state, boosted); if (iter == 1 && transcribe::debug::enabled()) { const long long s_h = H; @@ -1377,6 +1416,9 @@ transcribe_status decode_rnnt_greedy(const HostDecoderWeights & w, last_token = pred_token; std::swap(state, next_state); predictor_dirty = true; + if (boost != nullptr) { + boost_state = boost->next(boost_state, pred_token); + } new_symbols += 1; if (w.tdt_max_symbols > 0 && new_symbols >= w.tdt_max_symbols) { diff --git a/src/arch/parakeet/decoder.h b/src/arch/parakeet/decoder.h index e7cb70a55..ff2948d6c 100644 --- a/src/arch/parakeet/decoder.h +++ b/src/arch/parakeet/decoder.h @@ -30,6 +30,7 @@ #include "ggml-backend.h" #include "ggml.h" #include "transcribe.h" +#include "transcribe-phrase-boost.h" #include #include @@ -218,24 +219,30 @@ struct TdtToken { // // Returns TRANSCRIBE_OK on success; cannot fail except via invalid args // (validated by the family driver before this is called). -transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, - const float * enc_out, - int T_enc, - int d_enc, - int n_threads, - std::vector & out_tokens); +// +// `boost`, when non-null and non-empty, biases the token argmax toward the +// caller's vocabulary terms (transcribe_run_params::vocabulary); see +// transcribe-phrase-boost.h. Token confidences stay the model's own. +transcribe_status decode_tdt_greedy(const HostDecoderWeights & w, + const float * enc_out, + int T_enc, + int d_enc, + int n_threads, + std::vector & out_tokens, + const transcribe::PhraseBoost * boost = nullptr); // Run RNNT greedy decode end-to-end. Same predictor + joint code as TDT, // but the joint emits `vocab+1` logits (no duration extras) and the step // rule is "blank → advance one frame, non-blank → emit + stay, capped by // tdt_max_symbols". Per-emit duration_frames is fixed at 1. Same I/O // contract and TdtToken result type as decode_tdt_greedy. -transcribe_status decode_rnnt_greedy(const HostDecoderWeights & w, - const float * enc_out, - int T_enc, - int d_enc, - int n_threads, - std::vector & out_tokens); +transcribe_status decode_rnnt_greedy(const HostDecoderWeights & w, + const float * enc_out, + int T_enc, + int d_enc, + int n_threads, + std::vector & out_tokens, + const transcribe::PhraseBoost * boost = nullptr); // Streaming variant of RNN-T greedy decode. Consumes T_enc_new encoder // frames (the chunk just produced) and APPENDS emitted tokens to diff --git a/src/arch/parakeet/model.cpp b/src/arch/parakeet/model.cpp index a877781ea..ddf8e622c 100644 --- a/src/arch/parakeet/model.cpp +++ b/src/arch/parakeet/model.cpp @@ -28,6 +28,7 @@ #include "transcribe-log.h" #include "transcribe-mel.h" #include "transcribe-meta.h" +#include "transcribe-prompting.h" #include "transcribe/parakeet.h" #include "weights.h" @@ -40,6 +41,7 @@ #include #include #include +#include #include #include #include @@ -587,6 +589,10 @@ transcribe_status load(Loader & loader, const transcribe_model_load_params * par return st; } + // Vocabulary terms bias the greedy transducer decoders (TDT and RNN-T); + // CTC heads do not take them yet. + transcribe::set_feature(m.get(), TRANSCRIBE_FEATURE_VOCABULARY, m->host_decoder.head_kind != HostHeadKind::CTC); + // Multitalker bundle post-load: fuse the diarizer conformer's BN (needs // uploaded data), build its ceil-framed mel frontend, and publish the // DIARIZATION capability — for a bundle it is a property of the file. @@ -789,6 +795,56 @@ static double parakeet_ms_per_enc_frame(const ParakeetHParams & hp) { static_cast(hp.fe_sample_rate); } +// Logit bonus per matched vocabulary token, in natural-log units. Chosen on +// the dev half of a term-recall set and checked against general WER; see +// docs/prompting.md. TRANSCRIBE_VOCABULARY_BOOST overrides it for research. +constexpr float kVocabularyBoost = 8.0f; + +static float vocabulary_boost_score() { + if (const char * v = transcribe::env::str("TRANSCRIBE_VOCABULARY_BOOST")) { + char * end = nullptr; + const float value = std::strtof(v, &end); + if (end != v && value >= 0.0f) { + return value; + } + } + return kVocabularyBoost; +} + +// The phrase-boost automaton for this run's vocabulary, or nullptr when the +// run has none. Terms are tokenized as the model writes them (with the word +// boundary marker), so a term matches only from the start of a word. +static const transcribe::PhraseBoost * vocabulary_boost(ParakeetSession * pc, + const ParakeetModel * pm, + const transcribe_run_params * params) { + std::vector terms = transcribe::prompting::terms(params); + if (terms.empty() || pm->host_decoder.head_kind == HostHeadKind::CTC) { + return nullptr; + } + if (terms != pc->boost_terms || pc->boost.empty()) { + std::vector> phrases; + for (const std::string & term : terms) { + std::vector ids; + if (pm->tok.encode_sentencepiece_bpe(term, ids, 0, -1, /*remove_extra_whitespaces=*/true) != TRANSCRIBE_OK) { + log_msg(TRANSCRIBE_LOG_LEVEL_WARN, "parakeet: this tokenizer cannot encode vocabulary terms; ignoring them"); + return nullptr; + } + bool unknown = false; + for (const int32_t id : ids) { + unknown = unknown || pm->tok.is_unknown(id); + } + if (unknown) { + log_msg(TRANSCRIBE_LOG_LEVEL_WARN, "parakeet: a vocabulary term has characters the model cannot write; skipped"); + continue; + } + phrases.push_back(std::move(ids)); + } + pc->boost.build(phrases, vocabulary_boost_score()); + pc->boost_terms = std::move(terms); + } + return pc->boost.empty() ? nullptr : &pc->boost; +} + // Host-side TDT/RNNT/CTC decode + public result-hierarchy build for one // utterance's encoder output. `enc` is the row-major [T_enc, d_enc] // activation for ONE utterance; utt_index >= 0 tags the per-utterance @@ -827,10 +883,12 @@ static transcribe_status decode_and_populate(ParakeetSession * pc, transcribe_status st = TRANSCRIBE_OK; switch (pm->host_decoder.head_kind) { case HostHeadKind::TDT: - st = decode_tdt_greedy(pm->host_decoder, enc, T_enc, d_enc, pc->n_threads, pc->raw_tokens); + st = decode_tdt_greedy(pm->host_decoder, enc, T_enc, d_enc, pc->n_threads, pc->raw_tokens, + vocabulary_boost(pc, pm, params)); break; case HostHeadKind::RNNT: - st = decode_rnnt_greedy(pm->host_decoder, enc, T_enc, d_enc, pc->n_threads, pc->raw_tokens); + st = decode_rnnt_greedy(pm->host_decoder, enc, T_enc, d_enc, pc->n_threads, pc->raw_tokens, + vocabulary_boost(pc, pm, params)); break; case HostHeadKind::CTC: st = decode_ctc_greedy(pm->host_decoder, enc, T_enc, d_enc, pc->n_threads, pc->raw_tokens); diff --git a/src/arch/parakeet/parakeet.h b/src/arch/parakeet/parakeet.h index 30ae27439..719d99691 100644 --- a/src/arch/parakeet/parakeet.h +++ b/src/arch/parakeet/parakeet.h @@ -318,6 +318,9 @@ struct ParakeetSession final : public transcribe_session { std::vector pos_div_term; std::vector enc_host; std::vector raw_tokens; + // Vocabulary biasing, rebuilt only when the run's terms change. + std::vector boost_terms; + transcribe::PhraseBoost boost; // Multitalker bundle scratch: streaming-diarizer AOSC/FIFO state for // the embedded sortformer forward (diarize=ON runs only). diff --git a/src/transcribe-phrase-boost.cpp b/src/transcribe-phrase-boost.cpp new file mode 100644 index 000000000..db4f29b74 --- /dev/null +++ b/src/transcribe-phrase-boost.cpp @@ -0,0 +1,137 @@ +// transcribe-phrase-boost.cpp - see transcribe-phrase-boost.h. + +#include "transcribe-phrase-boost.h" + +#include +#include + +namespace transcribe { + +namespace { + +bool by_token(const PhraseBoost::Edge & e, int32_t token) { + return e.token < token; +} + +} // namespace + +int PhraseBoost::child(int state, int32_t token) const { + const auto & c = nodes_[static_cast(state)].children; + const auto it = std::lower_bound(c.begin(), c.end(), token, + [](const std::pair & p, int32_t t) { return p.first < t; }); + return (it != c.end() && it->first == token) ? it->second : -1; +} + +void PhraseBoost::build(const std::vector> & phrases, float score) { + nodes_.assign(1, Node{}); + edges_.clear(); + score_ = score; + std::vector end(1, false); + + // The trie: one node per distinct token prefix. + for (const std::vector & phrase : phrases) { + if (phrase.empty()) { + continue; + } + int state = root; + for (const int32_t token : phrase) { + int next = child(state, token); + if (next < 0) { + next = static_cast(nodes_.size()); + Node node; + node.earned = nodes_[static_cast(state)].earned + (state == root ? 0.0f : score); + nodes_.push_back(node); + end.push_back(false); + auto & c = nodes_[static_cast(state)].children; + c.insert(std::lower_bound(c.begin(), c.end(), std::make_pair(token, -1)), std::make_pair(token, next)); + } + state = next; + } + end[static_cast(state)] = true; + } + + // Failure links and kept bonuses, breadth first so a node's parent and + // its failure target are always finished before it. + std::deque queue; + for (const auto & [token, c] : nodes_[root].children) { + nodes_[static_cast(c)].fail = root; + nodes_[static_cast(c)].locked = end[static_cast(c)] ? nodes_[static_cast(c)].earned : 0.0f; + queue.push_back(c); + } + while (!queue.empty()) { + const int u = queue.front(); + queue.pop_front(); + for (const auto & [token, v] : nodes_[static_cast(u)].children) { + int f = nodes_[static_cast(u)].fail; + while (f != root && child(f, token) < 0) { + f = nodes_[static_cast(f)].fail; + } + const int target = child(f, token); + nodes_[static_cast(v)].fail = (target >= 0 && target != v) ? target : root; + nodes_[static_cast(v)].locked = end[static_cast(v)] ? nodes_[static_cast(v)].earned : + nodes_[static_cast(u)].locked; + queue.push_back(v); + } + } + + // Every transition out of every state, resolved through the failure + // chain once here instead of on each decode step. The deepest match wins. + edges_.assign(nodes_.size(), {}); + for (size_t s = 0; s < nodes_.size(); ++s) { + const Node & from = nodes_[s]; + std::vector & out = edges_[s]; + for (int f = static_cast(s);; f = nodes_[static_cast(f)].fail) { + for (const auto & [token, target] : nodes_[static_cast(f)].children) { + const auto at = std::lower_bound(out.begin(), out.end(), token, by_token); + if (at != out.end() && at->token == token) { + continue; + } + // Extending the match keeps everything earned so far. Falling + // back gives back the unfinished part and keeps completed + // terms; the suffix that still matches is earned again. + const bool extends = f == static_cast(s); + const float delta = + nodes_[static_cast(target)].earned - from.earned + (extends ? 0.0f : from.locked); + out.insert(at, Edge{ token, target, delta }); + } + if (f == root) { + break; + } + } + } +} + +int PhraseBoost::next(int state, int32_t token) const { + const auto & out = edges_[static_cast(state)]; + const auto at = std::lower_bound(out.begin(), out.end(), token, by_token); + return (at != out.end() && at->token == token) ? at->target : root; +} + +float PhraseBoost::delta(int state, int32_t token) const { + const auto & out = edges_[static_cast(state)]; + const auto at = std::lower_bound(out.begin(), out.end(), token, by_token); + if (at != out.end() && at->token == token) { + return at->delta; + } + const Node & from = nodes_[static_cast(state)]; + return from.locked - from.earned; +} + +void PhraseBoost::apply(int state, float * logits, int n, int32_t blank) const { + const Node & from = nodes_[static_cast(state)]; + const float base = from.locked - from.earned; + if (base != 0.0f) { + for (int t = 0; t < n; ++t) { + if (t != blank) { + logits[t] += base; + } + } + } + for (const Edge & e : edges_[static_cast(state)]) { + if (e.token >= 0 && e.token < n && e.token != blank) { + logits[e.token] += e.delta - base; + } + } +} + +} // namespace transcribe diff --git a/src/transcribe-phrase-boost.h b/src/transcribe-phrase-boost.h new file mode 100644 index 000000000..141514d35 --- /dev/null +++ b/src/transcribe-phrase-boost.h @@ -0,0 +1,70 @@ +// transcribe-phrase-boost.h - token-level phrase boosting for greedy decoders. +// +// The caller's vocabulary terms, tokenized, become an Aho-Corasick automaton +// over token ids. A greedy decoder keeps one automaton state and, before each +// argmax, adds to every candidate token the score that emitting it would +// earn: +// +// - a token that extends the current partial match earns `score`; +// - a token that breaks it gives back what the unfinished match earned and +// may start a new match through the failure links; +// - a completed term keeps its bonus, so later tokens never take it back. +// +// The blank token never moves the automaton and is never adjusted. With no +// terms the decoder skips every call, so unbiased decoding stays bit-exact. +// This is shallow fusion with a boosting tree (as in icefall's ContextGraph +// and NeMo's phrase boosting), reduced to what one greedy hypothesis needs. + +#pragma once + +#include +#include +#include + +namespace transcribe { + +class PhraseBoost { + public: + // Builds the automaton. Empty phrases are ignored; duplicates merge. + // `score` is in logit units (natural log), applied per matched token after + // a term's first one: the first piece is often a short, common word start, + // and a bonus there rewrites ordinary words. A term is completed once the + // model has begun it, and nothing is started for it. + void build(const std::vector> & phrases, float score); + + bool empty() const { return nodes_.size() <= 1; } + + static constexpr int root = 0; + + // The state after emitting `token` from `state`. + int next(int state, int32_t token) const; + + // Adds to logits[0, n) the score each non-blank token would earn from + // `state`. Tokens outside [0, n) in the automaton are ignored. + void apply(int state, float * logits, int n, int32_t blank) const; + + // The score emitting `token` from `state` earns (what apply adds to it). + float delta(int state, int32_t token) const; + + struct Edge { + int32_t token; + int target; + float delta; + }; + + private: + struct Node { + std::vector> children; // sorted by token + int fail = 0; + float earned = 0.0f; // bonus a partial match to here has collected + float locked = 0.0f; // part of `earned` that completed terms keep + }; + + int child(int state, int32_t token) const; + + std::vector nodes_; + std::vector> edges_; // per state, sorted by token + float score_ = 0.0f; +}; + +} // namespace transcribe diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index b29e6cd29..5b42c1385 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -278,6 +278,20 @@ transcribe_apply_warnings(transcribe_decode_budget_unit) add_test(NAME transcribe_decode_budget_unit COMMAND transcribe_decode_budget_unit) +# ----------------------------------------------------------------------------- +# Phrase boosting automaton (pure host, no model) + +add_executable(transcribe_phrase_boost_unit + phrase_boost_unit.cpp + ${CMAKE_SOURCE_DIR}/src/transcribe-phrase-boost.cpp) + +target_include_directories(transcribe_phrase_boost_unit PRIVATE + ${CMAKE_SOURCE_DIR}/src) + +transcribe_apply_warnings(transcribe_phrase_boost_unit) + +add_test(NAME transcribe_phrase_boost_unit COMMAND transcribe_phrase_boost_unit) + # ----------------------------------------------------------------------------- # Greedy-decode repetition guard (pure host, no model) diff --git a/tests/phrase_boost_unit.cpp b/tests/phrase_boost_unit.cpp new file mode 100644 index 000000000..98fae5d9a --- /dev/null +++ b/tests/phrase_boost_unit.cpp @@ -0,0 +1,85 @@ +// Phrase boosting automaton (pure host, no model). The scores are the whole +// contract: a wrong one either invents terms or never finds them, and the +// decoder has no other check. + +#include "transcribe-phrase-boost.h" + +#include +#include +#include + +namespace { + +int g_failures = 0; + +void expect(const char * what, float got, float expected) { + if (std::fabs(got - expected) > 1e-6f) { + std::fprintf(stderr, "FAIL %s: got %.3f, expected %.3f\n", what, got, expected); + ++g_failures; + } +} + +// Emits `tokens` from the root and returns the summed score. +float walk(const transcribe::PhraseBoost & b, const std::vector & tokens, int * end_state = nullptr) { + int state = transcribe::PhraseBoost::root; + float total = 0.0f; + for (const int32_t t : tokens) { + total += b.delta(state, t); + state = b.next(state, t); + } + if (end_state != nullptr) { + *end_state = state; + } + return total; +} + +} // namespace + +int main(void) { + transcribe::PhraseBoost b; + b.build({ { 1, 2, 3 }, { 2, 4 }, {}, { 1, 2, 3 } }, 1.0f); + + // A term's first piece earns nothing; each later matched piece earns the + // score; an unrelated token earns nothing. + expect("start a term", b.delta(transcribe::PhraseBoost::root, 1), 0.0f); + expect("continue a term", b.delta(b.next(transcribe::PhraseBoost::root, 1), 2), 1.0f); + expect("unrelated from root", b.delta(transcribe::PhraseBoost::root, 9), 0.0f); + expect("complete term", walk(b, { 1, 2, 3 }), 2.0f); + + // A completed term keeps its bonus whatever follows. + expect("completed then unrelated", walk(b, { 1, 2, 3, 9, 9 }), 2.0f); + + // A broken match gives back exactly what it had earned. + expect("broken match", walk(b, { 1, 2, 9 }), 0.0f); + expect("broken at once", walk(b, { 1, 9 }), 0.0f); + + // Falling back keeps the suffix that still matches another term: + // 1 2 then 4 completes {2, 4} through the failure link. + int state = 0; + expect("suffix completes another term", walk(b, { 1, 2, 4 }, &state), 1.0f); + expect("and keeps it", walk(b, { 1, 2, 4, 9 }), 1.0f); + + // apply() adds exactly delta() to each non-blank token and leaves blank. + int s12 = 0; + walk(b, { 1, 2 }, &s12); + std::vector logits(6, 0.0f); + b.apply(s12, logits.data(), static_cast(logits.size()), /*blank=*/5); + for (int t = 0; t < 5; ++t) { + expect("apply matches delta", logits[static_cast(t)], b.delta(s12, t)); + } + expect("blank untouched", logits[5], 0.0f); + + // No phrases: empty, and every score is zero. + transcribe::PhraseBoost none; + none.build({}, 2.0f); + if (!none.empty()) { + std::fprintf(stderr, "FAIL empty automaton reports terms\n"); + ++g_failures; + } + expect("empty automaton", none.delta(transcribe::PhraseBoost::root, 1), 0.0f); + + if (g_failures == 0) { + std::printf("phrase_boost_unit: ok\n"); + } + return g_failures == 0 ? 0 : 1; +}