让网页听得见也说得出：我的声网对话式 AI 语音智能体实践笔记

让网页听得见也说得出：我的声网对话式 AI 语音智能体实践笔记

现在不少 AI 智能体已经支持语音输入。对着麦克风说一句需求，系统识别语音、生成回答，再把回答读出来。像《豆包》这类应用，已经让很多人习惯了这种交互方式。

那么，我就再想：怎样在自己开发的应用里接入一个对话式 AI 智能体，让应用接住用户说的话，再把语音回答送回应用。同时，还能同步显示双方对话字幕。

很早之前就了解过 声网，当时是从 OpenAI Realtime API 的合作信息中注意到它的，主要做 AI 实时语音互动。

最近听说声网有一个对话式 AI 引擎，能把 ASR（语音识别）、LLM（大模型）和 TTS（语音合成）串到同一条链路里。

一条完整的语音对话链路，包含用户说话、语音识别、模型生成、语音合成和浏览器播放。

语音流程图

我把它拆成四层：网页端体验、RTC 和 RTM 实时传输、已发布智能体的运行时，以及 ASR、LLM、TTS 模型链路。后面的实践会围绕这四层展开。

对我来说，先用对话式 AI 引擎的默认资源把基础链路跑通，可以少做一轮 ASR、LLM、TTS 的逐个对接；以后要换自定义模型或语音服务，再单独配置即可。

话不多说，直接开搞。

一、注册账号并配置项目

首先打开 声网 注册账号。

图1 注册页面

注册完成后，需要先创建一个项目，选择通用项目和 1v1 语音场景，名字就叫做《声声入耳》，当然这个名字你可以自定义，我们后续智能体开发要基于这个项目。

图2 创建项目

需要注意两个部分，APP ID 和 APP 证书，后面调用 API 时会用到。APP ID 是项目标识，APP 证书也只对应当前项目，两个项目之间不能串用，否则会导致校验失败。

图3 项目凭证

二、配置一个对话式 AI 智能体

一开始我想直接写网页应用的，后来发现，智能体配置问题和网页连接问题很容易混在一起。再实际操作时，我需要先在控制台确认智能体能运行，再让网页加入同一个频道，这样排查会轻松很多。

所以第一步先把智能体配置好。

图4 引擎入口

打开项目 对话式 AI 引擎 后，我先看了概览页。这里有两项服务需要开启：

• RESTful API，如果未开通则直接点击去创建即可。后面由服务端创建、停止智能体会话时会用到它。

• 对话式 AI 引擎服务，默认为未开启状态，你需要手动开启，不开通则无法使用该服务。

图5 服务开通

然后，点击侧边栏智能体 > 创建智能体 > 空白。智能体名称我填写为“约好啦在线客服”，描述填写为“网站应用智能体，适合给用户解答预约相关问题”。

图6 创建智能体

紧接着，我们进入到了配置页面，我们需要配置开场白和提示词，定义我们的智能体。

图7 智能体配置

开场白也不需要写得很花哨：

你好，我是约好啦在线客服。你可以问我预约表单、可预约时间、微信小程序入口等使用问题。

提示词

你是“约好啦”的客服助手，使用自然、简洁的中文回答问题。

在这个官网原型里，约好啦包含预约表单、服务项目、可预约时间、微信小程序入口和支付相关配置等常见问题。

回答规则：

– 每次回答控制在 2 到 4 句。
– 用户问操作方法时，用简单步骤说明。
– 用户问题不完整时，只追问一个必要信息。
– 不确定的价格、审核、支付状态或具体订单信息时，明确说需要人工核实，不要猜测。
– 不索取身份证号、银行卡号、验证码、支付密码等敏感信息。
– 不承诺结果，不使用“最好”“保证”“一定”等表达。
– 遇到故障问题，建议用户提供报错现象或截图，再联系人工客服处理。

示例：

用户：怎么创建预约表单？
回答：可以先新建一个服务项目，再设置可预约时间和表单字段。完成后生成预约入口，放到需要展示的位置即可。

用户：支付失败怎么办？
回答：请先确认支付配置和订单状态是否正常。如果仍无法处理，建议保存报错截图后联系人工客服核实。

然后点击右侧的预览测试，就能听到智能体的声音。简单对话几句，就能确认基本流程是否符合预期。后面如果要补充更多业务信息，还可以再接知识库或业务工具；本篇先以主流程跑通为目标，测试声网提供的对话式 AI 引擎能力。

图8 预览调试

当智能体确认无误后，我们就可以点击发布。发布以后，列表页会显示 Pipeline ID，它对应这份已发布的智能体配置，后续服务端启动会话时会用它来定位配置。

图9 发布结果

三、为“约好啦”官网原型添加客服悬浮按钮

现在智能体已经准备好了，接下来要让网页真正使用它。声网提供了对应的 SDK，可以负责网页端的 RTC、RTM 和语音会话连接。

图10 声网 SDK

网页接入后，再补上必要的会话配置，就可以开始测试。

所以我在“约好啦”官网原型中补两段代码：一段只在服务端运行，负责凭证和会话；另一段在浏览器运行，负责 RTC、RTM、麦克风和页面状态。

服务端接口我放在了 app/api/session/route.ts。此时，先把之前准备的 APP ID、APP 证书以及 Pipeline ID 填写到 .env.local 中，方便后续调用；这个文件只留在本地和服务端，不提交到仓库。

AGORA_APP_ID=962xxxx
AGORA_APP_CERTIFICATE=0838xxxx
AGORA_PIPELINE_ID=162xxxx

前端项目中，接入 SDK 后还要把会话建立顺序处理好。

主要是在用户点击客服浮动窗口时，页面先向后端发起请求 POST /api/session，然后前端再按“登录 RTM、订阅频道、加入 RTC、发布麦克风、初始化字幕监听”的顺序连接。

所有这些准备完成后，网页再请求 PUT /api/session，由服务端让已发布的智能体进入同一频道。

这时网页已经具备了启动会话的条件，接下来再用真实语音验证音频和字幕是否都能回来。

图11 启动代码

四、网页最小流程跑通

开发完毕后，直接启动项目，点击按钮后，会出现浏览器授权，此时点击允许即可。

图12 麦克风授权

接下来点击客服按钮，点开后会接入智能体并自动说开场白。我试着在它播报时插话，它会停止当前播报并接住新的问题。这个细节比单纯“能说话”更像一次真实的客服对话。

图13 客服对话

五、需要注意的点

在这次的实践中，需要注意的点是，需要先完成消息订阅，再创建智能体，这一部分，在文章「 实时字幕接入说明」。

图 14 APP 接入声网 SDK 流程

最早的实现里，前端请求一次接口，服务端立刻启动智能体，再把 Token 返回给页面。看起来少一次请求，实际却埋了一个时序问题：智能体可能已经发出了开场白或字幕事件，浏览器才开始订阅 RTM。

这类问题最难受的地方是，它不像 Token 错误那样直接失败。音频可能能听到，字幕却少一段；或者页面已连上，但日志里没有最早的消息。实时字幕接入说明 给出的流程也是先完成消息订阅，再创建智能体。

我把启动过程拆成两段：

虽然多了一次请求，但每个状态都能单独看见。Token 出错、RTM 未订阅、RTC 未连上、智能体未启动，都会落在不同步骤里。页面上的实时字幕和调试日志也就有了实际用途：它们用来判断链路到底卡在哪里。

还有一次更隐蔽的问题：客服已经能听到开场白，浏览器也能收到远端音频，但“实时对话”区域始终是空的。开始我以为是字幕事件没有发出来，后来对照日志才发现，RTM 已经连上，问题出在字幕监听的初始化参数。

我当时把 RTM 实例放进了 rtmConfig，而客户端工具包实际读取的是顶层的 rtmEngine。这两个名字看起来很像，页面也不会因为它报错：RTC 仍能播放音频，所以很容易误判为整条链路已经正常。把初始化改为传入顶层 rtmEngine 后，字幕事件才开始进入页面。这个坑也让我保留了调试日志：音频正常不代表 RTM 字幕已经正常，两个状态要分开看。

六、一个小配置带来的实际变化

最小流程跑通后，我开始用停顿测试对话节奏。默认配置下，我停几秒，智能体有时会很快接着追问，甚至沿着上一句话继续说。这对测试没什么问题，但放进真实页面后，用户只是想想下一句时，体验会显得有点着急。

我在对话式 AI 引擎的“通话调优”里找到“智能体最大静默时间”。截图中的默认值是 4 秒，我把它调到 60 秒，再重新发布。这里要注意：对话式 AI 引擎改完配置后，需要重新发布；已经在运行的旧会话不会自动切换到新配置。

图14 静默设置

这次会话里的实际等待时间超过 60 秒。我能确认的是，调大这个数值后，短暂停顿不会立刻触发追问；至于平台内部怎样结合语音活动和会话状态判断，我没有继续把它写成确定结论。对于我来说，能把“为什么它突然接话”变成一个可以回到控制台检查的参数，就已经足够了。

小结

一开始我把目标想得很简单：在网页上放一个麦克风按钮，把声音转成文字，再交给模型。做完本项目我才发现麦克风只是入口。

用户真正感受到的，是声音有没有进入 RTC 频道，已发布的智能体有没有按指定 Pipeline 启动，回答有没有被合成为音频，以及字幕有没有经由 RTM 回到页面。

目前效果是：我说一句，它听见；它答一句，我听见；我可以在它说话时进行打断，智能体也能快速响应，双方说过的话能在同一个页面留下来。

本次实践是成功的，但是本项目后续需要完善的还是知识库的接入、人工介入如何处理。