上个月做语音客服机器人我拿LiveKit搭了一套实时语音交互的底座前端WebRTC接入后端LiveKit Agents负责调度语音识别、大模型、语音合成。一开始图省事直接用了官方默认的语音服务结果在大陆环境下问题不断——识别延迟从几百毫秒飙到三四秒高峰期还偶发断流。后面把语音交互服务整体切到阿里云智能语音交互NLS才算把稳定性救回来。这篇就把“在中国大陆使用LiveKit集成阿里云语音交互服务”这件事里最关键的部分拆开讲清楚为什么要自己接、适配器怎么写、部署有哪些坑以及我实测下来的调优方向。适合谁看如果你正在用LiveKit做语音Agent、语音客服、同传字幕这类产品并且目标用户在国内那这篇文章能帮你少走不少弯路。纯前端接LiveKit但不跑Agents的读者也可以从自定义语音服务接入这部分拿到一些启发。我会尽量把代码链路讲细但不用大段工程源码糊脸而是把核心逻辑和需要注意的边界情况说透。1. 先搞清楚一个问题LiveKit缺的到底是哪块语音能力1.1 LiveKit Server和LiveKit Agents各自负责什么很多刚接触LiveKit的人会把“部署了LiveKit服务器”等同于“语音Agent能跑了”这两件事距离其实挺远。LiveKit Server本质上是一个WebRTC SFU选择性转发单元。它只负责把音视频流在参与者之间转发、录制、混流这些能力让它非常适合做直播间、视频会议、远程协作这类场景。但它本身不认识语音内容不负责“听懂”用户在说什么也不负责“开口说话”。LiveKit Agents才是做语音交互的那一层。它运行在LiveKit Server旁边以普通客户端的身份加入房间订阅用户麦克风轨道然后串联一条AI链路STT语音转文字把用户说的话变成文本LLM大语言模型理解文本、生成回复TTS文字转语音把回复文本变成语音播放给用户问题就出在这里。LiveKit Agents默认配置的STT和TTS大多数是Deepgram、ElevenLabs、OpenAI、Azure这类海外服务。它们在海外挺好用但在大陆的访问链路质量就谈不上稳定了。不是不能访问而是延迟忽高忽低、连接偶尔中断这在语音交互场景里非常致命——用户说一句话等三秒才有反应这产品基本没法用。1.2 默认语音组件在大陆的体验瓶颈在哪里我自己实测下来问题集中在几个层面连接建立慢海外语音服务的WebSocket/TLS握手经过跨境链路最差的时候要23秒才能建立连接而用户早就开始说话了。识别延迟波动大就算连接建立成功音频数据也要跨境往返识别结果返回时延抖动非常明显尤其在晚高峰。掉线恢复难公网链路一抖动WebSocket断连后自动重连又要走一遍握手流程整个会话体验会瞬间垮掉。数据合规与成本可控性语音数据是否跨境传输、按量计费的汇率和账单复杂度、出了问题找谁支持这些都是生产环境要面对的实际情况。如果产品只做海外市场这些都不是大问题。但只要目标用户在国内语音能力就必须考虑大陆可用的服务商作为底座。1.3 阿里云语音交互服务能补上这一环阿里云的智能语音交互服务NLS提供实时语音识别ASR和语音合成TTS正好是LiveKit Agents缺失的那两个环。它有几个对国内开发者很友好的特点国内多地域接入上海、北京、杭州、深圳等地都有网关可以跟业务服务器就近部署内网/低延迟访问。中文识别效果好支持句级标点预测、热词定制、方言模型对客服、会议、直播这些垂直场景有专门优化。WebSocket协议接入实时识别和合成都是WebSocket JSON控制帧 二进制音频帧的交互方式不绑定特定语言SDK随便用Python、Node.js、Go都能自己实现客户端。按量计费有免费额度生产之前可以先小流量验证成本可控。所以我当时的改造思路就很清晰了LiveKit Server和Agents继续保留只把STT和TTS底层从默认的海外服务替换成阿里云NLS的WebSocket客户端。2. 集成前的地基服务开通、密钥与LiveKit Server部署2.1 开通阿里云智能语音交互服务并准备三把钥匙在写代码之前先把阿里云这边的资源备齐。整个过程不算复杂但有三样东西容易搞混我这里一起说清楚。第一是AccessKey ID和AccessKey Secret。这是阿里云账号级别的API密钥在控制台“AccessKey管理”里创建。需要注意AccessKey是账号维度的权限很大生产环境建议用RAM子账号授权只开通NLS服务的调用权限不要把主账号密钥直接放到代码或环境变量里。第二是AppKey。在智能语音交互控制台创建一个应用会拿到一个AppKey它标识你这个调用属于哪个业务应用也跟你在控制台上选择的热词模型、语言模型绑定。一个账号下可以建多个AppKey我习惯按项目维度分一个方便后面看账单和调用量。第三是临时Token。调NLS的WebSocket接口时认证依靠的是Token而不是AccessKey直连。Token的有效期默认是24小时需要自己去获取。获取方式是调用阿里云POP API的GetToken接口或者用官方SDK封装好的方法。因为Token有有效期代码里必须做缓存和定时刷新这个坑后面专门讲。开通服务时有个细节智能语音交互下面有“实时语音识别”“录音文件识别”“语音合成”等不同产品实时语音识别和语音合成是分开计费、分开开通的。别只开通了一个然后在跑TTS时报错说没有权限最后查半天发现是产品没开。2.2 部署一个能对外服务的LiveKit ServerLiveKit Server的部署方式有很多Docker Compose、Kubernetes、二进制都有官方支持。我在这个项目里选的是Docker Compose因为单机环境够用、升级方便、配置也直观。一个最小可用的docker-compose.yml大概长这样version: 3.9 services: caddy: image: caddy:latest restart: unless-stopped ports: - 80:80 - 443:443 volumes: - ./Caddyfile:/etc/caddy/Caddyfile - caddy_data:/data command: caddy reverse-proxy --from livekit.example.com --to livekit:7880 livekit: image: livekit/livekit-server:latest restart: unless-stopped command: --config /etc/livekit.yaml volumes: - ./livekit.yaml:/etc/livekit.yaml ports: - 7880:7880 - 7881:7881 - 50000-50100:50000-50100/udp volumes: caddy_data:这里的Caddy负责自动签发HTTPS证书把WSS流量转发到LiveKit Server的7880端口。LiveKit的WebSocket地址是wss://协议如果没有TLS证书浏览器和大部分移动端都没办法正常建立WebRTC连接所以这一层不是可选项。如果你不想多维护一个Caddy也可以在阿里云控制台申请免费的SSL证书配置到Nginx里做反向代理。免费证书一般一年有效期到期后需要手动续期再部署不过阿里云控制台上这个操作流程已经很成熟了。2.3 音频格式认知LiveKit里的Opus和阿里云要的PCM很多人第一次写适配器时最容易栽在音频格式上。我先把概念捋一下用户在浏览器或手机端采集到音频经过WebRTC编码后在网络上是Opus编码格式。LiveKit Server转发这些Opus包给Agents。LiveKit Agents内部会对Opus进行解码得到的是PCM裸数据以AudioFrame的形式传给开发者。阿里云NLS的实时识别接口接收的音频格式是16KHz、16bit、单声道的PCM语音合成返回的也是PCM或WAV。所以适配器的核心工作之一就是把LiveKit的音频帧和阿里云的音频数据互相转换。大多数情况下直接在AudioFrame层面处理PCM就行不需要自己处理Opus编码解码。但要注意两点采样率对齐。LiveKit音频帧默认采样率可能是48KHz需要重采样到16KHz阿里云才认。Agents框架里一般有AudioResampler或者你在写入NLS连接前做一次转换。声道数对齐。如果用户用了立体声耳麦AudioFrame可能是双声道的得降混成单声道再送STT。否则识别准确率会明显下降甚至报格式错误。# 伪代码把LiveKit AudioFrame转换成16k单声道PCM def frame_to_aliyun_pcm(frame: rtc.AudioFrame) - bytes: # 先降混到单声道 pcm frame.data if frame.num_channels 1: pcm downmix_to_mono(pcm, frame.num_channels) # 重采样到16kHz if frame.sample_rate ! 16000: pcm resample_to_16000(pcm, frame.sample_rate) return pcm.tobytes()这个“16KHz/16bit/单声道PCM”的知识点越早统一后面的坑就越少。3. 写适配器的核心把阿里云ASR/TTS桥接到LiveKit Agents3.1 设计思路把LiveKit Agents的抽象接口“翻译”成阿里云协议LiveKit Agents对STT和TTS都做了抽象分别对应stt.STT和tts.TTS。我们要做的事情就是实现这两个抽象类让Agents以为自己在跟一个普通语音服务通信而底层的真实服务是阿里云NLS。从数据流来看整个桥接设计是这样的STT方向LiveKit Agents把用户的AudioFrame推给我们我们把帧转成音频字节流写入阿里云NLS的WebSocket连接。阿里云识别出文本后通过WebSocket回调事件返回我们把文本转成Agents需要的SpeechData对象。TTS方向Agents把大模型回复的文本传给我们我们把文本打包成TTS请求发给阿里云语音合成WebSocket接口收到音频帧后拼装成LiveKit的AudioFrame推回给Agents。所以本质上我们是在LiveKit和阿里云之间做一次协议翻译和数据流搬运。这个活儿不涉及复杂算法但对异步状态管理、连接生命周期、数据缓冲的要求很高。3.2 实现STT适配器用户的语音如何变成文字阿里云实时语音识别的WebSocket交互大致可以分为三步建立连接后发送StartTranscription指令携带AppKey、采样率、是否返回中间结果等参数。持续发送二进制音频帧。服务端异步返回识别事件常见的有SentenceBegin句首、RecognitionResultChanged中间结果、SentenceEnd句尾带最终文本。LiveKit这边的STT接口需要支持流式音频输入并异步返回识别结果。我建议用一个后台协程专门监听阿里云的WebSocket事件把识别出的句子塞进一个队列由LiveKit的回调去向队列取结果。文字太抽象直接上核心逻辑伪代码from livekit.agents import stt from livekit import rtc class AliyunSTT(stt.STT): def __init__(self, token: str, app_key: str, sample_rate: int 16000): super().__init__(capabilitiesstt.STTCapabilities(streamingTrue, interim_resultsTrue)) self._token token self._app_key app_key self._sample_rate sample_rate def _create_stream(self): return AliyunSTTStream(self) class AliyunSTTStream(stt.Stream): def __init__(self, stt: AliyunSTT): self._stt stt self._ws None self._result_queue asyncio.Queue() self._background_task None async def start(self): self._ws await connect_aliyun_nls(tokenself._stt._token) await send_start_transcription( self._ws, app_keyself._stt._app_key, sample_rateself._stt._sample_rate, enable_intermediate_resultTrue, ) self._background_task asyncio.create_task(self._listen_events()) async def push_frame(self, frame: rtc.AudioFrame): # 转成16k/16bit/mono PCM然后写入WebSocket pcm frame_to_aliyun_pcm(frame) await self._ws.send(pcm) async def flush(self): # 通知阿里云端结束当前句识别 await send_stop_transcription(self._ws) async def close(self): await self._background_task.cancel() await self._ws.close() async def _listen_events(self): async for message in self._ws: event parse_aliyun_event(message) if event.type SentenceEnd: await self._result_queue.put( stt.SpeechData(textevent.text, confidenceevent.confidence) ) async def recognize(self) - stt.SpeechData: return await self._result_queue.get()这段代码里最需要注意的是流的生命周期管理。LiveKit会多次调用push_frame也会在用户停顿或VAD判定句子结束时调用flush。如果我们的阿里云WebSocket连接没有正确关联到当前句子就会出现明明识别出了文字但Agents那边等不到结果的情况。我的做法是每个AliyunSTTStream实例独享一个WebSocket连接减少状态交错代码逻辑上更清晰。3.3 实现TTS适配器大模型的回复文本如何变成语音TTS这边相对简单一些。阿里云语音合成也是WebSocket协议发送一段文本服务端返回一段或多段音频二进制帧。LiveKit的TTS接口需要实现synthesize(text)方法返回音频数据流。要注意的一点是TTS返回的音频格式跟STT输入格式保持一致——16KHz、16bit、单声道PCM。如果大模型回复是带Markdown符号的长文本建议先把特殊符号清理掉否则合成出来的语音可能把符号本身也读出来。核心逻辑伪代码from livekit.agents import tts class AliyunTTS(tts.TTS): def __init__(self, token: str, app_key: str, voice: str zhixiaobai): super().__init__(capabilitiestts.TTSCapabilities(streamingFalse)) self._token token self._app_key app_key self._voice voice async def synthesize(self, text: str) - AsyncIterable[rtc.AudioFrame]: async with connect_aliyun_nls(tokenself._token) as ws: await send_tts_request( ws, app_keyself._app_key, texttext, voiceself._voice, sample_rate16000, ) # 服务端返回的可能是多个二进制音频帧逐个转成AudioFrame async for pcm_chunk in ws.iter_bytes(): yield pcm_to_audio_frame(pcm_chunk, sample_rate16000)如果你需要更流式的体验阿里云也支持文本流式合成也就是一段长文本可以一边合成一边返回音频不需要等整段文本全部处理完。但为了稳定我第一版是用一次文本、一次合成完成的效果已经够用。4. Agent里接入自定义STT/TTS之后的联调与实测4.1 注册自定义STT/TTS到语音Agent写好了适配器接下来把它接入到Agent里。LiveKit Agents提供了一套voice.Agent的高级接口直接传入我们自定义的STT和TTS就行。from livekit.agents import voice from aliyun_bridge import AliyunSTT, AliyunTTS stt_engine AliyunSTT(tokentoken, app_keyapp_key) tts_engine AliyunTTS(tokentoken, app_keyapp_key, voicezhixiaobai) agent voice.Agent( sttstt_engine, llmllm_engine, ttstts_engine, )这里的llm_engine可以是任何OpenAI兼容的大模型接口也可以是你自己部署的模型服务。LiveKit Agents只负责把STT输出的文本交给LLM再把LLM返回的文本交给TTS整体流程非常清晰。4.2 会话流程与VAD的配合接入自定义STT/TTS之后一次典型的语音会话是这样的用户加入房间LiveKit Server把用户音频转发给Agents。Agents内部的VAD语音活动检测判断用户开始说话开始向STT推音频帧。阿里云NLS识别出文本Agents拿到文本后发送给LLM。LLM生成回复文本Agents把文本交给TTS合成语音。TTS合成的音频通过LiveKit播放给用户。这里有个细节LiveKit Agents默认会启用VAD来决定“什么时候把音频送入STT”。如果你的STT自己也做端点检测两者会打架。我踩过一次现象是识别结果断在半句。后来我把STT里的静音检测参数调成跟VAD参数协同让VAD负责切句子STT只负责把音频流持续转写问题就消失了。4.3 首次联调实测数据我在华东1的ECS上部署整套环境实测下来的效果指标实测值备注WebSocket建连耗时120ms左右同地域访问NLS网关首次语音识别返回500-800ms开启中间结果感知会更快TTS首包返回300-500ms收到文本后开始合成单轮会话整体时延1.5-2.5s含LLM推理耗时这个数据跟之前用海外默认服务相比体感提升非常明显。用户测试时明显感觉到“对话是跟得上的”。当然时延数据会因ECS规格、地域、大模型选型不同而波动我这里给的是参考值。5. 部署到阿里云ECS之后网络链路、Token有效期与并发配置5.1 地域选择与访问链路规划如果你的LiveKit Server和Agents部署在国内地域选择直接决定了访问NLS的延迟。我推荐把整套基础设施放在同一个地域甚至同一个可用区。比如Agents跑在华东1杭州的ECS上阿里云NLS也选华东1或华东2的网关这样Agents到NLS的网络路径很短、很稳定。访问链路整体是用户终端 →WSS→ 阿里云SLB/Caddy → LiveKit ServerWebRTC媒体转发 → LiveKit AgentsSTT/LNM/TTS调度 → 阿里云NLS网关ASR/TTS其中用户终端到LiveKit Server这一段走的是WebRTC标准协议国内运营商网络对WebRTC的UDP支持总体还可以但如果遇到UDP被限制的网络环境需要开启LiveKit的TCP/TLS候选来兜底。这个配置可以在LiveKit Server的yaml里设置启用TURN over TCP。5.2 Token管理24小时有效期如何优雅续期阿里云NLS的Token有效期是24小时如果你的Agent进程长期运行不可能手动去换Token。我一开始偷懒启动时获取一次Token就全局复用结果第二天早上线上STT全部失效用户说话没有反应排查了半天才发现是Token过期。后来改成这样启动时从阿里云获取Token缓存到内存。后台启动一个定时任务每隔8小时刷新一次Token避开24小时有效期的截止时间。每次创建NLS连接时从缓存取最新Token。如果调用返回鉴权错误立即触发一次强制刷新并重建连接。import asyncio from datetime import timedelta class TokenManager: def __init__(self, access_key_id: str, access_key_secret: str): self._ak_id access_key_id self._ak_secret access_key_secret self._token None self._lock asyncio.Lock() async def start(self): asyncio.create_task(self._periodic_refresh()) async def _periodic_refresh(self): while True: await asyncio.sleep(timedelta(hours8).total_seconds()) await self.refresh() async def refresh(self): async with self._lock: self._token await self._fetch_token() async def get_token(self): if not self._token: async with self._lock: if not self._token: self._token await self._fetch_token() return self._token这里用锁来避免并发请求时重复刷新Token逻辑不算复杂但能避免很多线上事故。5.3 并发与连接池参数调优阿里云NLS是按并发路数计费的默认可能有几十路的并发上限。如果你的业务会同时进来多个语音会话需要关注并发控制。对LiveKit Agents这一侧我做了两件事限制Agent实例内的并发会话数。比如单实例最多同时处理10路语音会话超出后排队或者扩容新实例。为NLS连接维护一个连接池。ASR和TTS各自维护一组WebSocket连接按需从池里取用完归还。避免每来一路会话就新建连接延迟高还容易触发服务端连接数限制。另外ECS上的文件句柄限制也要检查。每路WebSocket连接会占用一个文件描述符如果ECS的ulimit默认只有1024几十路会话就把句柄耗光了。建议在启动脚本里加上ulimit -n 65535以及在systemd或Docker启动参数里同步放宽限制。6. 我在这个项目里踩过的坑按排查过程还原6.1 用户一开口识别就断VAD和ASR的静音参数互相打架现象用户说“你好”Agent总能收到前半段但后半段识别不出经常只有一个“你”字。排查过程一开始怀疑是网络丢包我看了LiveKit Server的WebRTC统计丢包率在正常范围。接着怀疑是音频帧推送太碎阿里云那边识别不稳定又确认了每帧大小没问题。最后无意中看到Agent日志VAD在用户说完“你”字后判定句子结束停止了向STT推送音频所以阿里云只收到了“你”后面的内容根本没送过去。根因VAD和阿里云NLS都启用了静音检测两个静音阈值叠加导致VAD过早切断了句子。处理方式调整VAD的静音结束阈值让VAD更倾向于保留完整句子。同时把阿里云NLS的max_sentence_silence句内最大静音参数调大两边协同不再各自为政。调到合理参数后识别结果完整了。6.2 识别文本变成乱码采样率与声道没对齐现象阿里云返回的文本内容是乱码比如“你好”识别成“尼浩”这种奇怪的近似音偶尔还有完全无法识别的字符。排查过程这个坑我印象特别深。刚开始我以为是热词没配置但换了常用词也一样。后来我在适配器里把发送给阿里云的音频数据落盘保存用音频工具打开一看播放速度明显偏快音调也偏高——典型的采样率错误。再检查代码发现AudioFrame在某些设备上采样率是48KHz我的重采样函数漏掉了部分情况导致发过去的PCM还是48KHz的数据。阿里云并不知道我发的是48KHz它按照16KHz解码自然全是乱码。根因重采样逻辑覆盖不全个别设备采集参数不标准。处理方式在frame_to_aliyun_pcm里强制检查frame.sample_rate不是16KHz就统一走重采样器并且把声道降混逻辑前置。修完之后识别文本恢复正常。6.3 长时间会话后STT无响应Token过期且没有自动重连现象用户进行了一个很长的会议Agent一开始识别正常大约2小时后突然没有任何识别结果。Agent进程没崩日志也没有异常报错。排查过程这是最难查的一种问题因为从日志看一切正常就是没结果。我看了STT的连接状态发现WebSocket还保持着心跳也正常。后来手动查了一下阿里云Token的创建时间发现会话开始时用的Token已经过期了。阿里云NLS的WebSocket连接如果在会话中途Token过期服务端可能不会主动断开连接而是默默拒绝后续请求导致客户端一直等结果永远等不到。根因Token缓存了我启动时的旧Token定时刷新逻辑没覆盖到长连接场景。处理方式改进TokenManager让它每小时检查一次Token剩余有效期如果剩余时间不足1小时就刷新。同时在STT适配器里监听阿里云返回的错误事件一旦遇到鉴权失败立即重建WebSocket连接并重置音频流状态。这个改动上线后再没出现过长时间会话无识别结果的问题。6.4 静音时段过长导致识别流被服务端掐断现象用户在会议场景中经常会有较长时间不说话过了一段静音后再次说话时识别没有回应。排查过程我看日志发现阿里云服务端在静音持续一段时间后返回了一个TaskFailed事件错误码指向静音超时。NLS实时识别有静音超时保护机制大约30秒左右没有音频数据服务端会主动结束当前识别任务。而LiveKit Agent的VAD认为用户没说满一个句子没有及时停止发送。根因长时间静音触发了服务端超时保护。处理方式在STT适配器里打开一个可配置的心跳机制当检测到相对较长的静音时主动向阿里云发送一次“停止识别再重新开始”的指令也就是手动切割句子。这样既不会中断整个WebSocket连接又能避开服务端的静音超时保护。写在最后从“默认海外语音服务不可用”到“阿里云NLS稳定支撑生产流量”中间的距离并不远但细节确实不少。回头看这个项目最值钱的不是那些WebSocket接口怎么调而是每一步设计背后的网络环境认知和异常处理思路。LiveKit给你的是实时通信的骨架语音能力要靠自己接稳。如果你也在做类似的集成建议从音频格式统一开始一步步推进别想着一口气全接完——先打通STT再通TTS最后才是并发和部署的打磨。