走到哪讲到哪，一位跟着你走的AI导游 - 云游如何用端到端具身交互智能让山水开口说话

打开一个网页地图上六个景点星罗棋布。你的位置靠近西湖断桥还没来得及点击右侧的 AI 导游已经微笑着开口您现在站在西湖断桥之上。这座桥虽然不长却承载了千年的浪漫传说。让我给您讲讲白娘子和许仙在这里相遇的故事……“你好奇追问一句那断桥这个名字到底怎么来的”导游不假思索地接上了话题。这不是预录好的语音导览。屏幕上的这位「云游」是由端到端具身交互智能驱动的具身交互智能体——她能感知你的位置、能听你的提问、能想该怎么讲、还能配合讲解内容自然地做出表情和手势。走到哪讲到哪随时打断随时追问。本文以云游 YúnYóu 为实战样本拆解一个景区 AI 导游应用如何基于魔珐星云端到端具身交互智能平台用一个 SDK 把定位感知、大脑推理与多模态表达全链路打通让六处山水风景在浏览器里「开口说话」。第一站为什么风景讲解是端到端具身交互智能的天然舞台景区语音导览器用了几十年体验基本是「租设备、按编号、听录音」。手机上的 AI 导游虽然方便了一些但讲解和游客的行进节奏仍然是割裂的。真实的导游不是这样。一位好的导游在你走路的同时一直在观察你的状态——判断你对哪块摩崖石刻多看了一眼决定要不要展开一段传说在你走神前用一个悬念把你拉回来。你走累了她放慢节奏你好奇追问她停下来先回答再回到主线。这种持续感知位置 → 持续理解兴趣 → 持续决策讲解节奏 → 持续表达与行动的闭环正是魔珐星云提出的端到端具身交互智能要解决的核心问题。云游要做的就是把这种能力搬进一个 Web 端的漫游空间里——游客打开浏览器面对的不是冰冷的文字百科而是一位有温度、有学识、能感知你走到哪里的 AI 导游。第二站一次连接一路风景传统景区导游的拼接困境如果按传统思路搭建一个AI 景区导游至少要对接四套服务定位服务LBS接一家语音识别ASR接一家大模型推理LLM接一家语音合成 形象驱动TTS Avatar再接一家四套服务各自工作中间需要自己写胶水层做状态同步。代码量 2000 行起步首字响应 1.5 到 3 秒ASR 和 TTS 的状态割裂导致导游讲到一半游客无法打断追问。这就是传统拼接方案的典型局限。端到端方案一个 SDK 撑起一次漫游云游基于魔珐星云端到端 SDK XingyunAvatarAgent 构建核心业务代码不到 500 行。整个前端对接只需要三步提供一个 DOM 容器、注册一组回调、调用 agent.ask() 发送消息。// src/services/avatar.ts — 连接具身交互智能体真实代码 async connect(config: { appId: string; appSecret: string }, callbacks: AvatarServiceCallbacks): Promiseany { const { appId, appSecret } config const { onSubtitleOn, onSubtitleOff, onStateChange, onASRResult, onError } callbacks // 等待 E2E SDK 加载完成 if (!window.XingyunAvatarAgent) { console.log([AvatarService] 等待 XingyunAvatarAgent SDK 加载...) await new Promisevoid((resolve, reject) { const start Date.now() const check () { if (window.XingyunAvatarAgent) { resolve() return } if (Date.now() - start 15000) { reject(new Error(XingyunAvatarAgent SDK 加载超时请检查网络连接)) return } setTimeout(check, 200) } check() }) console.log([AvatarService] SDK 加载完成) } const containerEl document.getElementById(this.containerId) if (!containerEl) { throw new Error(容器 #${this.containerId} 不存在请确保容器已渲染) } console.log([AvatarService] 创建 XingyunAvatarAgent 实例...) const agent new window.XingyunAvatarAgent({ container: containerEl, appId, appSecret, gatewayServer: SDK_CONFIG.GATEWAY_URL, onMessage(error: any) { console.error([E2E SDK] 渲染错误:, error.code, error.message) }, agentCallbacks: { onAgentStateChange(state: any) { console.log([E2E SDK] Agent 状态:, state) onStateChange(typeof state string ? state : state?.type || ) }, onASRResult(result: any) { console.log([E2E SDK] ASR 结果:, result.text, result.isFinal ? (最终) : ) onASRResult(result.text || , !!result.isFinal) }, onConversationChange(event: any) { console.log([E2E SDK] 对话状态:, event.state) if (event.state idle || event.state listening) { onSubtitleOff() } }, onError(error: any) { console.error([E2E SDK] Agent 错误:, error.code, error.message) onError?.(error) }, }, }) console.log([AvatarService] 调用 agent.init()...) await agent.init({ onDownloadProgress(progress: number) { console.log([E2E SDK] 资源下载进度: ${progress.toFixed(0)}%) }, }) console.log([AvatarService] E2E 具身智能体连接成功) const cleanup () { void agent.destroy(page_unload) } window.addEventListener(beforeunload, cleanup) ;(agent as any).__cleanup cleanup return agent }端到端具身交互智能和模块拼接的本质区别感知、理解、决策、表达在同一次交互中持续并行运行。导游一边讲一边听游客有没有追问一边判断接下来该展开哪个故事。这段代码里已经包含了后面章节会拆解的所有回调状态感知、语音识别、对话状态切换、错误处理——它们构成了云游走到哪讲到哪的闭环基础。第三站在魔珐星云控制台配置一位 AI 导游云游的具身交互智能体并不是从零搭建的它的能力底座来自魔珐星云控制台的完整配置体系。以下用实际截图还原配置过程。1、创建具身应用在魔珐星云控制台创建一个新应用系统会自动分配 App ID 和 App Secret这就是后续 SDK 连接所需的身份凭证。2、形象配置选择智能体的外在形象——云游需要的是一位热情友善、见多识广的景区导游。平台提供多种形象可选也可以自定义。3、场景配置为智能体设定交互场景的背景环境。云游采用的是自然山水风格的背景和前端 UI 的森林绿 沙金主题保持一致。4、音色配置选择智能体的语音风格。景区导游需要的是热情亲切、语速适中的音色魔珐星云自研 TTS 支持多语言多风格。5、表演配置配置智能体的肢体语言和表情系统——这正是多模态表达的核心。语气、表情、手势、头部动作和身体动作由 SDK 统一生成。导游在讲述西湖传说时语气温柔、在介绍长城气势时手势开阔都来自这一层的配置。6、服务配置ASR 与大脑为当前应用配置语音识别和大模型服务。这一步体现了星云的可插拔架构——平台依靠标准化接口契约与统一状态管理保障模块替换后会话状态、事件流转、交互闭环不受破坏。ASR 支持 Xmov 自研、豆包、腾讯等多家供应商大脑支持魔珐自研、豆包、OpenAI 兼容协议等多种接入模式。这些配置完成后保存即生效。前端只需要拿着 App ID 和 App Secret通过 SDK 一行代码就能连上整套能力。同一个智能体可以拥有不同的身体。今天她是 Web 端的景区导游明天可以变成线下景区的互动终端、甚至人形机器人——身份、知识和导游业务能力持续复用。第四站LBS 定位——走到哪讲到哪云游与其他项目最大的不同在于它内置了一套位置服务系统。游客在地图上移动时系统持续计算与每个景点的距离接近景点自动触发讲解到达景点自动标记足迹。这不是后端轮询也不是额外对接的第三方定位服务——项目自研的位置服务与 SDK 的 AI 讲解紧密耦合位置一变讲解即触发。接近检测与自动讲解核心逻辑封装在 location.ts 中。每次位置更新时系统遍历全部景点找到最近的一个判断是否进入讲解触发距离// src/services/location.ts — 位置感知与接近检测真实代码 /** 用户当前位置 */ const position ref({ x: 50, y: 50 }) /** 已触发讲解的景点集合 */ const guidedSpots new Setstring() /** 最近景点 */ const nearestSpot computed(() { let minDist Infinity let nearest: ScenicSpot | null null for (const spot of scenicSpots) { const dist calculateDistance(position.value.x, position.value.y, spot.coordinates.x, spot.coordinates.y) if (dist minDist) { minDist dist nearest spot } } return nearest }) /** 是否已到达 */ const isArrived computed(() nearestDistance.value LBS_CONFIG.ARRIVAL_THRESHOLD) /** 是否在引导距离内 */ const isApproaching computed(() nearestDistance.value LBS_CONFIG.GUIDE_TRIGGER_DISTANCE) /** 检测接近与到达 */ function checkProximity() { if (!nearestSpot.value) return if (isApproaching.value !guidedSpots.has(nearestSpot.value.id)) { guidedSpots.add(nearestSpot.value.id) onApproachCallback?.(nearestSpot.value) } if (isArrived.value) { onArrivalCallback?.(nearestSpot.value) } }这里有两个关键设计guidedSpots 集合防止重复讲解。游客在西湖附近徘徊时不会每帧都触发一次讲解。只有第一次进入 12 单位距离时触发之后自动静默。重置漫游后才清空。接近和到达是两级事件。12 单位距离触发接近事件——AI 导游开始讲述沿途故事8 单位距离触发到达事件——景点标记为已到达足迹 1。这种两级触发模拟了真实导游的节奏远远看到一座塔就开始讲历史走到塔下再讲建筑细节。导航动画从瞬间移动到边走边讲游客点击前往按钮或点击地图上的景点时位置不是瞬间跳转而是沿直线逐步靠近// src/services/location.ts — 导航动画真实代码 /** 导航到指定景点 */ function navigateTo(spotId: string) { const spot scenicSpots.find(s s.id spotId) if (!spot) return targetId.value spotId if (navTimer ! undefined) cancelAnimationFrame(navTimer) const step () { const dx spot.coordinates.x - position.value.x const dy spot.coordinates.y - position.value.y const dist Math.sqrt(dx * dx dy * dy) if (dist LBS_CONFIG.NAV_STEP_SPEED) { setPosition(spot.coordinates.x, spot.coordinates.y) targetId.value null navTimer undefined return } const ratio LBS_CONFIG.NAV_STEP_SPEED / dist setPosition( position.value.x dx * ratio, position.value.y dy * ratio ) navTimer requestAnimationFrame(step) } navTimer requestAnimationFrame(step) }导航过程中每帧的位置更新都会触发 checkProximity所以游客在走向景点的过程中就可能触发接近讲解——模拟了真实场景中边走边听的体验。自动讲解触发接近事件触发后App.vue 将景点名称和引导词拼装为带上下文的提示词通过 agent.ask() 发送给导游。每个景点数据中都内置了 guideIntro 字段提供该景点的基础讲解素材// src/App.vue — 接近景点自动触发讲解真实代码 onApproach((spot: ScenicSpot) { guideToast.value appState.avatar.connected ? 正在接近「${spot.name}」云游为你讲述沿途故事。 : 正在接近「${spot.name}」。连接 AI 导游即可听取沿途讲解。 if (guideToastTimer ! undefined) clearTimeout(guideToastTimer) guideToastTimer window.setTimeout(() { guideToast.value }, 4000) // 如果 AI 已连接自动触发讲解 if (appState.avatar.connected) { const prompt ${SYSTEM_PROMPT}\n\n游客正在接近「${spot.name}」。请用 2-3 句话简短欢迎并引出讲解${spot.guideIntro} appStore.sendMessage(prompt, 正在为你介绍${spot.name}).catch(() { connectError.value 自动讲解未发送成功可点击下方话题重试。 }) } })提示词中同时携带了 SYSTEM_PROMPT 定义的身份人设和景点专属的 guideIntro导游收到后会结合两者生成一段自然的讲解。整条链路从位置更新到接近检测再到讲解触发全部在前端完成由项目自研的 LBS 服务与 SDK 的 ask() 接口协同驱动。第五站随时打断追问——游客掌握主动权导游正在讲断桥的建造历史你突然想到一个问题“白娘子的传说和这座桥有什么关系”——好的导游会立刻停下当前讲解先回答你的问题再自然地回到主线。这种随时打断追问的能力来自 SDK 感知层在导游说话的同时仍然持续运行。前端通过监听 ASR 回调和对话状态变化来实现// src/stores/app.ts — 语音输入与打断真实代码 async startVoiceInput(): Promisevoid { if (!appState.avatar.agent) return appState.asr.isListening true try { await avatarService.startASR(appState.avatar.agent) } catch (error) { console.error([AppStore] startASR 失败:, error) appState.asr.isListening false } } async stopVoiceInput(): Promisevoid { if (!appState.avatar.agent) return appState.asr.isListening false try { await avatarService.stopASR(appState.avatar.agent) } catch (error) { console.error([AppStore] stopASR 失败:, error) } } interrupt(): void { if (!appState.avatar.agent) return avatarService.interrupt(appState.avatar.agent) avatarState.value interactive_idle }游客点击「语音提问」按钮SDK 内置的 ASR 开始工作识别结果通过 onASRResult 回调实时返回最终识别结果自动填入输入框。感知能力内置在同一个 SDK 中不需要额外对接外部语音识别服务。而打断更加直接——一行 agent.interrupt(‘speak’) 即可停止当前播报导游立即进入聆听状态等待游客的新问题。第六站多模态表达——语气、表情、手势统一生成导游在讲述西湖「水光潋滟晴方好」时语气轻柔在介绍长城时气势开阔在说到莫高窟飞天壁画时配合适当的手势和表情——这些表达形式由 SDK 内部统一生成并同步驱动。第二站展示的 agentCallbacks 中onAgentStateChange 实时追踪表达状态onConversationChange 感知对话阶段切换——这些回调在导游说话的同时照常运行游客随时可以打断追问。这整个链路在前端只需要一行代码触发// 游客接近景点 → 智能体推理 → 语音播报 口型 表情 手势 身体动作 // 所有表达形式在同一次交互中统一生成而非各自独立播放 await agent.ask(游客正在接近「西湖·断桥」。请用 2-3 句话简短欢迎并引出讲解。)而打断也是即时的// src/services/avatar.ts — 客户端即时打断真实代码 interrupt(agent: any): void { agent.interrupt(speak) }这就是数字行动智能体以具身交互智能体的形式在终端上与游客自然互动。SDK 内部将感知、理解、表达和行动连接在同一套状态管理体系中前端通过 agent.ask() 触发全链路通过 onAgentStateChange 感知表达状态通过 interrupt() 即时打断——三个接口覆盖完整的交互生命周期。星云端侧的 AI 端渲能力让这一切在浏览器中流畅运行——第二站的 connect 方法已经展示了完整的端侧渲染接入只需提供一个 DOM 容器SDK 自动在容器内启动渲染所有画面都在浏览器本地完成。对于景区公共场所的网络环境更低的延迟和更少的带宽占用尤为关键。当同一个智能体进入人形机器人或线下实体设备时同样的感知—理解—决策—表达链路延伸为物理行动在真实物理空间中与游客交互。智能体的身份、知识和业务能力在不同身体形态间持续复用。第七站自然旅行主题——把山河装进浏览器技术底座之上云游在视觉和交互设计上也形成了自己的气质。自然旅行主题森林绿主色#305c49搭配沙金强调色#e8d3a6和暖米白底色#f6f6ef字体选用宋体衬线搭配 Segoe UI 无衬线贴合旅行手册的温润质感和市面上千篇一律的蓝色科技风形成明显区隔。/* src/style.css — 自然旅行主题色真实代码 */ :root { font-family: Segoe UI, PingFang SC, Microsoft YaHei, sans-serif; color: #263e34; background: #f6f6ef; --forest: #305c49; --forest-deep: #203f33; --muted: #7d897b; --sand: #e8d3a6; --line: #e3e7dc; --paper: #fffffb; --red: #a8553e; }两栏漫游布局左侧主区域承载漫游英雄区SVG 山水意象 品牌标语、景点列表6 处精选风景按山岳/湖泊/古迹/园林/石窟分类筛选、SVG 互动地图景点标记 用户位置 导航路线 点击移动和景点详情面板右侧全高 AI 导游面板常驻渲染SDK 容器 字幕 文字/语音对话 随时打断。六处精选风景泰山·南天门山岳、西湖·断桥湖泊、故宫·太和殿古迹、长城·八达岭古迹、拙政园·远香堂园林、莫高窟·九层楼石窟。每个景点都内置了坐标、描述、亮点标签、游览建议和专属讲解引导词。接近即讲解游客在地图上移动接近景点时自动触发 AI 导游讲解不需要额外的操作步骤。到达后自动标记足迹打开我的足迹可以回顾本次漫游到过哪些风景。这些设计选择服务于同一个目标让具身交互智能体成为游客漫游体验的核心。终点站端到端具身交互智能让山水开口说话云游的实战把端到端具身交互智能的核心理念落到了代码里围绕一次完整的人机交互把感知、理解、决策、表达和行动连接成一套持续运行的系统——核心代码从传统管线的 2000 行缩减到约 500 行首字响应从 1.5~3 秒降到约 500ms打断即时生效项目自研 LBS 与 SDK 讲解联动状态全链路统一流转部署从四套服务分别对接收敛为一个 SDK 全链路打通。同一个智能体今天可以是 Web 端的景区导游明天可以出现在线下互动大屏或人形机器人上身份、知识和导游业务能力持续复用。魔珐星云是一套端到端具身交互智能平台让 AI 通过屏幕和机器人进入真实世界成为能够感知、理解、表达并行动的智能体——让每一处风景都能找到属于自己的导游。如果想基于魔珐星云平台搭建类似的端到端具身交互智能体欢迎访问官网体验。本文转自网络如有侵权请联系删除。