[BUG] 热词偶尔生效的问题

[zyl168]

Important Instructions ⚠️

Before submitting this issue, please read carefully and confirm the following:

• I am using the latest version of sherpa-onnx. If not, I will upgrade and check if the issue persists.
• I understand that issues not reproducible on the latest version may be closed without response.
• I have verified that the error is reproducible using only sherpa-onnx, not code from my own project.
• I will provide detailed steps to reproduce the issue.
• I will provide complete logs and error messages.
• I understand that issues not following these instructions may be closed or receive no response (如果直接删掉这个issue template 里的步骤，我们很有可能不会回复您的issue).

---

Describe the issue

我在使用x-asr-streaming时配置了热词，但是发现热词只有部分时候生效

Steps to reproduce

1. 配置热词和bpe.vocab，使用go-example-api代码
2. 配置相应热词权重，使用x-asr-streaming-480-int8版本
3. 阅读热词内容，发现有时生效，有时不生效

Expected behavior

阅读热词内容，发现有时生效，有时不生效

Environment

• sherpa-onnx version:[v1.13.4]
• OS: Linux-x86 Ubuntu 20.04.6 LTS
• Python version:3.8.18
• onnxruntime version:1.17.1
• GPU (if applicable):
• NPU (if applicable):

Logs

[dosubot]

Hi @zyl168! I'm Dosu and I'm helping the csukuangfj's Org team.

热词"有时生效，有时不生效"通常与以下几点有关：

1. 解码方法必须是 modified_beam_search。 热词仅在 modified_beam_search 下生效，默认的 greedy_search 会静默忽略热词配置 [1]。请确认你的 Go 代码中确实设置了 decoding_method = "modified_beam_search"。

2. Aho-Corasick 匹配机制本身的特性。 热词通过 Aho-Corasick 自动机实现：匹配到热词前缀时会给路径加分，但如果该路径最终未能完整匹配整个热词，之前加的分会被取消 [1]。因此热词只是提高了正确假设在 beam search 中存活的概率，并不保证一定生效——当声学证据较弱或其他假设得分更高时，加分路径仍可能被淘汰。

3. Beam 宽度（max_active_paths）。 默认值为 4 [2]，较窄的 beam 会降低加分假设存活到最后的概率。可以尝试增大到 8–16，观察热词命中率是否提升（会略微增加延迟）。

4. hotwords-score 调参。 分数太低可能不足以克服竞争假设。另外，如果对单个热词指定分数，格式必须是热词后跟 :score，且 score 必须在该行最末尾，否则该热词会无效 [1]。

如果能提供你使用的 recognizer 配置（decoding-method、hotwords-score、max-active-paths 的值），以及几组热词未生效时的具体转录结果对比，可以进一步帮你排查是 beam 宽度、分数还是匹配逻辑的问题。

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[zyl168]

你好@zyl168我是Dosu，我正在帮助 csukuangfj 的组织团队。

热词“有时生效，有时不生效”通常与以下几点有关：

1. **解码方法必须是modified_beam_search。**热词仅modified_beam_search在下生效，默认的greedy_search会静默忽略热词[1]。请确认你的 Go 代码中确实设置了decoding_method = "modified_beam_search"。
2. **Aho-Corasick 匹配本身的特性。**热词通过 Aho-Corasick 自动机实现：匹配到热词一起时给路径加分，但如果路径最终未能完整匹配整个更高热词，加的分会取消 [1]。因此热词只是提高了正确的假设在波束搜索中此时的概率，并不能保证一定生效——当声学较弱或假设其他得分时之前，加分路径仍有可能被淘汰。
3. **Beam宽度（max_active_paths）。**默认值为4 [2]，较窄的beam会降低加分假设到最后的概率。可以尝试增加到8-16，观察热词命中率是否提升（会稍微增加延迟）。
4. hotwords-score另外，如果对单个热词分数指定，格式必须是热词后跟，:score且分数必须在该行最复杂，否则该热词会无效[1]。

如果能够提供您使用的识别器配置（decoding-method、hotwords-score、max-active-paths的值），以及几组热词未生效时的具体转录结果对比，可以进一步帮助排查是束宽度、还是分数匹配逻辑的问题。

回复时只需提及@dosu即可。

Docs已经过时了。直接用Dosu吧。

decoding-method、hotwords-score、max-active-paths分别是modified_beam_search，10.0，4，下面是我的源码：
package engine

import (
"context"
"fmt"
"strings"
"sync"

sherpa "github.com/k2-fsa/sherpa-onnx-go/sherpa_onnx"

)

type SherpaOnline struct{ rec *sherpa.OnlineRecognizer; config OnlineConfig }

type OnlineConfig struct {
Model, Encoder, Decoder, Joiner, Tokens, ModelType string
HotwordsFile string; HotwordsScore float32
ModelingUnit string; BpeVocab string
HrLexicon string; HrRuleFsts string
NumThreads int; Provider string; Debug int; SampleRate int
}

func NewSherpaOnline(cfg OnlineConfig) (*SherpaOnline, error) {
c := sherpa.OnlineRecognizerConfig{}
c.FeatConfig = sherpa.FeatureConfig{SampleRate: cfg.SampleRate, FeatureDim: 80}
c.ModelConfig.Tokens = cfg.Tokens
c.ModelConfig.NumThreads, c.ModelConfig.Provider, c.ModelConfig.Debug = cfg.NumThreads, cfg.Provider, cfg.Debug
c.ModelConfig.ModelType = cfg.ModelType
if cfg.HotwordsFile != "" {
c.DecodingMethod = "modified_beam_search"
c.MaxActivePaths = 4 // larger beam for better accuracy with hotwords
} else {
c.DecodingMethod = "modified_beam_search"
}
c.HotwordsFile = cfg.HotwordsFile
c.HotwordsScore = cfg.HotwordsScore
c.ModelConfig.ModelingUnit = cfg.ModelingUnit
c.ModelConfig.BpeVocab = cfg.BpeVocab
c.Hr.Lexicon = cfg.HrLexicon
c.Hr.RuleFsts = cfg.HrRuleFsts
c.EnableEndpoint = 1
c.Rule1MinTrailingSilence, c.Rule2MinTrailingSilence, c.Rule3MinUtteranceLength = 2.4, 1.2, 20.0
switch strings.ToLower(cfg.ModelType) {
case "zipformer2", "zipformer2_ctc":
c.ModelConfig.Zipformer2Ctc.Model = cfg.Model
case "paraformer":
c.ModelConfig.Paraformer.Encoder, c.ModelConfig.Paraformer.Decoder = cfg.Encoder, cfg.Decoder
case "transducer":
c.ModelConfig.Transducer.Encoder, c.ModelConfig.Transducer.Decoder, c.ModelConfig.Transducer.Joiner = cfg.Encoder, cfg.Decoder, cfg.Joiner
default:
if cfg.Model != "" { c.ModelConfig.Zipformer2Ctc.Model = cfg.Model
} else { c.ModelConfig.Transducer.Encoder, c.ModelConfig.Transducer.Decoder, c.ModelConfig.Transducer.Joiner = cfg.Encoder, cfg.Decoder, cfg.Joiner }
}
rec := sherpa.NewOnlineRecognizer(&c)
if rec == nil { return nil, fmt.Errorf("failed to create OnlineRecognizer") }
return &SherpaOnline{rec: rec, config: cfg}, nil
}

func (s *SherpaOnline) NewOnlineSession() (OnlineSession, error) {
stream := sherpa.NewOnlineStream(s.rec)
if stream == nil { return nil, fmt.Errorf("failed to create OnlineStream") }
return &sherpaOnlineSession{rec: s.rec, stream: stream}, nil
}
func (s *SherpaOnline) TranscribeOffline(ctx context.Context, samples []float32, sampleRate int) (RecognitionResult, error) {
return RecognitionResult{}, fmt.Errorf("use offline engine")
}
func (s *SherpaOnline) Healthy() bool { return s.rec != nil }
func (s *SherpaOnline) Close() error { sherpa.DeleteOnlineRecognizer(s.rec); return nil }

type sherpaOnlineSession struct {
mu sync.Mutex; rec *sherpa.OnlineRecognizer; stream *sherpa.OnlineStream; text string
}
func (s *sherpaOnlineSession) AcceptWaveform(sampleRate int, samples []float32) (string, error) {
s.mu.Lock(); defer s.mu.Unlock()
s.stream.AcceptWaveform(sampleRate, samples)
for s.rec.IsReady(s.stream) { s.rec.Decode(s.stream) }
result := s.rec.GetResult(s.stream)
if result != nil && result.Text != "" && result.Text != s.text { s.text = result.Text; return strings.ToLower(s.text), nil }
return "", nil
}
func (s *sherpaOnlineSession) IsEndpoint() bool { s.mu.Lock(); defer s.mu.Unlock(); return s.rec.IsEndpoint(s.stream) }
func (s *sherpaOnlineSession) CurrentText() string { s.mu.Lock(); defer s.mu.Unlock(); return s.text }
func (s *sherpaOnlineSession) Reset() { s.mu.Lock(); defer s.mu.Unlock(); s.rec.Reset(s.stream); s.text = "" }
func (s *sherpaOnlineSession) InputFinished() { s.mu.Lock(); defer s.mu.Unlock(); s.stream.InputFinished() }
func (s *sherpaOnlineSession) Close() error { s.mu.Lock(); defer s.mu.Unlock(); sherpa.DeleteOnlineStream(s.stream); return nil }

[csukuangfj]

推荐 https://k2-fsa.github.io/sherpa/onnx/homophone-replacer/index.html

[zyl168]

推荐 https://k2-fsa.github.io/sherpa/onnx/homophone-replacer/index.html

感谢匡神，已经使用，哈哈