1. 为什么要在Unity里接入Qwen2.5-Omni1.1 从只能看到能听会说的交互升级做过Unity项目的人都有一个体会传统游戏或者数字孪生应用里的NPC、虚拟助手交互方式基本停留在点按钮或者打字输入这个层面。玩家点一下UI程序走一个分支播一段动画结束。这种交互本质上还是人适应机器用户得先学会你的操作逻辑才能获得反馈。Qwen2.5-Omni这类全模态模型带来的变化是根本性的。它同时具备文本理解、语音识别、语音合成、图像理解这几项能力而且是在一个模型里端到端完成的。这意味着你在Unity场景里放一个虚拟角色用户直接对着麦克风说话角色能听懂、能思考、能用带情感的声音回答甚至能结合摄像头画面理解用户当前的环境。这套链路打通之后交互范式就从操作UI变成了和人对话。我最初接触这个需求是给一个展厅项目做虚拟讲解员。客户的要求很朴素参观者走到屏幕前直接问问题讲解员要能答上来声音别太机械。当时评估了几条路线最后选了Qwen2.5-Omni核心原因就是它把ASR、LLM、TTS三件事合并了省掉了中间拼接的工程量和延迟。1.2 全模态能力到底包含哪些可用的功能很多人看到全模态这个词会有点懵不知道具体能调什么。我按实际开发中用到的能力拆一下语音输入理解用户说话模型直接输出文本回复中间不需要你单独接一个语音识别服务。这对中文口语、带口音的普通话支持都不错。语音输出合成模型可以生成音频流音色自然支持多说话人。你不需要再去找TTS引擎。图文混合理解传入图片加文本问题模型能描述画面内容、识别物体、回答关于图片的问题。展厅场景里可以用来识别参观者手里的展品。流式输出文本和音频都支持流式返回这对实时交互体验至关重要用户不用等整段生成完才听到声音。需要说明的是Qwen2.5-Omni的视觉理解是图片级别的不是视频流级别的连续理解。如果你要做实时视频分析得自己按帧抽图再送进去这个后面会讲怎么处理。1.3 什么样的Unity项目适合上这套方案不是所有项目都值得接大模型。我总结了几类真正有收益的场景场景类型典型需求接入价值数字展厅/展馆虚拟讲解员、问答互动高替代人工讲解教育类应用口语陪练、智能答疑高实时语音交互是刚需数字孪生语音控制场景、设备问答中高解放双手操作游戏NPC自由对话、剧情互动中取决于对话深度需求智能座舱Demo语音助手原型高接近真实产品形态反过来如果你的项目只是需要固定几句语音提示那用预录音频就够了没必要上大模型成本和复杂度都不划算。判断标准很简单交互是否需要理解自然语言和生成非固定内容。只要答案是肯定的这套方案就有价值。2. 接入前的技术选型与环境准备2.1 走API还是本地部署这是个成本问题Qwen2.5-Omni的接入方式主要有两条路调用云端API或者本地部署推理服务。这两条路的取舍直接决定了你整个项目的架构。云端API的好处是省事你不需要关心GPU、显存、模型加载这些事一个HTTP请求或者WebSocket连接就能用。缺点是依赖网络有调用成本而且音频数据要上传到远端。对于展厅、教育这类对延迟敏感但能接受联网的场景API是首选。本地部署适合数据不能出内网、或者调用量极大想摊薄成本的场景。但Qwen2.5-Omni这个体量的模型本地跑起来对硬件要求不低至少需要一张大显存的显卡而且推理框架的配置有一定门槛。我个人的建议是原型阶段一律先用API跑通链路等交互逻辑验证完了再评估要不要转本地。2.2 Unity端的网络通信方案怎么选Unity里做网络请求常见的有UnityWebRequest、HttpClient以及各种WebSocket库。针对Qwen2.5-Omni的流式特性我的选型建议是这样的纯文本问答UnityWebRequest就够用简单直接注意放在协程里别阻塞主线程。流式文本音频必须用WebSocket。因为流式返回是一段一段推过来的HTTP的请求-响应模式处理起来很别扭。音频采集与播放采集用Microphone类播放用AudioSource配合流式写入或者用OnAudioRead回调做实时播放。这里有个坑要提前说Unity的Microphone类在部分平台上采样率是固定的而Qwen2.5-Omni对输入音频有格式要求通常是16kHz、单声道、PCM。你采集到的音频往往需要重采样。这个重采样如果做得粗糙识别准确率会明显下降。后面我会专门讲怎么处理。2.3 音频格式这件事比想象中重要我见过太多人卡在音频格式上。Qwen2.5-Omni的语音输入一般要求16kHz采样率、16位深、单声道PCM数据。而Unity的Microphone默认可能是44.1kHz或48kHz还是双声道。处理思路是采集时尽量指定16kHz如果平台不支持就采集后做降采样。降采样不是简单丢样本要做低通滤波再抽取否则会有混叠噪声。实际项目里我用的是一个简单的线性插值重采样效果够用代码量也小。如果你对音质要求高可以上更专业的重采样算法但大多数语音识别场景线性插值已经能跑出不错的识别率。音频编码方面如果走API通常需要把PCM数据做Base64编码或者封装成WAV格式再传。WAV的好处是自带头信息服务端解析方便。我一般是在Unity端把PCM加上44字节的WAV头直接传WAV。3. Unity端语音采集与数据管线的搭建3.1 麦克风采集的初始化与权限处理Unity里用Microphone类采集音频第一步是检查设备。Microphone.devices返回可用设备列表展厅项目里经常遇到多个麦克风的情况得让用户或者配置指定用哪个。// 检查并选择麦克风设备 string[] devices Microphone.devices; if (devices.Length 0) { Debug.LogError(未检测到麦克风设备); return; } // 优先选择名称包含指定关键字的设备 string targetDevice devices[0]; foreach (var d in devices) { if (d.Contains(USB)) { targetDevice d; break; } }权限这块PC平台一般不用特别处理但如果是移动端或者WebGL必须在使用前请求麦克风权限。WebGL平台尤其要注意浏览器要求用户主动交互比如点击按钮之后才能启动麦克风不能在场景加载时自动开。初始化采集时Microphone.Start(deviceName, loop, lengthSec, frequency)这几个参数要仔细设。lengthSec是环形缓冲区的长度设太短会丢数据设太长占内存。我一般设1到2秒配合一个读取指针循环取数据。frequency尽量设16000如果设备不支持Unity会自动用最接近的值这时候你就得在读取后做重采样。3.2 把采集到的音频切成可发送的片段实时语音交互不是等用户说完一整段才发送而是要做语音活动检测VAD检测到用户开始说话就采集检测到停顿就切一段发出去。这样交互才自然。VAD的实现有简有繁。简单做法是算音频的RMS均方根能量超过阈值认为在说话低于阈值持续一段时间认为说完了。这个方案在安静环境够用但展厅这种嘈杂环境容易误触发。复杂一点可以用WebRTC的VAD算法或者干脆用模型自带的端点检测。我实际项目里用的是能量阈值加静音计时的组合// 简化的VAD逻辑 float rms CalculateRMS(samples); if (rms speakThreshold) { silenceTimer 0f; isSpeaking true; } else if (isSpeaking) { silenceTimer Time.deltaTime; if (silenceTimer 0.8f) { // 静音超过0.8秒认为说完 isSpeaking false; SendAudioSegment(); } }阈值和静音时长这两个参数需要根据实际环境调。展厅环境我一般把阈值调高一点静音时长设0.8到1.2秒太短会把用户换气的停顿当成结束太长又显得反应慢。3.3 音频重采样与WAV封装的实操细节前面提到采集到的音频可能需要重采样。这里给一个我常用的线性插值重采样实现思路// 将sourceRate的音频重采样到targetRate float ratio (float)sourceRate / targetRate; int targetLength (int)(sourceSamples.Length / ratio); float[] target new float[targetLength]; for (int i 0; i targetLength; i) { float srcIndex i * ratio; int idx0 (int)srcIndex; int idx1 Mathf.Min(idx0 1, sourceSamples.Length - 1); float frac srcIndex - idx0; target[i] Mathf.Lerp(sourceSamples[idx0], sourceSamples[idx1], frac); }重采样之后是WAV封装。WAV头是44字节包含RIFF标识、文件大小、格式块、数据块等信息。关键字段是采样率、声道数、位深。封装的时候注意字节序WAV是小端序Unity的BitConverter默认就是小端直接写就行。// 写WAV头的关键部分 byte[] header new byte[44]; // RIFF 文件长度 WAVE // fmt 格式块长度 音频格式 声道数 采样率 字节率 块对齐 位深 // data 数据长度封装好的WAV字节数组如果是走API通常还要做Base64编码。Base64会让数据膨胀约33%但传输方便。如果走WebSocket二进制帧可以直接传原始字节省掉编码开销。4. 与Qwen2.5-Omni服务端的对接实现4.1 请求结构的设计与多模态数据的组织Qwen2.5-Omni的请求通常是一个JSON结构里面包含消息数组。每条消息有角色user/assistant/system和内容。内容可以是纯文本也可以是文本加音频、文本加图片的混合。一个典型的语音问答请求长这样{ model: qwen2.5-omni, messages: [ { role: user, content: [ {type: input_audio, audio: base64编码的音频数据}, {type: text, text: 请用简洁的语言回答} ] } ], stream: true }注意这里的content是个数组可以混合多种模态。如果你要做图文理解就把图片的Base64或者URL放进去。系统提示词system message可以用来设定角色性格、回答风格这个在虚拟讲解员场景里很有用比如设定你是一位专业的展厅讲解员回答要口语化、亲切。4.2 WebSocket流式接收与音频流的处理流式模式下服务端会一段一段返回数据。文本片段和音频片段是分开的需要你在客户端做区分和拼接。文本流处理相对简单收到一段就追加到显示缓冲区UI上做打字机效果。音频流处理麻烦一些因为音频是分块的你得把每块音频数据按顺序写入播放缓冲区。我的做法是维护一个音频队列收到音频块就入队播放线程从队列取数据播放。这样即使网络有抖动播放也不会断断续续。队列长度要控制太长会导致延迟累积太短又容易断音。一般控制在200到500毫秒的缓冲量比较合适。// 音频块入队 void OnAudioChunkReceived(byte[] audioData) { lock (audioQueue) { audioQueue.Enqueue(audioData); } } // 播放线程从队列取数据写入AudioSource这里有个细节流式返回的音频块可能是PCM裸数据也可能是某种编码格式。如果是PCM直接写入AudioClip就行如果是压缩格式得先解码。具体看服务端返回的格式说明别想当然。4.3 错误处理与重连机制网络请求一定会出问题尤其是展厅这种长时间运行的环境。我踩过的坑包括网络抖动导致WebSocket断开、服务端限流返回错误、音频数据过大被截断。处理策略分几层连接层WebSocket断开后自动重连重连间隔做指数退避避免频繁重连打爆服务端。请求层单次请求失败做有限次重试重试前检查是不是音频格式问题别盲目重试。业务层给用户友好的提示比如网络有点问题请再说一遍而不是弹一堆错误码。// 指数退避重连 int retryCount 0; float retryDelay 1f; while (!connected retryCount maxRetry) { yield return new WaitForSeconds(retryDelay); retryDelay Mathf.Min(retryDelay * 2, 30f); retryCount; Connect(); }还有一个容易被忽略的点请求超时。语音交互对延迟敏感如果服务端响应超过几秒用户体感就很差。我一般设一个5到8秒的超时超时后取消请求并提示用户重试。5. 语音交互体验的打磨与性能优化5.1 降低端到端延迟的几个关键手段语音交互最影响体验的就是延迟。从用户说完到听到回答如果超过2秒就会觉得卡。我实测下来延迟主要来自几个环节音频采集缓冲、网络传输、模型推理、音频播放缓冲。优化手段按收益排序缩短VAD静音判定时间从1.2秒降到0.8秒直接省0.4秒。但别降太狠否则会把用户正常停顿切断。启用流式输出文本和音频都流式用户能第一时间听到开头感知延迟大幅降低。音频采集缓冲区调小采集缓冲从2秒降到0.5秒减少等待。播放缓冲控制播放端缓冲别设太大200毫秒左右即可。这几项加起来端到端延迟能从3秒多压到1.5秒以内体感提升非常明显。5.2 音频播放的实时性与断音问题流式音频播放最容易出的问题是断音就是播放到一半卡一下。原因通常是播放缓冲空了网络数据还没到。解决办法是做一个预缓冲收到第一批音频数据后先攒够一定量比如300毫秒再开始播放这样后续即使网络有波动也有缓冲垫着。代价是开头多等300毫秒但换来的是播放流畅值得。另一个断音原因是Unity主线程卡顿。音频播放如果放在主线程场景里一有复杂计算就会卡。建议把音频写入放在独立线程或者用Unity的音频线程回调别和渲染、逻辑抢主线程。5.3 多模态输入时的资源管理如果项目里还要传图片给模型做理解资源管理就得上心。图片Base64编码后体积不小频繁传大图会拖慢请求。我的做法是传之前先把图片压缩到合理尺寸一般长边不超过1024像素就够了再大模型也看不出更多细节。压缩用Unity的Texture2D.EncodeToJPG质量设70到80体积能降一个数量级。还有内存管理。音频和图片的字节数组用完要及时释放别一直挂在内存里。展厅项目连续运行几天内存泄漏会累积成大问题。用using或者手动置null配合GC基本能控制住。6. 实战中踩过的坑与排查思路6.1 识别率忽高忽低问题出在采样率项目上线初期遇到一个诡异现象同样的语音有时候识别得很准有时候完全识别错。排查了半天最后定位到采样率。原因是不同设备的麦克风默认采样率不一样有的16kHz有的48kHz。我的重采样代码在16kHz设备上不触发在48kHz设备上触发但重采样实现有个边界bug导致部分数据错位。修复后识别率就稳定了。这个坑的教训是永远不要假设采集设备的采样率一定要在运行时读取实际采样率再做对应处理。而且重采样代码要单独测试用已知频率的正弦波验证输出是否正确。6.2 WebSocket在部分平台上的兼容性问题Unity的WebSocket在不同平台表现不一致。PC上跑得好好的打包到WebGL就出问题。WebGL平台的WebSocket是浏览器原生实现不支持某些自定义头而且对二进制帧的处理和PC端有差异。解决办法是WebGL平台单独走一套逻辑用浏览器的WebSocket API通过jslib桥接。或者干脆WebGL平台降级用HTTP轮询牺牲一点实时性换兼容性。移动端也有坑主要是后台切换时连接会断。得监听应用焦点变化切回前台时检查连接状态并重连。6.3 长连接下的内存与句柄泄漏长时间运行的项目WebSocket连接如果管理不当会出现句柄泄漏。表现是运行几小时后连接数越来越多最后服务端拒绝新连接。根因通常是断开连接时没有正确释放资源。每次重连都新建一个WebSocket对象旧的没关干净。修复方法是确保每次断开都调用Close和Dispose并且用一个连接管理器统一管理避免多处创建连接。// 连接管理器确保单例和正确释放 void Dispose() { if (ws ! null) { ws.Close(); ws.Dispose(); ws null; } }6.4 服务端返回音频格式与预期不符有一次服务端升级返回的音频格式从PCM变成了某种压缩格式客户端直接播放出一堆噪音。排查时先抓包看返回数据的头部确认格式再对应调整解码逻辑。这个坑提醒我对接第三方服务时一定要对返回数据做格式校验别假设格式永远不变。可以在客户端加一个格式检测发现不符就记录日志并降级处理而不是直接崩溃。7. 从Demo到产品还需要补哪些课7.1 对话上下文的管理策略Demo阶段往往是一问一答没有上下文。但真实交互里用户会说那它呢再详细说说这些都需要模型记住前面的对话。Qwen2.5-Omni支持多轮对话你需要把历史消息一起传过去。但历史不能无限累积否则请求越来越大延迟越来越高。我的做法是保留最近N轮对话N一般设5到10轮超出就丢弃最早的。同时可以做一个摘要机制把久远的对话压缩成一句话摘要保留兼顾上下文和性能。7.2 打断机制与双工交互真实对话里用户会在AI说话时打断。如果AI一直说个不停体验很差。实现打断需要播放音频时持续监听麦克风检测到用户说话就立即停止播放并开始新一轮采集。这个逻辑听起来简单做起来有几个细节停止播放要立即不能等当前音频块播完采集要清空之前的缓冲避免把AI的声音录进去状态机要清晰避免打断和正常采集逻辑打架。7.3 内容安全与合规的兜底任何面向公众的语音交互产品都得考虑内容安全。模型可能生成不合适的内容或者用户输入敏感信息。需要在客户端和服务端都做过滤。客户端可以做基础的敏感词检测服务端一般有内容审核接口。另外系统提示词里要明确约束模型的回答范围比如只回答与展品相关的问题。这不能百分百防住但能挡掉大部分跑偏的情况。7.4 离线降级方案的必要性网络不可能永远稳定。展厅项目如果网络断了虚拟讲解员直接哑掉体验很糟。所以要有降级方案网络不可用时切换到本地预置的问答库至少能回答常见问题。降级方案的触发要平滑用户感知不到切换。可以做一个健康检查定期探测服务可用性不可用就切本地恢复了再切回来。8. 一些个人经验与后续扩展方向这套方案我在两个项目里落地过一个是展厅讲解员一个是教育类的口语陪练。整体跑下来Qwen2.5-Omni的全模态能力确实省了很多拼接工作尤其是语音识别和合成一体化延迟和稳定性都比自己拼三套服务好。如果让我给准备入坑的人一句建议那就是先把音频链路跑通再谈模型。我见过太多人一上来就研究模型参数、提示词工程结果卡在麦克风采集和格式转换上。音频这条链路看着简单实际坑最多采样率、声道、位深、字节序、重采样每一项都能让你调半天。把这条链路用固定音频文件测通了再接实时采集再接模型一步步来成功率最高。后续扩展的话有几个方向值得试一是结合场景里的物体识别让虚拟角色能看到用户在指什么二是接入数字人驱动让口型跟语音同步视觉上更自然三是做多角色对话场景里多个NPC各自有性格能互相交流。这些都是在现有链路上做加法基础打好了扩展起来并不难。最后分享一个小技巧调试语音交互时把每次请求的音频存成WAV文件落盘出问题时可以回放对比。这个习惯帮我定位过好几次偶发识别错误最后发现都是特定环境噪音导致的针对性加了降噪就解决了。 Unity接入Qwen2.5-Omni全模态大模型：语音交互实战指南
1. 为什么要在Unity里接入Qwen2.5-Omni1.1 从只能看到能听会说的交互升级做过Unity项目的人都有一个体会传统游戏或者数字孪生应用里的NPC、虚拟助手交互方式基本停留在点按钮或者打字输入这个层面。玩家点一下UI程序走一个分支播一段动画结束。这种交互本质上还是人适应机器用户得先学会你的操作逻辑才能获得反馈。Qwen2.5-Omni这类全模态模型带来的变化是根本性的。它同时具备文本理解、语音识别、语音合成、图像理解这几项能力而且是在一个模型里端到端完成的。这意味着你在Unity场景里放一个虚拟角色用户直接对着麦克风说话角色能听懂、能思考、能用带情感的声音回答甚至能结合摄像头画面理解用户当前的环境。这套链路打通之后交互范式就从操作UI变成了和人对话。我最初接触这个需求是给一个展厅项目做虚拟讲解员。客户的要求很朴素参观者走到屏幕前直接问问题讲解员要能答上来声音别太机械。当时评估了几条路线最后选了Qwen2.5-Omni核心原因就是它把ASR、LLM、TTS三件事合并了省掉了中间拼接的工程量和延迟。1.2 全模态能力到底包含哪些可用的功能很多人看到全模态这个词会有点懵不知道具体能调什么。我按实际开发中用到的能力拆一下语音输入理解用户说话模型直接输出文本回复中间不需要你单独接一个语音识别服务。这对中文口语、带口音的普通话支持都不错。语音输出合成模型可以生成音频流音色自然支持多说话人。你不需要再去找TTS引擎。图文混合理解传入图片加文本问题模型能描述画面内容、识别物体、回答关于图片的问题。展厅场景里可以用来识别参观者手里的展品。流式输出文本和音频都支持流式返回这对实时交互体验至关重要用户不用等整段生成完才听到声音。需要说明的是Qwen2.5-Omni的视觉理解是图片级别的不是视频流级别的连续理解。如果你要做实时视频分析得自己按帧抽图再送进去这个后面会讲怎么处理。1.3 什么样的Unity项目适合上这套方案不是所有项目都值得接大模型。我总结了几类真正有收益的场景场景类型典型需求接入价值数字展厅/展馆虚拟讲解员、问答互动高替代人工讲解教育类应用口语陪练、智能答疑高实时语音交互是刚需数字孪生语音控制场景、设备问答中高解放双手操作游戏NPC自由对话、剧情互动中取决于对话深度需求智能座舱Demo语音助手原型高接近真实产品形态反过来如果你的项目只是需要固定几句语音提示那用预录音频就够了没必要上大模型成本和复杂度都不划算。判断标准很简单交互是否需要理解自然语言和生成非固定内容。只要答案是肯定的这套方案就有价值。2. 接入前的技术选型与环境准备2.1 走API还是本地部署这是个成本问题Qwen2.5-Omni的接入方式主要有两条路调用云端API或者本地部署推理服务。这两条路的取舍直接决定了你整个项目的架构。云端API的好处是省事你不需要关心GPU、显存、模型加载这些事一个HTTP请求或者WebSocket连接就能用。缺点是依赖网络有调用成本而且音频数据要上传到远端。对于展厅、教育这类对延迟敏感但能接受联网的场景API是首选。本地部署适合数据不能出内网、或者调用量极大想摊薄成本的场景。但Qwen2.5-Omni这个体量的模型本地跑起来对硬件要求不低至少需要一张大显存的显卡而且推理框架的配置有一定门槛。我个人的建议是原型阶段一律先用API跑通链路等交互逻辑验证完了再评估要不要转本地。2.2 Unity端的网络通信方案怎么选Unity里做网络请求常见的有UnityWebRequest、HttpClient以及各种WebSocket库。针对Qwen2.5-Omni的流式特性我的选型建议是这样的纯文本问答UnityWebRequest就够用简单直接注意放在协程里别阻塞主线程。流式文本音频必须用WebSocket。因为流式返回是一段一段推过来的HTTP的请求-响应模式处理起来很别扭。音频采集与播放采集用Microphone类播放用AudioSource配合流式写入或者用OnAudioRead回调做实时播放。这里有个坑要提前说Unity的Microphone类在部分平台上采样率是固定的而Qwen2.5-Omni对输入音频有格式要求通常是16kHz、单声道、PCM。你采集到的音频往往需要重采样。这个重采样如果做得粗糙识别准确率会明显下降。后面我会专门讲怎么处理。2.3 音频格式这件事比想象中重要我见过太多人卡在音频格式上。Qwen2.5-Omni的语音输入一般要求16kHz采样率、16位深、单声道PCM数据。而Unity的Microphone默认可能是44.1kHz或48kHz还是双声道。处理思路是采集时尽量指定16kHz如果平台不支持就采集后做降采样。降采样不是简单丢样本要做低通滤波再抽取否则会有混叠噪声。实际项目里我用的是一个简单的线性插值重采样效果够用代码量也小。如果你对音质要求高可以上更专业的重采样算法但大多数语音识别场景线性插值已经能跑出不错的识别率。音频编码方面如果走API通常需要把PCM数据做Base64编码或者封装成WAV格式再传。WAV的好处是自带头信息服务端解析方便。我一般是在Unity端把PCM加上44字节的WAV头直接传WAV。3. Unity端语音采集与数据管线的搭建3.1 麦克风采集的初始化与权限处理Unity里用Microphone类采集音频第一步是检查设备。Microphone.devices返回可用设备列表展厅项目里经常遇到多个麦克风的情况得让用户或者配置指定用哪个。// 检查并选择麦克风设备 string[] devices Microphone.devices; if (devices.Length 0) { Debug.LogError(未检测到麦克风设备); return; } // 优先选择名称包含指定关键字的设备 string targetDevice devices[0]; foreach (var d in devices) { if (d.Contains(USB)) { targetDevice d; break; } }权限这块PC平台一般不用特别处理但如果是移动端或者WebGL必须在使用前请求麦克风权限。WebGL平台尤其要注意浏览器要求用户主动交互比如点击按钮之后才能启动麦克风不能在场景加载时自动开。初始化采集时Microphone.Start(deviceName, loop, lengthSec, frequency)这几个参数要仔细设。lengthSec是环形缓冲区的长度设太短会丢数据设太长占内存。我一般设1到2秒配合一个读取指针循环取数据。frequency尽量设16000如果设备不支持Unity会自动用最接近的值这时候你就得在读取后做重采样。3.2 把采集到的音频切成可发送的片段实时语音交互不是等用户说完一整段才发送而是要做语音活动检测VAD检测到用户开始说话就采集检测到停顿就切一段发出去。这样交互才自然。VAD的实现有简有繁。简单做法是算音频的RMS均方根能量超过阈值认为在说话低于阈值持续一段时间认为说完了。这个方案在安静环境够用但展厅这种嘈杂环境容易误触发。复杂一点可以用WebRTC的VAD算法或者干脆用模型自带的端点检测。我实际项目里用的是能量阈值加静音计时的组合// 简化的VAD逻辑 float rms CalculateRMS(samples); if (rms speakThreshold) { silenceTimer 0f; isSpeaking true; } else if (isSpeaking) { silenceTimer Time.deltaTime; if (silenceTimer 0.8f) { // 静音超过0.8秒认为说完 isSpeaking false; SendAudioSegment(); } }阈值和静音时长这两个参数需要根据实际环境调。展厅环境我一般把阈值调高一点静音时长设0.8到1.2秒太短会把用户换气的停顿当成结束太长又显得反应慢。3.3 音频重采样与WAV封装的实操细节前面提到采集到的音频可能需要重采样。这里给一个我常用的线性插值重采样实现思路// 将sourceRate的音频重采样到targetRate float ratio (float)sourceRate / targetRate; int targetLength (int)(sourceSamples.Length / ratio); float[] target new float[targetLength]; for (int i 0; i targetLength; i) { float srcIndex i * ratio; int idx0 (int)srcIndex; int idx1 Mathf.Min(idx0 1, sourceSamples.Length - 1); float frac srcIndex - idx0; target[i] Mathf.Lerp(sourceSamples[idx0], sourceSamples[idx1], frac); }重采样之后是WAV封装。WAV头是44字节包含RIFF标识、文件大小、格式块、数据块等信息。关键字段是采样率、声道数、位深。封装的时候注意字节序WAV是小端序Unity的BitConverter默认就是小端直接写就行。// 写WAV头的关键部分 byte[] header new byte[44]; // RIFF 文件长度 WAVE // fmt 格式块长度 音频格式 声道数 采样率 字节率 块对齐 位深 // data 数据长度封装好的WAV字节数组如果是走API通常还要做Base64编码。Base64会让数据膨胀约33%但传输方便。如果走WebSocket二进制帧可以直接传原始字节省掉编码开销。4. 与Qwen2.5-Omni服务端的对接实现4.1 请求结构的设计与多模态数据的组织Qwen2.5-Omni的请求通常是一个JSON结构里面包含消息数组。每条消息有角色user/assistant/system和内容。内容可以是纯文本也可以是文本加音频、文本加图片的混合。一个典型的语音问答请求长这样{ model: qwen2.5-omni, messages: [ { role: user, content: [ {type: input_audio, audio: base64编码的音频数据}, {type: text, text: 请用简洁的语言回答} ] } ], stream: true }注意这里的content是个数组可以混合多种模态。如果你要做图文理解就把图片的Base64或者URL放进去。系统提示词system message可以用来设定角色性格、回答风格这个在虚拟讲解员场景里很有用比如设定你是一位专业的展厅讲解员回答要口语化、亲切。4.2 WebSocket流式接收与音频流的处理流式模式下服务端会一段一段返回数据。文本片段和音频片段是分开的需要你在客户端做区分和拼接。文本流处理相对简单收到一段就追加到显示缓冲区UI上做打字机效果。音频流处理麻烦一些因为音频是分块的你得把每块音频数据按顺序写入播放缓冲区。我的做法是维护一个音频队列收到音频块就入队播放线程从队列取数据播放。这样即使网络有抖动播放也不会断断续续。队列长度要控制太长会导致延迟累积太短又容易断音。一般控制在200到500毫秒的缓冲量比较合适。// 音频块入队 void OnAudioChunkReceived(byte[] audioData) { lock (audioQueue) { audioQueue.Enqueue(audioData); } } // 播放线程从队列取数据写入AudioSource这里有个细节流式返回的音频块可能是PCM裸数据也可能是某种编码格式。如果是PCM直接写入AudioClip就行如果是压缩格式得先解码。具体看服务端返回的格式说明别想当然。4.3 错误处理与重连机制网络请求一定会出问题尤其是展厅这种长时间运行的环境。我踩过的坑包括网络抖动导致WebSocket断开、服务端限流返回错误、音频数据过大被截断。处理策略分几层连接层WebSocket断开后自动重连重连间隔做指数退避避免频繁重连打爆服务端。请求层单次请求失败做有限次重试重试前检查是不是音频格式问题别盲目重试。业务层给用户友好的提示比如网络有点问题请再说一遍而不是弹一堆错误码。// 指数退避重连 int retryCount 0; float retryDelay 1f; while (!connected retryCount maxRetry) { yield return new WaitForSeconds(retryDelay); retryDelay Mathf.Min(retryDelay * 2, 30f); retryCount; Connect(); }还有一个容易被忽略的点请求超时。语音交互对延迟敏感如果服务端响应超过几秒用户体感就很差。我一般设一个5到8秒的超时超时后取消请求并提示用户重试。5. 语音交互体验的打磨与性能优化5.1 降低端到端延迟的几个关键手段语音交互最影响体验的就是延迟。从用户说完到听到回答如果超过2秒就会觉得卡。我实测下来延迟主要来自几个环节音频采集缓冲、网络传输、模型推理、音频播放缓冲。优化手段按收益排序缩短VAD静音判定时间从1.2秒降到0.8秒直接省0.4秒。但别降太狠否则会把用户正常停顿切断。启用流式输出文本和音频都流式用户能第一时间听到开头感知延迟大幅降低。音频采集缓冲区调小采集缓冲从2秒降到0.5秒减少等待。播放缓冲控制播放端缓冲别设太大200毫秒左右即可。这几项加起来端到端延迟能从3秒多压到1.5秒以内体感提升非常明显。5.2 音频播放的实时性与断音问题流式音频播放最容易出的问题是断音就是播放到一半卡一下。原因通常是播放缓冲空了网络数据还没到。解决办法是做一个预缓冲收到第一批音频数据后先攒够一定量比如300毫秒再开始播放这样后续即使网络有波动也有缓冲垫着。代价是开头多等300毫秒但换来的是播放流畅值得。另一个断音原因是Unity主线程卡顿。音频播放如果放在主线程场景里一有复杂计算就会卡。建议把音频写入放在独立线程或者用Unity的音频线程回调别和渲染、逻辑抢主线程。5.3 多模态输入时的资源管理如果项目里还要传图片给模型做理解资源管理就得上心。图片Base64编码后体积不小频繁传大图会拖慢请求。我的做法是传之前先把图片压缩到合理尺寸一般长边不超过1024像素就够了再大模型也看不出更多细节。压缩用Unity的Texture2D.EncodeToJPG质量设70到80体积能降一个数量级。还有内存管理。音频和图片的字节数组用完要及时释放别一直挂在内存里。展厅项目连续运行几天内存泄漏会累积成大问题。用using或者手动置null配合GC基本能控制住。6. 实战中踩过的坑与排查思路6.1 识别率忽高忽低问题出在采样率项目上线初期遇到一个诡异现象同样的语音有时候识别得很准有时候完全识别错。排查了半天最后定位到采样率。原因是不同设备的麦克风默认采样率不一样有的16kHz有的48kHz。我的重采样代码在16kHz设备上不触发在48kHz设备上触发但重采样实现有个边界bug导致部分数据错位。修复后识别率就稳定了。这个坑的教训是永远不要假设采集设备的采样率一定要在运行时读取实际采样率再做对应处理。而且重采样代码要单独测试用已知频率的正弦波验证输出是否正确。6.2 WebSocket在部分平台上的兼容性问题Unity的WebSocket在不同平台表现不一致。PC上跑得好好的打包到WebGL就出问题。WebGL平台的WebSocket是浏览器原生实现不支持某些自定义头而且对二进制帧的处理和PC端有差异。解决办法是WebGL平台单独走一套逻辑用浏览器的WebSocket API通过jslib桥接。或者干脆WebGL平台降级用HTTP轮询牺牲一点实时性换兼容性。移动端也有坑主要是后台切换时连接会断。得监听应用焦点变化切回前台时检查连接状态并重连。6.3 长连接下的内存与句柄泄漏长时间运行的项目WebSocket连接如果管理不当会出现句柄泄漏。表现是运行几小时后连接数越来越多最后服务端拒绝新连接。根因通常是断开连接时没有正确释放资源。每次重连都新建一个WebSocket对象旧的没关干净。修复方法是确保每次断开都调用Close和Dispose并且用一个连接管理器统一管理避免多处创建连接。// 连接管理器确保单例和正确释放 void Dispose() { if (ws ! null) { ws.Close(); ws.Dispose(); ws null; } }6.4 服务端返回音频格式与预期不符有一次服务端升级返回的音频格式从PCM变成了某种压缩格式客户端直接播放出一堆噪音。排查时先抓包看返回数据的头部确认格式再对应调整解码逻辑。这个坑提醒我对接第三方服务时一定要对返回数据做格式校验别假设格式永远不变。可以在客户端加一个格式检测发现不符就记录日志并降级处理而不是直接崩溃。7. 从Demo到产品还需要补哪些课7.1 对话上下文的管理策略Demo阶段往往是一问一答没有上下文。但真实交互里用户会说那它呢再详细说说这些都需要模型记住前面的对话。Qwen2.5-Omni支持多轮对话你需要把历史消息一起传过去。但历史不能无限累积否则请求越来越大延迟越来越高。我的做法是保留最近N轮对话N一般设5到10轮超出就丢弃最早的。同时可以做一个摘要机制把久远的对话压缩成一句话摘要保留兼顾上下文和性能。7.2 打断机制与双工交互真实对话里用户会在AI说话时打断。如果AI一直说个不停体验很差。实现打断需要播放音频时持续监听麦克风检测到用户说话就立即停止播放并开始新一轮采集。这个逻辑听起来简单做起来有几个细节停止播放要立即不能等当前音频块播完采集要清空之前的缓冲避免把AI的声音录进去状态机要清晰避免打断和正常采集逻辑打架。7.3 内容安全与合规的兜底任何面向公众的语音交互产品都得考虑内容安全。模型可能生成不合适的内容或者用户输入敏感信息。需要在客户端和服务端都做过滤。客户端可以做基础的敏感词检测服务端一般有内容审核接口。另外系统提示词里要明确约束模型的回答范围比如只回答与展品相关的问题。这不能百分百防住但能挡掉大部分跑偏的情况。7.4 离线降级方案的必要性网络不可能永远稳定。展厅项目如果网络断了虚拟讲解员直接哑掉体验很糟。所以要有降级方案网络不可用时切换到本地预置的问答库至少能回答常见问题。降级方案的触发要平滑用户感知不到切换。可以做一个健康检查定期探测服务可用性不可用就切本地恢复了再切回来。8. 一些个人经验与后续扩展方向这套方案我在两个项目里落地过一个是展厅讲解员一个是教育类的口语陪练。整体跑下来Qwen2.5-Omni的全模态能力确实省了很多拼接工作尤其是语音识别和合成一体化延迟和稳定性都比自己拼三套服务好。如果让我给准备入坑的人一句建议那就是先把音频链路跑通再谈模型。我见过太多人一上来就研究模型参数、提示词工程结果卡在麦克风采集和格式转换上。音频这条链路看着简单实际坑最多采样率、声道、位深、字节序、重采样每一项都能让你调半天。把这条链路用固定音频文件测通了再接实时采集再接模型一步步来成功率最高。后续扩展的话有几个方向值得试一是结合场景里的物体识别让虚拟角色能看到用户在指什么二是接入数字人驱动让口型跟语音同步视觉上更自然三是做多角色对话场景里多个NPC各自有性格能互相交流。这些都是在现有链路上做加法基础打好了扩展起来并不难。最后分享一个小技巧调试语音交互时把每次请求的音频存成WAV文件落盘出问题时可以回放对比。这个习惯帮我定位过好几次偶发识别错误最后发现都是特定环境噪音导致的针对性加了降噪就解决了。