落鱼科技头像
【Web 语音智能体接入:用 XingyunAvatarAgent 处理语音回调与会话状态】封面图

【Web 语音智能体接入:用 XingyunAvatarAgent 处理语音回调与会话状态】

语音智能体接入:回调、播报与打断

以 XingyunAvatarAgent 为例,梳理初始化、语音回调、流式展示与会话状态。

“模型已经输出完了,页面能显示本轮结束吗?”

接语音智能体时,这个问题很容易被低估。一次问答至少包含请求发送、模型生成、语音与动作表达几个过程。把其中任意一步当作整轮结束,都可能让界面状态提前变化。

还有两个常见问题:ASR 已经自动进入对话,业务又提交了一次相同文本;页面离开后,会话或麦克风资源没有及时释放。

本文使用魔珐星云的 XingyunAvatarAgent 端到端 SDK 作为接入示例,重点讨论这些状态与事件如何处理。示例依据 SDK 文档整理,不包含真实设备上的延迟、识别率或自然语音打断测试,也不把文档能力等同于实测结果。

阅读前先确定边界

本文的示例运行在 Web 中,涉及文本问答、语音输入、回复展示、客户端打断和会话销毁。视觉感知、机器人运动控制、跨终端记忆同步,需要各自的设备与业务接入,不会因为这段 Web 代码运行成功而自动具备。

如果想从头跟着本文体验,也可以通过我的专属链接进入魔珐星云,在注册页面填写:

邀请码:JSUAY3IS96

快速开始:https://media.xingyun3d.com/learning/index.html

01 先让它开口:换到新的 Agent 入口

如果你之前接过旧版 XmovAvatar,应该熟悉这种分工:业务拿到 ASR 的识别结果,交给大模型,再把回复拼成 SSML,调用 speak()。

到了新版 XingyunAvatarAgent,文本对话和语音输入都有了对应入口。我们先准备一个有明确尺寸的容器,再引入端到端 SDK:

<div id="avatar"
     style="width:100%;height:520px"></div>

<button id="start-asr">开始语音</button>
<button id="stop-asr">停止收音</button>
<button id="interrupt">打断表达</button>
<button id="destroy">结束会话</button>

<p id="asr-text"></p>
<p id="answer-text"></p>
<p id="conversation-state"></p>

<script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar_e2e@latest.js"></script>

下文的 JavaScript 可放在这些节点之后的 <script type="module"> 中,以使用顶层 await。先在平台侧准备好角色、音色及智脑等应用配置,再替换下面的 appId、appSecret。示例用于接入验证,真实凭据不要提交到公开仓库;生产环境按项目的鉴权方案处理。

const agent = new window.XingyunAvatarAgent({
  container: document.getElementById("avatar"),
  appId: "your-app-id",
  appSecret: "your-app-secret",
  gatewayServer:
    "https://nebula-agent.xingyun3d.com" +
    "/user/v1/ttsa_v2/session",
  enableClientInterrupt: true,

  onMessage(error) {
    console.error("渲染层", error.code, error.message);
  },
  agentCallbacks: {
    onError(error) {
      console.error("Agent 层", error.code, error.message);
    },
  },
});

这里先圈出三个容易漏掉的地方:加载的是 xmovAvatar_e2e@latest.js;全局对象换成 XingyunAvatarAgent;网关路径换成了 /ttsa_v2/session。

还有错误监听。新版除了渲染层的 onMessage,还要关注 agentCallbacks.onError,ASR、Brain、网络等环节的异常也需要进入排查视野。

接下来等初始化完成,再发起第一轮文本对话:

await agent.init({
  onDownloadProgress(progress) {
    console.log(`资源加载 ${progress.toFixed(0)}%`);
  },
});

await agent.ask("请用两句话介绍这个展厅。");

ask() 把输入交给智脑,再进入具身表达链路。应用侧不用再为这次回复额外调用一遍 speak()。

但先别把 await agent.ask() 理解成“它已经说完”。调用成功与整轮表达结束,是后面要分开看的两个时刻。

在这里插入图片描述

图 1|完成初始化后,分别通过文本和语音入口发起交互。

02 打开麦克风,最该少写的一行代码

文本对话跑通后,再接语音会更容易定位问题。

const startButton = document.getElementById("start-asr");
const stopButton = document.getElementById("stop-asr");

startButton.addEventListener("click", async () => {
  try {
    await agent.startASR();
  } catch (error) {
    console.error("语音启动失败", error);
  }
});

stopButton.addEventListener("click", async () => {
  try {
    await agent.stopASR();
  } catch (error) {
    console.error("停止识别失败", error);
  }
});

页面需要运行在 HTTPS 或 localhost,麦克风由用户点击按钮后开启。按钮是否可用,应结合初始化进度、Agent 与 ASR 状态来控制。

这一步有个很容易顺手写出来的问题:在 onASRResult 收到最终识别结果后,又手动执行一次 agent.ask(result.text)。

在默认自动对话链路里,识别完成后会自动进入智脑对话。识别回调可用于字幕展示或调试,重复 ask() 可能把同一句话提交两遍。

这也解释了为什么新旧示例不能原样混用。旧项目里承担“向下一环传递结果”的业务代码,迁移之后要重新检查。

语音接入之后,可以在播报过程中插入一句:“先讲讲二号展区。”再分别观察识别文本、打断事件和下一轮回复。

这里要区分“麦克风正在收音”和“系统识别到了有效插话”。平台资料列出了降噪、AEC/抗回声、本体声音抑制、VAD、远场语音及 Double Talk/Barge-in 等能力;具体表现需要结合应用配置、音箱与麦克风的位置、环境噪声验证。仅调用 startASR(),不足以证明这些环节在当前设备上都已达到预期。

03 大模型输出完了,智能体还可能没说完

如果页面上有一个“本轮已结束”的提示,你会把它挂在哪个事件上?

只看大模型流式输出的 done,容易提前一步。文字已经生成完,语音和动作仍可能在继续。

这时需要把回调各自负责的事情分清楚。在创建实例之前,先获取用于展示的节点:

const asrText = document.getElementById("asr-text");
const answerText = document.getElementById("answer-text");
const conversationState =
  document.getElementById("conversation-state");

再把下面这些方法加入构造参数中的 agentCallbacks,与前面的 onError 一起使用:

onASRResult(result) {
  asrText.textContent = result.text;
  // 默认自动对话模式:此处不重复 ask()
},

onLLMResponse(response) {
  if (response.event === "chunk") {
    if (response.isFirst) answerText.textContent = "";
    answerText.textContent += response.text ?? "";
  }
  // done 表示模型输出结束,不据此宣布播报结束
},

onConversationChange(event) {
  conversationState.textContent = event.state;
  if (event.state === "completed") {
    console.log("本轮播报已结束");
  }
},

在这里插入图片描述

图 2|事件语义示意,间距不代表耗时;真实执行中,模型输出与表达可以重叠。

另外,onAgentStateChange 适合观察整体状态,onASRStateChange 适合观察麦克风与识别状态,onSocketStateChange 用来辅助定位 E2E 控制连接问题。

主动点击“打断”按钮时,可以调用:

const interruptButton = document.getElementById("interrupt");
const destroyButton = document.getElementById("destroy");

interruptButton.addEventListener("click", () => {
  agent.interrupt("speak");
});

destroyButton.addEventListener("click", async () => {
  try {
    await agent.destroy("user");
  } catch (error) {
    console.error("会话释放失败", error);
  }
});

结束交互时,调用 destroy() 释放会话与麦克风资源;如果集成在组件中,也应在卸载钩子里清理。按钮打断可以帮助检查客户端链路。自然语音插话能否及时被识别,还需要结合应用配置、拾音环境和有效打断判定来验证。

04 为什么要分开维护三种状态

把全部过程压成一个 isBusy,初期很省事,但不容易区分以下情况:

  • Agent 连接正在恢复,当前不能接收新请求。
  • 麦克风仍在收音,但当前表达已经被打断。
  • 模型输出已结束,播报仍在继续。

因此,界面至少要分别观察 Agent 状态、ASR 状态和对话状态。它们有联系,也各自有不同的变化条件。

在平台的术语中,这类系统被称为“端到端具身交互智能”。官方将整体能力概括为:多模态感知 + 专属智脑 + 多模态表达 + AI 端渲 + 数字与物理行动。

端到端不是简单拼接,而是需要围绕同一次交互协调事件、会话状态、时序与异常。

这对应用开发的具体要求,是用户插话、模型生成、表达结束和网络重连之间,不能各自维护一份互不一致的状态。

在这里插入图片描述

图 3|平台交互模型的概念示意,不表示该 Web 示例已实现全部感知与行动能力。

“专属智脑”可以理解为知识、身份规则、任务与业务工具的配置层。RAG、知识图谱、工作流或企业系统是否实际参与回答,要看应用配置和调用结果;接通 ask() 本身并不能证明已经完成这些业务集成。

同样,AI 端渲描述的是渲染侧的工程安排,不能据此推断语音和智脑服务也可离线。一个智能体可以进入不同的身体,但跨终端复用身份、知识、任务和记忆,仍需要相应配置;机器人动作也取决于本体与已接入技能。

05 替换组件时,检查接口之外的行为

可插拔组件允许复用已有 ASR、模型或 TTS。集成时,接口能调用只是第一步,还要核对替换前后的事件语义。

模块接入后应确认的行为
ASR临时结果与最终结果如何区分;是否自动进入对话;如何上报识别失败
Brain上下文如何传递;流式首块与结束事件如何表示;业务工具是否获得授权
TTS 与表达模型结束后是否仍在播报;如何通知表达完成;打断后是否残留旧内容
机器人运控哪些动作由本体提供;失败与取消如何回传;是否存在实际执行权限

例如,替换 ASR 之后,如果继续沿用旧业务代码,在最终结果回调里手动 ask(),而新的链路又已自动提交,就会产生重复请求。这个问题与识别准确率无关,根源在于两个环节都承担了“提交到下一步”的职责。

平台文档描述的标准化接口契约与统一状态管理,需要在这些具体场景中核对:事件有没有重复、状态能不能恢复、取消动作是否生效、异常是否到达应用层。

06 用一组可观察的场景结束联调

不要只观察“能否回复第一句话”。下面这组场景更容易暴露会话问题,表中是检查目标,不是本文的实测结果。

操作应观察的结果
初始化尚未完成时尝试提交不应直接调用需要 running 状态的接口
语音说完一句完整问题在自动对话模式下,不应因业务重复调用而产生两次相同请求
收到模型 done 事件可以结束文本生成提示,不应直接冒充播报 completed
开始下一轮回复上一轮展示内容应按业务需要清空,避免错误拼接
点击客户端打断当前表达应按 SDK 约定被停止,并能继续处理后续交互
模拟网络断开再恢复状态提示、按钮可用性和 SDK 恢复状态应保持一致
退出页面或卸载组件主动释放会话、麦克风及相关监听

自然语音打断还需要单独测试:用户插话、咳嗽、轻声应和、扬声器回声与背景噪声,不能只用一个按钮调用来代替验证。如果要比较方案,也应在相同设备、网络、音量和测试语料下记录结果。

这篇接入示例想留下的,是一个适用于多种语音智能体的判断方法:先明确每个事件表示哪一步完成,再决定页面状态和下一步动作。 请求提交成功、模型输出结束与播报结束,各有各的用途。


参考文档


转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/m0_68089732/article/details/168345053

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--