★ FEATURED ARTICLE LiveKit Agents 如何用 STT keyterm 提示词提高品牌名的转写准确率【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents用语音 Agent 做点单、客服或预约时一个常见的问题是 STT 把品牌名听错用户说 Big Mac转出来却成了别的拼写Agent 随后的工具调用自然也跟着错。LiveKit Agents 的仓库里examples/drive_thru这个麦当劳点单示例给出的解法是在初始化 STT 时传入keyterm词表把品牌名如Big Mac、McFlurry、McCrispy作为提示词喂给识别器以提高这些词转写的准确率。本文以这个示例为主路径说明如何配置keyterm、如何运行验证以及可选的会话级 keyterms 自动检测怎么用。环境准备按 examples/README.md 的说明运行示例需要一个 LiveKit Cloud 账户或本地 LiveKit serverexamples目录下的.env文件写入你的 LiveKit 凭据参考examples/.env.exampleLIVEKIT_URLwss://your-project.livekit.cloud LIVEKIT_API_KEYyour_api_key LIVEKIT_API_SECRETyour_api_secretLIVEKIT_URL换成你的项目地址后两项换成你的密钥。大多数示例包括 drive-thru默认走LiveKit Inference此时用 LiveKit 的 API key/secret 做鉴权只有直接用某个厂商插件的示例才需要额外配置对应厂商的 key。Python 3.10 以上和 uv 声明requires-python 3.10并依赖livekit-agents1.6、livekit-plugins-silero、livekit-plugins-turn-detector等。在仓库根目录安装依赖uv sync --all-extras --dev主路径在 STT 初始化时传入 keyterm 词表drive-thru 示例中AgentSession的 STT 是这样创建的见 agent.pysession AgentSessionUserdata, ... )要点STT 模型是deepgram/nova-3。Deepgram 插件的文档明确keyterm只被 Nova-3 模型支持见 stt.py 的参数说明。extra_kwargs里的keyterm词表就是 README 里说的 STT Tuning初始化时带上品牌名让识别器更准确地转出这些词见 README.md。如果你绕过 inference 网关、直接用 Deepgram 插件的STT构造参数名同样是keyterm接受str或list[str]旧的keyterms参数已弃用并会打 warning。直接给非 Nova-3 模型传keyterm会在构造时抛错插件里的校验逻辑和报错文案如下见 stt.pyKeyterm Prompting is only available for transcription using the Nova-3 Model. To boost recognition of keywords using another model, use the Keywords feature.反过来keywords带 boost 值的词表与 Nova-3 互斥Nova-3 上设置keywords会抛ValueError提示改用 Keyterm PromptingNova-2 / Nova-1 / Enhanced / Base 等模型则用keywords做词表增强。关于其他厂商模型inference 网关会按模型前缀把 keyterms 映射到对应参数deepgram/前缀映射为keytermassemblyai/前缀映射为keyterms_promptspeechmatics/linden-1明确不支持 keyterm 提示见 inference/stt.py。也就是说stt_context_options的会话级 keyterms 只会对支持该能力的模型生效。运行示例并观察转写安装好依赖并配好.env后从仓库根目录按示例 README 的方式运行drive-thru 同理也可单独进入examples/drive_thru目录执行uv sync后运行uv run agent.py console该目录自带可独立解析的 pyproject.toml 和 Dockerfileuv run examples/drive_thru/agent.py consoleAgent 会跑在 console 里用麦克风对它说出品牌名比如 Can I get a Big Mac观察 Agent 的应答与转写内容是否与 keyterm 词表中的拼写一致。示例仓库里还带了 test_agent.py 的行为测试它验证的是输入品牌名 → 工具调用选中正确item_id这条链路如 Can I get a McFlurry Oreo? 应触发order_regular_item且item_id为sweet_mcflurry_oreo。注意这些测试以文本方式驱动会话校验的是 LLM 的工具选择不是 STT 本身的转写不能替代你对真实语音的验证。可选分支会话级 keyterms 与自动检测如果不想把词表写死在 STT 初始化里LiveKit Agents 提供了会话级的stt_context_options。examples/voice_agents/basic_agent.py的用法如下见 basic_agent.pysession AgentSession( ... # automatically detect keyterms and apply them to the STT per user turn stt_context_options{ keyterms: [LiveKit], keyterm_detection: { enabled: True, turn_interval: 1, # increase to reduce LLM API calls }, }, )对应选项定义在 keyterm_detection.pykeyterms静态词表在所有接受词表的地方都会应用不会被自动检测改动keyterm_detection.enabled是否启动后台检测器默认Falsekeyterm_detection.turn_interval每 N 个用户轮次跑一次检测默认1调大可减少检测 LLM 的调用量keyterm_detection.max_keyterms已确认检测词的数量上限默认不限keyterm_detection.timeout单轮检测的超时秒数默认10.0keyterm_detection.llm用于抽取的检测 LLM未设置时默认使用google/gemma-4-31b-it不会占用 Agent 自己的 LLM。工作原理检测器用独立 LLM 从对话转写中抽取有辨识度的词人名、品牌、地名等只有被佐证拼写后才推送到 STT候选词仅跟踪不生效实现见 KeytermDetector。几个值得注意的边界检测只会在 STT 支持 keyterms 时启动STT 不支持时框架会打日志keyterm detection is enabled but the STT does not support keyterms; skipping detection并跳过会话进行中可以整体替换用户定义的词表session.update_options(keyterms[...])会替换用户静态词表并立即同步到 STT但自动检测出的词不受影响见 agent_session.py。验证这个分支是否在工作设置环境变量LK_KEYTERMS_DEBUG1后每一轮检测的输入和pending/confirm/remove结果都会以 debug 日志输出见 keyterm_detection.py词表发生变化时也会有keyterms changed的 debug 日志附带 added/removed 列表。限制与排查模型限制keyterm只对 Deepgram Nova-3 可用keywords只对 Nova-2 / Nova-1 / Enhanced / Base 可用。两者用错模型都会在构造 STT 时直接抛ValueError报错文案见上文这是配置不生效时最先要检查的点。参数名Deepgram 插件里keyterms是弃用名正确参数是keyterminference 网关的extra_kwargs中 key 名按厂商区分Deepgram 用keytermAssemblyAI 用keyterms_prompt。生效范围keyterm 词表只对接受词表的 STT 模型生效stt_context_options的自动检测也依赖 STT 上报的 keyterms 能力不支持时按上面的 warning 日志排查。效果验证仓库文档说明 keyterm 的目的是 improve transcription accuracy但没有给出量化的准确率指标。验证方式就是在 console 中真实说一遍品牌名听 Agent 转写与应答是否正确转写仍不对时优先核对词表拼写是否与你说法一致、模型是否为 Nova-3。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
