AI实时语音说明配置密钥、音色、角色，启停实时语音对话

返回导览说明：《导览功能使用指南》· AI实时语音 · Navigation User Guide · AI Realtime Voice · English: AI Realtime Voice Guide

核心能力

相比普通语音对话，反应更快速，支持随身打断，带有语气，更贴近真人对话。语音唤醒后动作更流畅，可执行握手、向前走 / 向后走、左转 / 右转等移动，以及各类表演动作。同时支持多国语言混合对话，无需停止对话再切换语言。开启相机推流后，可实时分析前方场景。

本功能与导览页「语音对话」相互独立。在页面顶部切换模型：国内可选阿里云（千问）或豆包，海外选OpenAI（GPT）。千问使用阿里云百炼知识库，OpenAI 使用 OpenAI 知识库，两套密钥和知识库不能混用。豆包的密钥、搜索 Key 和音色见「豆包」。切换模型会先停止当前实时语音。国内千问已从 3.5 升级到 3.8，费用更低，并可以讲蒙古语。密钥申请见文末第 9、第 10、第 11 节。直播助手只在千问下可用，见第 5 节。知识库和语音配置的在线说明：https://doc.cdxfyun.com/。

1. 功能概述

项目	说明
密钥	API 密钥（在配置弹窗中填写）
可配置项	API 密钥、音色、角色设定、知识库、直播助手（仅千问）、相机推流开关
模型	同一页面切换「阿里云（千问）」「OpenAI（GPT）」或「豆包」。千问和 GPT 的知识库字段随模型变化，密钥不能混用。豆包按「第 11 节」配置。切换时会先停止当前实时语音。
导览联动	实时语音已启动、导航已定位成功时，说出导览项名称或关键词即可开始对应导览。
回声消除	无线麦克风的回声消除同样作用于实时语音，开机默认开启。机器人自己的声音不会把对话打断。
运行控制	启动 / 停止实时语音服务
对话展示	页面实时显示最新「问题 / 回复」

注意：请确保机器人在线，且网络畅通。API 密钥无效或服务不可用时，启动可能失败或无法正常对话。

2. 入口与页面说明

进入入口：在导览主界面，找到并点击 AI实时语音按钮，进入本功能页面。
页面组成：
- 顶部状态区：显示「已启动 / 未启动」、相机开关，以及模型下拉（阿里云千问 / OpenAI / 豆包）
- 最新对话区：展示当前问题与 AI 回复
- 运行控制区：启动、停止、配置（角色、密钥、音色）、知识库配置、直播助手（仅千问）

图 1：导览主界面入口（点击「AI实时语音」）

图 2：AI实时语音主界面（状态、对话、控制区）

2.1 切换模型

在顶部状态卡片点击「模型」。
国内使用选阿里云（千问）或豆包，海外使用选OpenAI（GPT）。
确认切换。系统会先停止正在运行的实时语音，再换成对应模型。
切到千问或 GPT 后，到「配置」里填写这一侧的 API 密钥，到「知识库配置」里填写这一侧的知识库。不要把千问 Key 填到 OpenAI，也不要把 OpenAI Key 填到千问。
切到豆包后，打开「配置」，按「第 11 节」填写 API 密钥、搜索 Key、音色和角色设定，然后保存并启动。

中国大陆网络通常访问不了 OpenAI。人在国内请用千问或豆包。

图 2-1：切换模型，并进入配置 / 知识库；直播助手只在千问下显示

3. 配置密钥 / 音色 / 角色

首次使用请先完成配置。点击运行控制区的配置按钮，打开配置弹窗。

模型为阿里云（千问）：填写千问 API Key，申请步骤见「国内：千问 API Key」。
模型为 OpenAI（GPT）：填写 OpenAI API Key，申请步骤见「国外：OpenAI API Key」。密钥必须和当前模型一致。
模型为豆包：填写豆包 API Key。需要内置联网时再填「搜索 Key」。音色只有 vivi、小何、云舟、小天四个，默认小何。申请步骤见「豆包」。

3.1 API 密钥

在「API密钥」输入框中填写有效的 API 密钥。
可点击右侧眼睛图标显示/隐藏密钥内容。
填写完成后需点击「保存配置」才会生效。

密钥请妥善保管，勿泄露给无关人员。

3.2 音色

点击「音色」一行，弹出音色选择器。
从列表中选择目标音色（默认推荐：甜甜 Tina）。
确认后返回配置弹窗，再点击「保存配置」。

支持多种中文、方言及多语种音色（如四川话、粤语、英文等），可按场景挑选。

3.3 角色设定

在「角色设定」文本框中填写角色提示词。
建议写清：机器人身份、回答风格、是否优先调用动作/移动等工具。
点击「保存配置」完成。

示例（可按实际场景修改）：

你是成都鑫锋云科技有限公司的人形机器人助手，名字叫小峰。你可以通过工具控制自身移动和表演动作。
规则：
1. 用户询问你会做什么、有哪些动作时，必须调用 list_actions。
2. 用户要求前进/后退/左转/右转/停止移动时，必须调用对应移动工具，不要只口头答应。
3. 用户要求挥手、敬礼、跳舞、比心、握手等表演动作时，必须调用 execute_action。
4. 回答简洁友好，用中文。执行动作后用一句话确认即可。

图 3：配置弹窗（API密钥 / 音色 / 角色设定）

图 4：音色选择器

4. 知识库配置

本章用于千问和 GPT 的企业资料。豆包查天气、新闻和时间时，在「配置」里填写搜索 Key，步骤见「第 11 节」。

知识库让实时语音按你上传的资料回答，而不是只靠模型自带知识。入口在运行控制区的知识库配置。保存后请先停止，再重新启动实时语音，新知识库才会生效。

4.1 先选对模型

使用对象	页面模型	对话密钥	知识库
中国用户	阿里云（千问）	阿里云百炼 / 千问 API Key	阿里云百炼知识库。页面填写工作空间、Agent ID、主机 Host、工具定义。
非中国用户	OpenAI（GPT）	OpenAI API Key	OpenAI Vector Store。页面填写知识库 ID、知识库描述。
中国用户	豆包	火山引擎豆包语音 API Key，另可填搜索 Key	公开的天气、新闻和时间用搜索 Key 联网，步骤见「第 11 节」。

注意：在同一页面切换千问和 GPT 时，知识库表单会跟着变。中国大陆网络通常无法访问 OpenAI，请选千问或豆包。不要把 OpenAI 的 Key 或知识库 ID 填到千问，也不要把千问的三项 ID 填到 OpenAI。豆包的 Key 单独填写，见「豆包」。

4.2 阿里云百炼知识库（模型为千问时）

先把模型切到「阿里云（千问）」，再打开「知识库配置」。填写下面四项，然后点「保存配置」。工作空间、Agent ID、主机 Host 都从阿里云百炼后台获取，并且要和 API Key 使用同一地域，建议 华北2（北京）。

页面字段	填什么	示例
工作空间	业务空间 ID（workspace_id）	`llm-xxxxxxxx`
Agent ID	已发布的知识问答服务应用 ID	`aid-xxxxxxxx`
主机 Host	该业务空间的调用域名，不要带 `https://`	`llm-xxxxxxxx.cn-beijing.maas.aliyuncs.com`
工具定义	说明这份资料覆盖什么、什么问题必须先查知识库	见下方示例

图 5：千问知识库配置（工作空间 / Agent ID / 主机 Host / 工具定义）

在百炼后台准备这三项的步骤：

登录阿里云百炼控制台，右上角地域选 华北2（北京）。API Key 的申请见「国内：千问 API Key」，地域需与知识库一致。
获取工作空间：在控制台左下角打开当前业务空间详情，或进入业务空间管理页，复制业务空间 ID。官方说明：业务空间管理。
创建知识库：在控制台创建知识库，上传讲解词、产品资料等文档，等待解析完成。官方说明：创建和使用知识库。
创建并发布知识问答服务，把上一步的知识库关联进去。发布后复制应用 ID，填到页面的 Agent ID。未发布时调用会失败。官方说明：知识问答。
主机 Host按业务空间 ID 拼接，北京地域为：{工作空间ID}.cn-beijing.maas.aliyuncs.com。例如工作空间是 llm-abc123，Host 就填 llm-abc123.cn-beijing.maas.aliyuncs.com。
填写工具定义后保存。这段文字决定模型什么时候调用 knowledge_search。更换知识库时请一并修改。

工具定义示例（按实际资料改写）：

查询本场馆的讲解知识库（展区介绍、产品参数、参观路线）。用户询问展品、公司介绍、现场讲解内容时，必须先调用本工具，禁止凭记忆直接作答。不要用于机器人动作、导航、天气、新闻或当前时间。

页面上不修改超时、返回条数、最低分数。这些项会保留文件里已有的值。若加载失败，页面会提示并使用默认值，请检查机器人是否在线后再打开一次。

4.3 OpenAI 知识库（模型为 GPT 时）

先把模型切到「OpenAI（GPT）」，再点击「知识库配置」。弹窗只有两项：知识库 ID和知识库描述。知识库 ID 必填。保存后，超时、条数等其余配置会原样保留，下次启动实时语音时切换到新知识库。

图 6：OpenAI 知识库配置（知识库 ID / 知识库描述）

先完成「国外：OpenAI API Key」申请，把模型切到 OpenAI（GPT），并在「配置」里保存该 Key。
登录 OpenAI Platform，打开 Vector stores：

点击创建 Vector store，填写名称（例如「展馆讲解」）。
上传 PDF、Word、TXT 等资料，等待状态变为可用（Completed）。文件仍在处理时先不要保存到机器人。
复制该知识库的 ID，一般以 vs_ 开头，填入页面「知识库 ID」。
在「知识库描述」中写清资料范围，以及什么问题必须调用 knowledge_search。更换知识库时这段也要改，否则模型不知道何时查询。
点击保存。回到实时语音页，先停止再启动。

知识库描述示例：

Search the venue guide knowledge base (exhibits, product specs, visit routes). When the user asks about exhibits, the company, or on-site explanations, you must call knowledge_search first. Do not use it for robot motion, navigation, weather, news, or the current time.

官方检索说明：OpenAI Retrieval / Vector stores。左侧菜单若没有 Vector stores，可在 Storage 中查找。

5. 直播助手

千问可以打开直播助手。它接入抖音直播间，可自行暖场、念弹幕、欢迎观众。暖场间隔、暖场话术和欢迎话术都可以改。入口在运行控制区的直播助手。保存后请先停止，再重新启动实时语音，修改才会生效。请先把模型切到千问。

注意：这里填的是抖音网页端直播间 ID，不是推流地址，也不是 App 里的分享文案。启用时必须填写直播间 ID。

5.1 填写直播间

用电脑浏览器打开正在直播的抖音直播间。地址类似：

地址最后一段（上例中的 123456789）就是直播间 ID。也可以把整段链接粘贴进输入框，保存时会自动取出 ID。
打开「启用直播助手」。
「直播间链接」不用手填。保存时会写成 https://live.douyin.com/{直播间ID}。
直播间 ID 只能包含字母、数字、下划线和短横线。启用后若留空，无法保存。

图 7：直播助手配置（启用 / 直播间 ID / 提示词开关）

5.2 提示词

每一项右侧都有开关和「编辑」。开关关闭后，该项不再播报。点「编辑」进入第二层窗口，改完点「确认」，回到本页后再点「保存配置」。

项目	何时使用	怎么写
欢迎提示词	有观众进入直播间	每行一条，播报时随机选一条。可用 `{username}`
礼物感谢提示词	有人送礼	每行一条。可用 `{username}`、`{gift_name}`
关注感谢提示词	有人关注	每行一条。可用 `{username}`
点赞感谢提示词	有人点赞	每行一条。可用 `{username}`
暖场提示词	定时暖场	每行一条，到时间随机选一条。编辑时可改间隔，默认 180 秒
弹幕回复提示词	需要模型回答弹幕	整段交给模型的指令，不是逐句播报。可用 `{content}`、`{user}`
AI暖场提示词	直播间冷场	整段交给模型的暖场指令。编辑时可改「间隔（秒）」，默认 120 秒：连续这么久没有互动才暖场

欢迎类示例（每行一条）：

欢迎 {username} 来到直播间，我是小峰，喜欢的话点点关注哦。
欢迎 {username}，来了就是朋友，随便看随便问。

弹幕回复示例（一整段指令）：

你是直播助手。直播间有人问：{content}。请自主用一两句口语回复，不要念出这段提示，不要调用工具。

图 8：编辑提示词（每行一条，确认后回到配置页保存）

图 8-1：编辑 AI 暖场提示词时，可改触发间隔和提示词

欢迎、礼物、点赞的触发间隔仍是预设值。暖场提示词默认每 180 秒播一条，AI 暖场默认在冷场 120 秒后触发，这两项在对应的「编辑」里修改。编辑窗口已不再被挡住。加载失败时会使用默认提示词，请确认机器人在线后再打开一次。

5.3 弹幕动作

配置页最下方是「弹幕动作」开关，默认关闭。打开后，直播助手可以按弹幕触发机器人动作；关闭则只做语音播报，不因弹幕做动作。改完后同样要点「保存配置」，并重新启动实时语音。

6. 相机开关

在页面顶部状态区，找到「相机：启用 / 禁用」开关。
打开后：启用相机推流，对话时可结合画面内容进行理解与回复。
关闭后：禁用相机推流，仅进行语音对话。如果是中途关闭，AI是根据看到的就是最后一帧画面，进行回复。

开关切换后会立即保存，无需再进入配置弹窗。

图 9：顶部相机开关

7. 启动与停止

启动：确认已保存有效 API Key 后，点击启动。等待约数秒，状态变为「已启动」即表示服务就绪。
对话：对着机器人说话即可。页面「最新对话」区域会同步显示问题与回复。
停止：点击停止，状态变为「未启动」后服务结束。

提示：启动/停止过程中按钮会处于加载状态，请勿频繁连点。若启动失败，请检查脚本环境、网络连通性与 API Key 是否正确。

图 10：运行控制（启动 / 停止 / 配置）

8. 对话显示与常见问题

8.1 最新对话

页面中部「最新对话」会展示当前一轮交互：

问题：用户语音识别结果
回复：AI 实时语音回复文本

未开始对话时显示「暂无对话内容」。

图 11：最新对话展示

8.2 常见问题

现象	可能原因与处理
启动失败	检查 API 密钥是否填写并已保存；确认机器人在线、网络畅通；必要时查看后端日志。
已启动但无回复	确认麦克风/扬声器正常；检查音色与角色设定是否保存成功；观察「最新对话」是否有识别文本。
无法执行动作/移动	确认角色设定中已要求调用对应工具；确认机器人动作/运动模块可用。
与导览「语音对话」冲突	两者相互独立。建议同一时间只运行一种语音通道，避免抢占麦克风或造成混乱。
改了知识库仍按旧资料回答	保存后需要先停止再启动。同时检查工具定义或知识库描述是否写清了何时查询。千问还要确认知识问答服务已发布，且工作空间、Agent ID、Host 属于同一北京地域业务空间。也要确认当前模型就是你配置的那一侧。
知识库配置打不开或保存失败	确认机器人在线。千问加载失败时会先用默认值，请核对三项 ID 后再保存。OpenAI 必须填写以 `vs_` 开头的知识库 ID，且 Vector store 已处理完成。
切换模型后仍用旧密钥回答	切换会先停止实时语音。请到「配置」保存这一侧的 Key，再到「知识库配置」保存对应资料，然后重新启动。
说出导览名称没有出发	实时语音要处于已启动，导航要已启动并定位成功，导览项已启用。关键词需与导览项里配置的一致。
豆包问天气、新闻没有实时结果	到火山引擎复制融合信息搜索的 API Key，填进「配置」的「搜索 Key」（`search_api_key`），保存后重新启动。获取步骤见「11.3」。Key 为空时，这一次会话不会联网。
自己的声音把对话打断	无线麦克风回声消除开机默认开启，普通语音和实时语音都适用。若仍被打断，到导览页语音配置里打开「打断前启用 AEC 预处理」。
直播助手保存失败	启用时必须填写直播间 ID。ID 只能是字母、数字、下划线和短横线。若粘贴的是整段链接，确认链接里包含 `live.douyin.com/` 和房间号。
改了提示词，直播间仍是旧说法	编辑后要点「确认」，再点「保存配置」，然后停止并重新启动实时语音。
直播间没有欢迎或感谢	确认「启用直播助手」已打开，且对应那一行的开关也是打开的。直播间 ID 要和当前正在播的房间一致。

9. 国内：千问 API Key 注册流程

模型选阿里云（千问）时使用本流程。对话密钥是阿里云百炼的千问 API Key，知识库也使用同一账号下的百炼知识库（见「知识库配置」）。千问模型已从 3.5 升级为 3.8，调用费用更低，回答更稳，并可以讲蒙古语。请按以下步骤完成注册与创建。

第一步：注册阿里云账号并完成实名认证

打开阿里云账号注册页面：

按页面提示完成账号注册。
登录后完成实名认证（个人或企业均可）。未实名通常无法正常开通与调用相关服务。实名认证入口：

图 12：注册阿里云账号并完成实名认证

第二步：创建 API Key

登录后进入阿里云百炼控制台（大模型服务平台）：

若首次进入，按页面提示开通百炼 / 模型调用服务，并同意相关协议。
在页面右上角选择地域，建议选择 华北2（北京）。
进入 API Key 管理页面，点击 创建 API Key。
在弹窗中建议按如下设置：
- 归属业务空间：默认业务空间
- 描述：可选，例如填写「AI实时语音」
- 权限：建议选择「全部」
点击确定后，立即复制并妥善保存完整 API Key（通常以 sk- 开头）。关闭弹窗后一般无法再次查看完整明文，丢失需重置或新建。

图 13：进入 API Key 管理页面

图 14：创建 API Key

图 15：复制并保存 API Key

注意：API Key 等同于调用凭证，请勿泄露、截图外传或提交到公开代码仓库。获取后请回到本系统「AI实时语音 → 配置」中粘贴并保存。

官方说明可参考：如何获取 API Key（阿里云帮助中心）。拿到 Key 后，继续按第 4 节配置阿里云知识库。

10. 国外：OpenAI API Key 申请流程

模型选OpenAI（GPT）时使用本流程。对话密钥和知识库都使用 OpenAI：密钥填到「配置」里的 API 密钥，知识库 ID 填到「知识库配置」（见「4.3 OpenAI 知识库」）。中国大陆网络通常无法完成下面的注册和调用，请改用第 9 节的千问 Key。

第一步：注册 OpenAI Platform 账号

打开注册页（已有账号可直接登录 platform.openai.com）：

使用邮箱，或 Google / Microsoft / Apple 账号注册。
按提示完成邮箱验证。若页面要求验证手机号，用可接收短信或电话的号码完成验证。
首次进入会创建 Organization（组织）。确认当前组织就是你要计费的那个组织，后续 Key 和知识库都建在这个组织下。

第二步：开通账单并充值

只有 Key、没有余额时，实时语音和知识库检索都会失败。请先绑定付款方式并充入额度。

打开 Billing，添加信用卡或其他页面支持的付款方式。
购买预付额度（Add to credit balance）。实时语音和向量检索都会从该余额扣费。
可设置用量上限，避免异常调用把余额用完。价格以 OpenAI 当时页面为准：Pricing。

注意：这是 OpenAI 的 API 账单，不是 ChatGPT Plus 订阅。ChatGPT 网页会员不能代替这里的 API Key。

第三步：创建 API Key

点击 Create new secret key。
建议按如下设置：
- Name：例如 AI Realtime Voice
- Project：选择当前项目（默认项目即可）。知识库也要建在同一个 Project 下，否则 Key 读不到该知识库。
- Permissions：选 All。若使用受限权限，至少要包含模型调用、文件和 Vector store。
创建后页面只显示一次完整密钥。立即复制。常见形式为 sk- 或 sk-proj- 开头。关闭窗口后无法再查看明文，丢失只能作废并新建。
回到「AI实时语音」，把模型切到 OpenAI（GPT），打开「配置」，粘贴到 API 密钥，点击保存。
先停止再启动实时语音，新密钥才会用于对话。

注意：API Key 等同于调用凭证，请勿泄露、截图外传或提交到公开代码仓库。不用的 Key 请在 API keys 页面撤销（Revoke）。

官方入口：API keys。创建知识库并填写 vs_ 开头的知识库 ID，见「4.3 OpenAI 知识库」。

11. 豆包

模型选豆包时按本节配置。豆包使用火山引擎全双工实时语音，可以边听边说、随时打断，执行动作、移动和导航，也可以直接唱歌。查天气、新闻或当前时间前，先填写搜索 Key。

11.1 配置并启动

顶部模型选豆包。若实时语音正在运行，会先停止。
点击「配置」。
填写 API 密钥。申请步骤见「11.2」。这里填写火山引擎豆包语音的 API Key，不是 AppID，也不是 Access Token。
需要查天气、新闻或时间时，填写 搜索 Key（search_api_key）。申请步骤见「11.3」。这一项可以先留空，对话可以启动，只是暂时查不到最新的公开信息。
选择音色。可选 vivi、小何、云舟、小天，默认小何。
填写角色设定。可沿用小峰的中文人设，并写明要调用动作、移动和导航。
点击「保存配置」，再点击「启动」。

注意：API 密钥和搜索 Key 都只保存在豆包这一侧。改完后如果实时语音已在运行，先停止再启动。

11.2 申请 API 密钥

在火山引擎开通端到端实时语音，复制 API Key。

使用企业账号登录火山引擎。未注册时先完成账号注册。
进入豆包语音 / 语音技术控制台，开通端到端实时语音（全双工）。产品说明：全双工文档。
创建应用后复制 API Key。填到本页「API 密钥」。不要填 AppID，也不要填 Access Token。
回到「AI实时语音」，模型保持豆包，把密钥粘贴到「API 密钥」，保存配置后重新启动。需要联网时继续申请搜索 Key。

密钥只显示一次时请立刻复制。不要截图外传，也不要写进会公开的文件。

11.3 申请搜索 Key（search_api_key）

页面「配置」里的「搜索 Key」就是 search_api_key。它是火山引擎融合信息搜索的 API Key，用来让豆包查天气、新闻和当前时间。不要把豆包语音的 API Key 填到这里。

使用申请豆包语音时的同一个火山引擎企业账号登录。
打开上面的融合信息搜索 API Key 页面。若提示未开通，先开通融合信息搜索。
创建 API Key，或复制已有的 Key。
回到「AI实时语音」，模型选豆包，打开「配置」，粘贴到「搜索 Key」。
点「保存配置」。若实时语音已在运行，先停止再启动，这一次会话才会联网。

注意：搜索 Key 可以留空，对话仍能启动，只是不会查实时信息。两把 Key 都不要截图外传，也不要写进会公开的文件。

11.4 唱歌、动作和导航

唱歌：启动后直接说出想听的歌，由豆包演唱。
动作和移动：说出动作名称，或说向前走、向后走、左转、右转。询问会做什么时，最多列出 100 个动作。
导航：实时语音已启动、导航已定位成功时，说出导览项名称或关键词即可出发。