阿里云

接入 Paraformer、CosyVoice、Qwen 与 Qwen Audio 3.0 Realtime

阿里云插件同时提供传统 STT + LLM + TTS 流水线和 Qwen Audio 3.0 端到端实时语音。

支持能力

STT：Paraformer 实时语音识别，默认模型为 paraformer-realtime-v2。
TTS：CosyVoice 流式语音合成，默认模型为 cosyvoice-v3-flash，默认音色为 longanyang。
LLM：百炼 OpenAI 兼容接口中的 Qwen 文本模型，默认模型为 qwen-plus。
Realtime：qwen-audio-3.0-realtime-plus 和 qwen-audio-3.0-realtime-flash。

安装与凭证

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

STT

参数说明

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

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

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

代码示例

from livekit.plugins import aliyun

stt = aliyun.STT(
    model="paraformer-realtime-v2",
    language="zh",
    interim_results=True,
    max_sentence_silence=500,
    vocabulary_id=None,
)

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 音色：

参数说明

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

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

代码示例

tts = aliyun.TTS(
    model="cosyvoice-v3-flash",
    voice="longanyang",
    sample_rate=24000,
    volume=100,
    rate=1.0,
    pitch=1.0,
)

tts = aliyun.TTS(model="cosyvoice-v2", voice="longxiaochun_v2")

LLM

参数说明

参数	类型	默认值	说明
`model`	`str`	`qwen-plus`	百炼 OpenAI 兼容接口使用的模型 ID。模型需要已在业务空间中开通。
`api_key`	`str \| None`	`DASHSCOPE_API_KEY`	百炼 API Key。未显式传入时从环境变量读取。
`user`	`str`	未传入	调用方标识，会作为请求中的 `user` 字段发送。
`temperature`	`float`	未传入	OpenAI 兼容的生成随机性参数。当前版本构造函数接受该参数，但不会自动转发到请求。
`parallel_tool_calls`	`bool`	未传入	是否允许一次响应并行产生多个工具调用。
`tool_choice`	`ToolChoice`	未传入	工具选择策略，可使用 `auto`、`none`、`required` 或指定函数。
`store`	`bool`	未传入	OpenAI 兼容的响应存储参数。当前版本构造函数接受该参数，但不会自动转发到请求。
`metadata`	`dict[str, str]`	未传入	附加到请求中的元数据。
`timeout`	`httpx.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

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

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

参数	类型 / 可选值	默认值	说明
`model`	`plus` / `flash` 对应的完整模型 ID	`qwen-audio-3.0-realtime-plus`	Realtime 模型
`voice`	内置音色或 `ClonedVoiceId`	`longanqian`	首次 session update 后不可改
`modalities`	`["text"]` / `["text","audio"]`	文本 + 音频	输出模态
`turn_detection`	`SmartTurnOptions` / `ServerVadOptions` / `None`	smart turn	轮次检测
`workspace_id`	`str \| None`	`None`	百炼业务空间 ID
`region`	`cn-beijing` / `ap-southeast-1`	`cn-beijing`	业务空间地域
`max_history_turns`	`1..50`	`50`	请求中保留的问答轮数

轮次检测示例：

代码示例

from livekit.agents import Agent, AgentSession
from livekit.plugins import aliyun

session = AgentSession(
    llm=aliyun.RealtimeModel(
        model="qwen-audio-3.0-realtime-plus",
        voice="longanqian",
        workspace_id="your-workspace-id",
        region="cn-beijing",
        modalities=["text", "audio"],
        turn_detection={"type": "smart_turn"},
        max_history_turns=50,
    )
)

await session.start(
    agent=Agent(instructions="你是一个简洁、友好的中文语音助手。"),
    room=ctx.room,
)

wss://{workspace_id}.{region}.maas.aliyuncs.com/api-ws/v1/realtime

# 语义轮次检测：用户停顿但语义未结束时继续等待
turn_detection = aliyun.SmartTurnOptions(type="smart_turn")

# 声学 VAD
turn_detection = aliyun.ServerVadOptions(
    type="server_vad",
    threshold=0.5,
    silence_duration_ms=500,
)

# 手动提交音频
turn_detection = None

模型与音色

模型：

qwen-audio-3.0-realtime-plus
qwen-audio-3.0-realtime-flash

内置音色：

longanqian
longanlingxin
longanlingxi
longanxiaoxin
longanlufeng

这些选项已经写入 Python 类型提示，IDE 可以直接补全。官方能力与事件协议见 Qwen Audio Realtime 文档。

自定义音色

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

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

为 plus 创建的音色不能用于 flash，插件会在连接前检查模型绑定。

代码示例

realtime = aliyun.RealtimeModel(
    model="qwen-audio-3.0-realtime-plus",
    voice=aliyun.ClonedVoiceId(
        "qwen-audio-3.0-realtime-plus-myvoice-0123456789"
    ),
    workspace_id="your-workspace-id",
)

常见问题

开场 `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。插件会等待服务端确认用户轮次结束，再重试工具结果响应，避免在用户说话中途抢答。

建议修改

插件

参数说明

模型与音色兼容关系

参数说明

参数说明

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

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

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

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

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

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