video-edit-planner-skill/references/funasr-nano-context-hotwords.md

Fun-ASR-Nano context, hotwords, and transcript correction notes

Use this when deciding whether Fun-ASR-Nano can use semantic context to improve recognition quality.

Verified from upstream code/docs

Sources checked:

• modelscope/FunASR funasr/models/fun_asr_nano/model.py
• modelscope/FunASR funasr/models/fun_asr_nano/inference_vllm.py
• modelscope/FunASR funasr/models/fun_asr_nano/inference_vllm_pipeline.py
• modelscope/FunASR funasr/models/fun_asr_nano/inference_vllm_streaming.py
• modelscope/FunASR docs/vllm_guide_zh.md
• modelscope/FunASR docs/model_selection.md

The upstream model is LLM-based: a SenseVoice-style audio encoder plus an LLM decoder. The upstream model-selection guide describes Fun-ASR-Nano as stronger on hard cases, context, and proper nouns.

The PyTorch path has a prompt builder roughly shaped as:

def get_prompt(self, hotwords: list[str], language: str = None, itn: bool = True):
    if len(hotwords) > 0:
        prompt = "请结合上下文信息，更加准确地完成语音转写任务。如果没有相关信息，我们会留空。\n\n\n**上下文信息：**\n\n\n"
        prompt += f"热词列表：[{hotwords}]\n"
    else:
        prompt = ""
    if language is None:
        prompt += "语音转写"
    else:
        prompt += f"语音转写成{language}"
    if not itn:
        prompt += "，不进行文本规整"
    return prompt + "："

The vLLM path exposes the same idea via hotwords and language. The vLLM guide documents language and hotwords as generate() / API parameters.

What is enabled by default?

Do not assume cross-segment semantic correction is automatically enabled for offline file transcription.

In the bundled transcription script at the time of writing:

• funasr_common.py calls model.generate(input=..., batch_size=1).
• It passes language only when the user specified a non-auto language.
• It passes use_itn=True for Fun-ASR-Nano.
• It does not pass hotwords.
• It does not pass prev_text or a rolling context between VAD segments.

Therefore, the current script uses Nano's model-internal contextual ability, language hint, and ITN, but it does not provide external domain context or previous transcript text. The transcript may still contain homophone/near-homophone mistakes such as 帐篷 -> 账本 when the source audio is unclear.

Practical guidance

1. Use explicit --language AUDIO_LANGUAGE_CODE to avoid language ambiguity.
2. If the content has known names, game terms, locations, item names, or recurring jargon, collect them as a hotword list before transcription.
3. Prefer adding explicit script support such as --hotword TERM / --hotwords-file FILE over relying on vague “semantic correction”.
4. Treat hotwords as biasing hints, not proof. They can improve proper nouns and domain terms but cannot fully fix unclear audio.
5. For final captions, quotes, subtitles, narration, or published copy, still re-listen and manually correct the original audio segment.
6. Do not silently invent hotwords. Ask the user for domain terms or extract candidate terms from existing project notes/transcripts and confirm them.

Possible future script enhancement

Expose hotwords in the bundled CLI:

funasr-nano VIDEO_PATH \
  --track TRACK_INDEX \
  --language AUDIO_LANGUAGE_CODE \
  --hotword "帐篷" \
  --hotword "复活点" \
  --output-dir VIDEO_DIR

Then pass them to FunASR:

gen_kw["hotwords"] = args.hotwords

For longer lists, support a UTF-8 text file with one hotword per line.