插件

阿里云

接入 Paraformer、CosyVoice、Qwen、Qwen Audio 与 Qwen-Omni Realtime

阿里云插件同时提供传统 STT + LLM + TTS 流水线,以及 Qwen Audio、Qwen-Omni 端到端实时语音。Audio 与 Omni 共用同一个 RealtimeModel,按模型 ID 选择协议。

支持能力

  • STT:Paraformer 实时语音识别,默认模型为 paraformer-realtime-v2。
  • TTS:CosyVoice 流式语音合成,默认模型为 cosyvoice-v3-flash,默认音色为 longanyang。
  • LLM:百炼 OpenAI 兼容接口中的 Qwen 文本模型,默认模型为 qwen-plus。
  • Realtime:Qwen Audio 3.0 / 3.1,以及 Qwen-Omni 3.5 / 3.8。Audio 与 Omni 默认轮次检测都是 server_vad。

安装与凭证

在阿里云百炼创建业务空间 API Key:

STT

参数说明

参数类型默认值说明
modelstrparaformer-realtime-v2Paraformer 实时识别模型。使用其他模型前,请确认该模型已在百炼业务空间中开通。
languagestr | Nonezh识别语言。流式识别需要明确的语言值,示例中的 zh 表示中文。
interim_resultsboolTrue是否返回中间识别结果。开启后,Agent 可以在用户说话过程中持续更新文本;句子结束时仍会返回最终结果。
max_sentence_silenceint500句尾静音阈值,单位为毫秒。值越小,结束响应越快,但更容易把一句话切成多段;值越大,等待时间更长,长句更不容易被截断。
disfluency_removal_enabledboolFalse是否过滤“嗯”“啊”等语气词。
semantic_punctuation_enabledboolFalse是否启用基于语义的断句。开启后,服务端会结合语义判断句子边界。
punctuation_prediction_enabledboolTrue是否启用标点预测。
inverse_text_normalization_enabledboolTrue是否启用文本逆归一化,将数字、日期等内容按更适合阅读的形式输出。
vocabulary_idstr | NoneNone百炼热词表 ID。传入后会提高专有名词、产品名等热词的识别稳定性;不使用热词时保持为 None。
workspacestr | NoneNone百炼业务空间 ID。需要使用指定业务空间时传入。

api_key 不需要写在构造参数中,插件会读取 DASHSCOPE_API_KEY 环境变量。热词表需要先在 百炼热词表服务 中创建,再将返回的 ID 传给 vocabulary_id。

流式识别必须提供明确的 language,当前模式不支持用 detect_language 自动选择语言。 构造函数仍接受 detect_language 和 punctuate,但当前流式实现不会使用这两个兼容参数;标点行为 请通过 semantic_punctuation_enabled、punctuation_prediction_enabled 等参数控制。

TTS

模型与音色兼容关系

CosyVoice 的音色不能跨模型版本混用,model 和 voice 必须使用同一版本的组合。 插件默认使用 cosyvoice-v3-flash 与 longanyang,这组参数同时支持新加坡和中国(北京)地域。

模型新加坡中国(北京)音色说明
cosyvoice-v3-flash可使用官方 v3 音色,例如 longanyang。
cosyvoice-v3-plus可使用官方 v3 音色,例如 longanyang。
cosyvoice-v2—只能使用 v2 音色,例如 longxiaochun_v2;不建议作为默认模型。
cosyvoice-v3.5-plus—仅支持声音复刻或声音设计生成的自定义音色,不提供系统音色。
cosyvoice-v3.5-flash—仅支持声音复刻或声音设计生成的自定义音色,不提供系统音色。

以上地域和模型限制以阿里云官方实时语音合成文档 及官方 CosyVoice 音色列表为准。

如果使用 cosyvoice-v2,必须显式传入 v2 音色:

参数说明

参数类型默认值说明
modelstrcosyvoice-v3-flashCosyVoice 合成模型。模型必须支持所选音色,并且需要与 API Key 所属地域匹配。
voicestrlonganyang音色 ID。音色必须与模型版本匹配;可用音色以官方 CosyVoice 音色列表为准。
sample_rateint24000输出采样率,单位为 Hz。支持 8000、16000、22050、24000、44100 和 48000。
speech_rateint1历史兼容参数,不会覆盖实际请求中的 rate;调整语速请使用 rate。
volumeint100输出音量,取值范围为 0 到 100。
ratefloat1.0语速倍率,取值范围为 0.5 到 2.0;大于 1 加快,小于 1 减慢。
pitchfloat1.0音调倍率,取值范围为 0.5 到 2.0;大于 1 升高,小于 1 降低。
max_session_durationfloat600单个 TTS WebSocket 连接的最长复用时间,单位为秒。连接池到达时长上限后会自动更新连接。

api_key 不需要写在构造参数中,插件会读取 DASHSCOPE_API_KEY 环境变量。

LLM

参数说明

参数类型默认值说明
modelstrqwen-plus百炼 OpenAI 兼容接口使用的模型 ID。模型需要已在业务空间中开通。
api_keystr | NoneDASHSCOPE_API_KEY百炼 API Key。未显式传入时从环境变量读取。
userstr未传入调用方标识,会作为请求中的 user 字段发送。
temperaturefloat未传入OpenAI 兼容的生成随机性参数。当前版本构造函数接受该参数,但不会自动转发到请求。
parallel_tool_callsbool未传入是否允许一次响应并行产生多个工具调用。
tool_choiceToolChoice未传入工具选择策略,可使用 auto、none、required 或指定函数。
storebool未传入OpenAI 兼容的响应存储参数。当前版本构造函数接受该参数,但不会自动转发到请求。
metadatadict[str, str]未传入附加到请求中的元数据。
timeouthttpx.Timeout | None连接 15 秒、读取/写入/连接池各 5 秒HTTP 客户端超时配置。

api_key 未显式传入时会读取 DASHSCOPE_API_KEY 环境变量。

当前版本会自动转发 user、metadata、parallel_tool_calls 和 tool_choice;如果业务依赖 temperature 或 store,请先确认适配器版本是否已支持对应请求字段。

这个适配器使用百炼 OpenAI 兼容端点,支持 LiveKit 工具调用。model 可替换为业务 空间已经开通的 Qwen 模型 ID。

Realtime

不传 turn_detection 时使用 {"type": "server_vad"}。仓库示例是 examples/aliyun_qwen_audio_realtime.py。

workspace_id 会生成业务空间专属地址:

也可以用 base_url 显式传入完整 WebSocket 端点。插件会把 LiveKit 音频重采样为 16 kHz PCM16,模型输出为 24 kHz PCM16。

参数类型 / 可选值默认值说明
modelAudio 3.0 / 3.1 或 Omni 模型 IDqwen-audio-3.0-realtime-plus不传时仍是 Audio 3.0 Plus
voice同代内置音色、ClonedVoiceId,或 Omni 音色名见下方只在首次 session update 生效
modalities["text"] / ["text","audio"]文本 + 音频输出模态
turn_detectionServerVadOptions / SmartTurnOptions / SemanticVadOptions / Noneserver_vadOmni 不接受 smart_turn
workspace_idstr | NoneNone百炼业务空间 ID
regioncn-beijing / ap-southeast-1cn-beijing业务空间地域
max_history_turns1..5050只发给 Qwen Audio;Omni 会忽略

轮次检测示例:

smart_turn 判定无效时会带 reason=turn_invalid。插件不会为这种停顿等待回复,也不会把它写成用户消息。

Qwen-Omni

Omni 使用嵌套的 session.audio,不要和 Audio 的顶层 voice、input_audio_format 混用。插件会按模型自动组包。默认音色是 Tina。

仓库示例是 examples/aliyun_qwen_omini_realtime.py。console 只有麦克风;摄像头画面需要房间里有视频轨道。

视频帧会编码成 JPEG,大约每秒发送一帧,并且必须先发送过至少一段音频。Qwen Audio 模型会丢弃视频帧。qwen3.8-omni-flash-realtime 不能用默认的 wss://dashscope.aliyuncs.com/api-ws/v1/realtime,需要通过 workspace_id 或 base_url 指向业务空间域名。

模型与音色

Qwen Audio:

  • qwen-audio-3.1-realtime-plus
  • qwen-audio-3.1-realtime-flash
  • qwen-audio-3.0-realtime-plus
  • qwen-audio-3.0-realtime-flash

Qwen-Omni:

  • qwen3.8-omni-flash-realtime
  • qwen3.5-omni-plus-realtime
  • qwen3.5-omni-flash-realtime

Audio 3.0 内置音色是 longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng,默认 longanqian。Audio 3.1 默认 longanqian_v3.1,并接受任意 *_v3.1 或 qwen-audio-3.1-tts-* 音色。3.0 与 3.1 的系统音色不能混用。Omni 接受非空音色名,默认 Tina。

官方协议见 Qwen Audio Realtime 文档 和 Qwen-Omni Realtime 文档。

自定义音色

声音复刻在百炼侧完成,不是在 LiveKit 插件中上传音频。调用百炼 声音复刻服务时:

  1. 使用 voice-enrollment。
  2. target_model 必须设为将要使用的 Realtime 模型。
  3. 提交清晰的单人语音样本。
  4. 保存返回的 voice_id。

为某个模型创建的复刻音色不能用于另一个模型。3.1 的复刻 ID 需要以对应模型 ID 开头,例如 qwen-audio-3.1-realtime-plus-...。插件会在连接前检查模型绑定。Audio 3.1 的系统音色不需要包进 ClonedVoiceId。

常见问题

开场 generate_reply 为什么需要用户消息?

Qwen 的 Realtime 协议要求创建响应前对话中已有用户消息。插件会在首次开场且尚无 真实用户消息时,把 generate_reply(instructions="...") 转换为合成的用户触发消息; 后续 instructions 仍作为本轮附加指令。

Realtime 模式可以使用 session.say() 吗?

可以。插件会把固定话术包装为一次强约束的朗读指令,并通过当前 Qwen Audio Realtime 连接生成音频,不需要另外配置 TTS:

Qwen Audio Realtime 是对话模型而不是确定性 TTS,因此这里属于“尽量逐字朗读”。 如果业务要求金额、验证码或合规话术必须一字不差,应使用独立的 TTS 模型。

为什么出现“不支持 forcing tool_choice”?

Qwen Audio Realtime 由模型自动选择工具,不支持 LiveKit 强制指定某个工具。插件会 保留参数兼容性并记录警告,但不会把强制选择发送给 Qwen。

为什么工具完成后暂时没有语音结果?

用户仍处于 speech_started 到有效 speech_stopped 之间时,Qwen 拒绝 response.create。插件会等待服务端确认用户轮次结束,再重试工具结果响应,避免在 用户说话中途抢答。