Hotwords not working? Check the request path and installed package

FunASR Blog · 2026-11-13

Your team may use hotwords for product names and personal names. Before expanding the vocabulary, check that the terms sent by the client actually reach the model in a supported form.

A client may encode two weighted terms as a JSON object, then place that JSON string inside a WebSocket message. The server must not treat braces, quotes and numbers as the terms themselves. Here is how to check the message, server script and standalone runtime separately.

Hotwords are hints, not forced replacements or accuracy guarantees. This article describes verified protocol and runtime boundaries, not a new recognition benchmark, speed ranking or production deployment guarantee.

1. Identify the entry point you actually use

These are separate deliverables. Updating the root funasr package does not update a copied server script or replace a standalone runtime installation. The WebSocket fix is tracked in #3892, preserving the original #3880 author history. One version number is not proof that the entire service was upgraded.

2. Turn JSON hotwords into model input

This example only encodes a message. It does not start a server, download weights or transmit audio:

import json

hotwords = {"阿里巴巴": 20, "通义实验室": 30}
message = {"hotwords": json.dumps(hotwords, ensure_ascii=False)}
assert json.loads(message["hotwords"]) == hotwords
print(json.dumps(message, ensure_ascii=False))

The fixed Python server joins JSON object keys with spaces and supplies them to both offline and online model parameters. An empty object becomes an empty string. Plain strings and strings that cannot be parsed as JSON retain their original text. This AutoModel interface does not accept numeric hotword weights, so 20 and 30 do not become relative model bias strengths. Check the chosen model and deployment protocol separately if weighted biasing is required.

A complete client must also follow its audio and chunking protocol. The snippet is not a complete streaming client, nor proof that other message formats are compatible. Configure TLS, authentication and resource limits for deployment. Do not put private audio, transcripts or sensitive vocabulary into public logs.

3. Verify the installed and imported Torch package

Use a dedicated test environment, install the pinned version, then inspect package metadata and the import location. Do not modify a shared serving environment directly:

python -m pip install "funasr-torch==0.1.7"
python -m pip check
python -c 'import importlib.metadata as m, funasr_torch; print(m.version("funasr-torch")); print(funasr_torch.__file__)'

The exported embedding used by the Contextual and Seaco wrappers has a hotword width of ten. Version 0.1.7 removes empty whitespace entries, retains the first ten characters of longer terms, and keeps indexes within that embedding range. This fixes a runtime boundary; it does not preserve the truncated suffix as a hint. Prefer short, distinctive terms and check both useful matches and false triggers on recordings you are authorized to process.

4. Compare individual and batched timestamps

Run a short recording and a long recording individually, then together in a batch. Check output count, text and timestamps against each recording. The Paraformer change in 0.1.7 slices each peak sequence by its own feature length, preventing padded frames from extending the shorter recording's final timestamp. The package also includes terminal abbreviation grouping and word-boundary fixes for rich-transcription segments.

Installed behavior is tested separately for the wheel and source distribution. Existing real GPU evidence uses synthetic fixtures and is bound to the runtime source file by file. It is not a new pretrained-model accuracy evaluation or a full compatibility guarantee for every model and device. Your own languages, noise conditions and recording lengths still need acceptance testing.

Release artifacts and your next step

See the Torch 0.1.7 release and checksums, PyPI package and ONNX 0.4.11 release. Source changes are tracked in #3882, #3871 and #3869.

Next, use a small set of authorized recordings and the meeting-transcript acceptance checklist to inspect terminology, omissions and timestamps before upgrading your service.