mirror of
https://github.com/sipeed/sipeed_wiki.git
synced 2026-09-11 00:22:49 -05:00
docs: add NanoKVM Go Voice Bridge quick start
Add Chinese and English Voice Bridge quick-start docs, sync sidebar entry, and organize localized screenshots for the realtime voice setup flow. Co-authored-by: taorye <taorye@outlook.com>
This commit is contained in:
liangziyue
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.0 KiB |
213
docs/hardware/en/kvm/NanoKVM_Go/realtime_voice_bridge.md
Normal file
213
docs/hardware/en/kvm/NanoKVM_Go/realtime_voice_bridge.md
Normal file
@@ -0,0 +1,213 @@
|
||||
---
|
||||
title: NanoKVM Go Realtime Voice Chat Quick Start
|
||||
keywords: NanoKVM Go, Qwen Audio, realtime voice, Voice Bridge
|
||||
update:
|
||||
- date: 2026-08-05
|
||||
version: v1.0
|
||||
author: Liang Ziyue
|
||||
content:
|
||||
- Added the English quick-start guide for Voice Bridge
|
||||
- Added the Virtual Audio prerequisite
|
||||
---
|
||||
|
||||
# Realtime Voice Chat Quick Start
|
||||
|
||||
## Voice Bridge Overview
|
||||
|
||||
Voice Bridge is a realtime voice bridge App that runs on NanoKVM Go. It forwards two-way audio between the controlled host's audio devices and a cloud realtime voice model, so a caller can talk to an AI assistant directly through a phone call.
|
||||
|
||||
In this example, Voice Bridge uses Qwen Audio Realtime. The caller's voice is sent from the controlled host to Qwen through NanoKVM Go, and the model's generated voice is sent back to the controlled host through the NanoKVM Go UAC2 virtual microphone. The App also shows transcripts for both sides on the device screen.
|
||||
|
||||
```text
|
||||
Caller phone -> controlled host call audio -> NanoKVM Go -> Qwen Audio Realtime
|
||||
Caller phone <- controlled host call audio <- NanoKVM Go <- Qwen Audio Realtime
|
||||
```
|
||||
|
||||
## What You Can Build
|
||||
|
||||
Voice Bridge can be used to quickly build and verify:
|
||||
|
||||
- AI phone customer-service demos;
|
||||
- realtime voice assistants and voice bots;
|
||||
- call-test setups with live transcripts;
|
||||
- prompt, voice, and realtime model validation workflows.
|
||||
|
||||
This guide only covers installing and running the official device-side App. You do not need to understand MCP, WebRTC, Opus, or audio resampling to try it. If you plan to replace the model, add a knowledge base or Agent, or customize the audio pipeline, first complete this quick start and confirm that the base workflow works.
|
||||
|
||||
## Final Result
|
||||
|
||||
After installation, open `Voice Bridge` from the NanoKVM Go `Apps` page, then start a phone call. The device screen shows the running status and transcripts:
|
||||
|
||||
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 12px; align-items: start;">
|
||||
<img src="./../../../assets/NanoKVM/go/realtime_voice_bridge/voice-bridge-app-fb0.webp" alt="NanoKVM Go Voice Bridge App interface" style="width: 100%;">
|
||||
<video src="./../../../assets/NanoKVM/go/realtime_voice_bridge/app-voice-bridge.mp4" aria-label="NanoKVM Go Voice Bridge App demo" style="width: 100%;" playsinline controls autoplay loop muted preload="metadata"></video>
|
||||
</div>
|
||||
|
||||
## Before You Start
|
||||
|
||||
Before installing the App, make sure that:
|
||||
|
||||
- NanoKVM Go is connected to the controlled host, and you can access its web interface;
|
||||
- the NanoKVM Go system and application are updated to the latest versions;
|
||||
- NanoKVM Go can access the internet to download App dependencies and connect to Qwen;
|
||||
- the phone is connected according to the device requirements and can make calls normally;
|
||||
- the controlled host can detect the NanoKVM Go UAC2 virtual microphone and speaker devices;
|
||||
- you have an Alibaba Cloud account, or you are ready to register one and enable Alibaba Cloud Model Studio.
|
||||
|
||||
> If the web settings do not include `Apps` or `MCP Service`, check for and install the latest NanoKVM Go system and application updates.
|
||||
|
||||
## Get Connection Information
|
||||
|
||||
Before installing the App, prepare the NanoKVM Go MCP API key, plus the Qwen Workspace ID and API key.
|
||||
|
||||
### Enable MCP Service
|
||||
|
||||
Open the NanoKVM Go web interface, go to `Settings > AI > MCP Service`, enable MCP Service, and copy the `API Key` shown on the page. Voice Bridge uses this key to create two-way NanoKVM Go audio sessions.
|
||||
|
||||
|
||||
|
||||
> Do not share the MCP API key with others, and do not write real keys into source code or public repositories.
|
||||
|
||||
### Enable Virtual Audio
|
||||
|
||||
Open the NanoKVM Go web interface, go to `Settings > Device > Virtual Audio`, and enable Virtual Audio. Then check the controlled host's system audio settings and confirm that the NanoKVM Go UAC2 virtual microphone and speaker devices are detected.
|
||||
|
||||
|
||||
|
||||
### Get Qwen Connection Information
|
||||
|
||||
1. Open the [Alibaba Cloud Model Studio console](https://modelstudio.console.alibabacloud.com/), register or sign in to an Alibaba Cloud account, and enable Model Studio as prompted.
|
||||
2. Select a region that supports realtime voice models, such as `China (Beijing)` or `Singapore`.
|
||||
|
||||
|
||||
|
||||
3. Open the `API Key` page.
|
||||
|
||||
|
||||
|
||||
4. Create an API key for `Voice Bridge`. Copy and save the full key immediately after it is created.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
5. After the key is created, the page shows an `API Host` value. It may be shown as a hostname or as part of a full endpoint URL. `QWEN_WORKSPACE_ID` is the leading `ws-...` part of that host.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
API Host:
|
||||
https://ws-xxxxxxxxxxxxxxxx.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
|
||||
```
|
||||
|
||||
In this case, enter the following value for `Qwen Workspace ID`:
|
||||
|
||||
```text
|
||||
ws-xxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
6. Confirm the realtime voice model name and region available to your account in the Model Studio console or the [Qwen-Omni-Realtime documentation](https://www.alibabacloud.com/help/en/model-studio/realtime).
|
||||
|
||||
When configuring Voice Bridge later, the required Qwen fields are:
|
||||
|
||||
- `Qwen Workspace ID` (`QWEN_WORKSPACE_ID`);
|
||||
- `Qwen API key` (`QWEN_API_KEY`).
|
||||
|
||||
`Qwen region` and `Qwen realtime model` can use the App form defaults first. Change them only if your account region or model access differs.
|
||||
|
||||
Available models, regions, quotas, and free usage may vary by account. Use the Model Studio console as the source of truth.
|
||||
|
||||
## Install and Configure Voice Bridge
|
||||
|
||||
Voice Bridge can be installed directly from the built-in Sipeed official App Server on NanoKVM Go. SSH, SCP, `apt install`, and manual `pip install` are not required.
|
||||
|
||||
1. Log in to the NanoKVM Go web interface and open `Settings > Apps > Store`.
|
||||
2. Select the built-in Sipeed official repository.
|
||||
|
||||
|
||||
|
||||
3. Find `Voice Bridge`, then click `Install`.
|
||||
|
||||
|
||||
|
||||
4. Wait for the installation configuration window to open.
|
||||
5. Fill in the automatically generated environment form. The web form shows user-facing field names, while the App saves them as environment variables internally. For a first test, you usually only need to fill in `NanoKVM MCP API key`, `Qwen Workspace ID`, and `Qwen API key`; keep the other fields at their defaults.
|
||||
|
||||
| Web form field | Environment variable | Description |
|
||||
| --- | --- | --- |
|
||||
| `Turn detection` | `INTERACT_TYPE` | Has a default value. Sets the turn detection mode. Available values include `server_vad` and `smart_turn`. |
|
||||
| `NanoKVM MCP API key` | `NANOKVM_MCP_KEY` | Get it from the NanoKVM Go `MCP Service` page. |
|
||||
| `Qwen API key` | `QWEN_API_KEY` | Create it in the Model Studio console. |
|
||||
| `Assistant instructions` | `QWEN_INSTRUCTIONS` | Has a default value. Sets the assistant identity, response style, and task requirements. |
|
||||
| `Base64 instructions` | `QWEN_INSTRUCTIONS_B64` | Optional. Base64-encoded UTF-8 instructions. If set, this overrides regular instructions. Leave it empty for the first test. |
|
||||
| `Qwen realtime model` | `QWEN_MODEL` | Has a default value. Change it only if your account requires a different available realtime voice model. |
|
||||
| `Qwen region` | `QWEN_REGION` | Has a default value. Change it only if your Qwen service and Workspace use a different region. |
|
||||
| `Session rotation interval` | `QWEN_SESSION_ROTATE_SECONDS` | Has a default value. Sets the interval for rotating the Qwen session. |
|
||||
| `Qwen voice` | `QWEN_VOICE` | Has a default value. Sets the voice used by model responses. |
|
||||
| `Qwen Workspace ID` | `QWEN_WORKSPACE_ID` | Get it from the `ws-...` prefix of the Model Studio `API Host`. |
|
||||
|
||||
|
||||
|
||||
> Field names and default values may change with App updates. Use the current environment form and Qwen official documentation as the source of truth.
|
||||
|
||||
6. After filling in the form, click `Install` and keep the `Installation log` window open until the page shows that installation succeeded.
|
||||
|
||||
Voice Bridge automatically installs build dependencies and installs pinned Python dependencies into the App's own `python/` directory. The first installation downloads and builds ARM dependencies, so it usually takes several minutes. The log window shows package download, build, and installation progress.
|
||||
|
||||
|
||||
|
||||
If installation fails, click `Copy log`, save the full log, and check the end of the log for network, package source, storage, or Python package build errors.
|
||||
|
||||
After installation, you can update the Voice Bridge environment configuration from `Settings > Apps > Installed`. New values take effect the next time the App starts.
|
||||
|
||||
|
||||
|
||||
## Run and Test
|
||||
|
||||
### Start the App
|
||||
|
||||
1. Open the `Apps` page on the NanoKVM Go touchscreen.
|
||||
2. Select `Voice Bridge` and launch it.
|
||||
3. Wait until the App reports that the model and audio connections are ready.
|
||||
|
||||
<video src="./../../../assets/NanoKVM/go/realtime_voice_bridge/app-voice-bridge.mp4" aria-label="NanoKVM Go Voice Bridge App startup and running demo" style="width: 60%; max-width: 480px; display: block; margin: 0 auto;" playsinline controls autoplay loop muted preload="metadata"></video>
|
||||
|
||||
### Start a Voice Conversation
|
||||
|
||||
1. Make a phone call and answer it on the controlled host.
|
||||
2. Speak into the phone.
|
||||
3. Confirm that the NanoKVM Go screen shows the user transcript.
|
||||
4. Wait for Qwen to respond, and confirm that the model transcript appears.
|
||||
5. Confirm that the model voice response is sent back to the phone through the controlled host.
|
||||
|
||||
This workflow has been verified with Android phones and iPhones.
|
||||
|
||||
## FAQ
|
||||
|
||||
### The Controlled Host Cannot Hear the Model Response
|
||||
|
||||
In the controlled host's system audio settings or call software, select the NanoKVM Go UAC2 virtual microphone as the input device, and check that the input is not muted.
|
||||
|
||||
### The App Does Not Receive Phone Audio
|
||||
|
||||
Confirm that the phone call is using USB audio, and select the NanoKVM Go UAC2 virtual speaker in the controlled host's system audio settings or call software. This workflow cannot use DP audio to transfer phone call media.
|
||||
|
||||
### The App Cannot Connect to Qwen
|
||||
|
||||
Check that `Qwen API key`, `Qwen Workspace ID`, `Qwen region`, and `Qwen realtime model` match, and confirm that NanoKVM Go can access the internet. Model permissions, quota, or rate limits on the account may also cause connection failures.
|
||||
|
||||
### Configuration Changes Do Not Take Effect
|
||||
|
||||
Exit Voice Bridge, save the new configuration from `Settings > Apps > Installed`, and restart the App. New environment values take effect the next time the App starts.
|
||||
|
||||
### How to Exit the App
|
||||
|
||||
After Voice Bridge exits, it closes the model, WebRTC, and media sessions, and it does not keep playing audio in the background. For the common App exit gesture and management method, see [Custom Apps: Exit an App](./custom_app.html#exit-app).
|
||||
|
||||
## Learn More and Customize
|
||||
|
||||
The official device-side example source code is in the [`voice-bridge/` directory of the NanoKVM-Go-Apps `main` branch](https://github.com/sipeed/NanoKVM-Go-Apps/tree/main/voice-bridge). The shared App SDK and development documentation are in the [`base` branch](https://github.com/sipeed/NanoKVM-Go-Apps/tree/base).
|
||||
|
||||
If you need to replace Qwen, connect another realtime voice model, or add a knowledge base, Agent, business tools, or custom audio processing, refer to the App source code and SDK documentation.
|
||||
|
||||
References: [NanoKVM-Go-Apps](https://github.com/sipeed/NanoKVM-Go-Apps) · [Alibaba Cloud Model Studio console](https://modelstudio.console.alibabacloud.com/) · [Get an API key](https://www.alibabacloud.com/help/en/model-studio/apikey) · [Get a Workspace ID](https://help.aliyun.com/en/model-studio/obtain-the-app-id-and-workspace-id) · [Qwen-Omni-Realtime documentation](https://www.alibabacloud.com/help/en/model-studio/realtime)
|
||||
@@ -572,6 +572,10 @@ items:
|
||||
file: kvm/NanoKVM_Go/system/flashing.md
|
||||
- label: Custom Apps
|
||||
file: kvm/NanoKVM_Go/custom_app.md
|
||||
- label: AI Realtime Voice Chat
|
||||
items:
|
||||
- label: Quick Start
|
||||
file: kvm/NanoKVM_Go/realtime_voice_bridge.md
|
||||
- label: FAQ
|
||||
file: kvm/NanoKVM_Go/faq.md
|
||||
- label: NanoKVM PCIe
|
||||
|
||||
229
docs/hardware/zh/kvm/NanoKVM_Go/realtime_voice_bridge.md
Normal file
229
docs/hardware/zh/kvm/NanoKVM_Go/realtime_voice_bridge.md
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
title: NanoKVM Go 实时语音对话快速体验
|
||||
keywords: NanoKVM Go, Qwen Audio, 实时语音, Voice Bridge
|
||||
update:
|
||||
- date: 2026-08-05
|
||||
version: v1.3
|
||||
author: Liang Ziyue
|
||||
content:
|
||||
- 补充启用虚拟音频的前置步骤
|
||||
- 优化 Qwen 连接信息获取说明
|
||||
- date: 2026-08-03
|
||||
version: v1.2
|
||||
author: Liang Ziyue
|
||||
content:
|
||||
- 重整快速体验流程并补充截图占位
|
||||
- date: 2026-07-30
|
||||
version: v1.1
|
||||
author: taonyx
|
||||
content:
|
||||
- 更新为 App Server 自动安装依赖和 environment 配置流程
|
||||
---
|
||||
|
||||
# 实时语音对话快速体验
|
||||
|
||||
## Voice Bridge 简介
|
||||
|
||||
Voice Bridge 是运行在 NanoKVM Go 上的实时语音桥接 APP。它在被控主机的音频设备与云端实时语音模型之间转发双向音频，让拨号端用户可以通过通话直接与 AI 对话。
|
||||
|
||||
在本文的示例中，Voice Bridge 使用 Qwen Audio Realtime：通话中的用户语音经 NanoKVM Go 发送给模型，模型生成的语音再通过 NanoKVM Go 的 UAC2 虚拟麦克风送回被控主机。APP 同时会在设备屏幕上显示双方的语音转写文本。
|
||||
|
||||
```text
|
||||
拨号手机 → 被控主机的通话音频 → NanoKVM Go → Qwen Audio Realtime
|
||||
拨号手机 ← 被控主机的通话音频 ← NanoKVM Go ← Qwen Audio Realtime
|
||||
```
|
||||
|
||||
## 可以用来做什么
|
||||
|
||||
通过 Voice Bridge，可以快速搭建和验证以下应用：
|
||||
|
||||
- AI 电话客服或语音应答演示；
|
||||
- 实时语音助手和对话机器人；
|
||||
- 带语音转写的通话测试环境；
|
||||
- 实时语音模型、提示词和音色的效果验证。
|
||||
|
||||
本文只介绍如何安装并运行官方设备端 APP，适合希望先体验功能的用户，不要求了解 MCP、WebRTC、Opus 或音频重采样。如果你准备替换模型、加入知识库或 Agent，或者修改音频链路，请先按本文跑通示例，再阅读[实时语音二次开发](./realtime_voice_bridge_technical.html)。
|
||||
|
||||
## 最终效果
|
||||
|
||||
安装完成后，在 NanoKVM Go 的 `Apps` 页面打开 `Voice Bridge`，然后使用手机拨号即可开始实时语音对话。设备屏幕会显示运行状态和双方的 transcript：
|
||||
|
||||
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 12px; align-items: start;">
|
||||
<img src="./../../../assets/NanoKVM/go/realtime_voice_bridge/voice-bridge-app-fb0.webp" alt="NanoKVM Go 设备端 Voice Bridge APP 界面" style="width: 100%;">
|
||||
<video src="./../../../assets/NanoKVM/go/realtime_voice_bridge/app-voice-bridge.mp4" aria-label="NanoKVM Go 设备端 Voice Bridge APP 运行演示" style="width: 100%;" playsinline controls autoplay loop muted preload="metadata"></video>
|
||||
</div>
|
||||
|
||||
## 使用前准备
|
||||
|
||||
开始安装前，请确认：
|
||||
|
||||
- NanoKVM Go 已连接被控主机，并且可以正常访问网页控制端；
|
||||
- NanoKVM Go 的系统和应用已更新至最新版本；
|
||||
- NanoKVM Go 可以访问互联网，以便下载 APP 依赖并连接 Qwen；
|
||||
- 手机已按设备要求接入 NanoKVM Go，并且可以正常拨打电话；
|
||||
- 被控主机可以识别 NanoKVM Go 的 UAC2 虚拟麦克风和扬声器设备；
|
||||
- 已准备阿里云账号，或准备按本文注册并开通阿里云百炼服务。
|
||||
|
||||
> 如果网页设置中没有 `Apps` 或 `MCP Service` 选项，请先检查并更新 NanoKVM Go 的系统和应用版本。
|
||||
|
||||
## 获取连接信息
|
||||
|
||||
安装 APP 前，需要准备 NanoKVM Go 的 MCP API key，以及 Qwen 的 Workspace ID 和 API key。
|
||||
|
||||
### 启用 MCP Service
|
||||
|
||||
进入 `设置 > AI > MCP 服务`，启用 MCP 服务并记录页面显示的 `API key`。该密钥用于允许 Voice Bridge 创建 NanoKVM Go 双向音频会话。
|
||||
|
||||
|
||||
|
||||
> 不要将 MCP API key 分享给他人，也不要把真实密钥写入源码或提交到公开仓库。
|
||||
|
||||
### 启用虚拟音频
|
||||
|
||||
进入 `设置 > 设备 > 虚拟音频`，启用虚拟音频。然后在被控主机的系统音频设置中，确认 NanoKVM Go 的 UAC2 虚拟麦克风和扬声器设备均已被识别。
|
||||
|
||||
|
||||
|
||||
### 获取 Qwen 连接信息
|
||||
|
||||
1. 打开 [阿里云百炼控制台](https://bailian.console.aliyun.com/)，注册或登录阿里云账号，并按页面提示开通百炼模型服务；
|
||||
2. 在控制台右上角选择支持实时语音模型的地域，例如 `华北2（北京）` 或 `新加坡`；
|
||||
|
||||
|
||||
|
||||
3. 进入 `API Key` 页面；
|
||||
|
||||
|
||||
|
||||
4. 创建用于 `Voice Bridge` 的 `API Key`。创建成功后请立即复制并妥善保存完整密钥；
|
||||
|
||||
|
||||
|
||||
5. 创建完成后，页面会显示 `OpenAI compatible` 和 `Anthropic` 两类兼容接口地址。`QWEN_WORKSPACE_ID` 就是接口地址域名最前面的 `ws-...` 这一段；
|
||||
|
||||
例如接口地址为：
|
||||
|
||||
```text
|
||||
OpenAI compatible:
|
||||
https://ws-xxxxxxxxxxxxxxxx.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
|
||||
|
||||
Anthropic:
|
||||
https://ws-xxxxxxxxxxxxxxxx.cn-beijing.maas.aliyuncs.com/apps/anthropic
|
||||
```
|
||||
|
||||
则 `QWEN_WORKSPACE_ID` 填写：
|
||||
|
||||
```text
|
||||
ws-xxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
|
||||
|
||||
6. 在百炼控制台或 [Qwen-Omni-Realtime 文档](https://help.aliyun.com/zh/model-studio/realtime)中确认账号当前可用的实时语音模型名称和地域。
|
||||
|
||||
后续配置 Voice Bridge 时，必须填写的 Qwen 字段为：
|
||||
|
||||
- `Qwen Workspace ID`（对应 `QWEN_WORKSPACE_ID`）；
|
||||
- `Qwen API key`（对应 `QWEN_API_KEY`）。
|
||||
|
||||
`Qwen region` 和 `Qwen realtime model` 可以先使用 APP 表单中的默认值；如果你的百炼账号、地域或模型权限不同，再按控制台信息修改。
|
||||
|
||||
不同账号的可用模型、地域和免费额度可能不同，请以百炼控制台显示的信息为准。
|
||||
|
||||
|
||||
## 安装并配置 Voice Bridge
|
||||
|
||||
Voice Bridge 可以直接从 NanoKVM Go 内置的 Sipeed 官方 App Server 安装，无需使用 SSH、SCP，也不需要手动执行 `apt install` 或 `pip install`。
|
||||
|
||||
1. 登录 NanoKVM Go 网页控制端，进入 `设置 > 应用 > 应用商店`；
|
||||
|
||||
2. 选择内置的 Sipeed 官方仓库；
|
||||
|
||||
|
||||
|
||||
3. 找到 `Voice Bridge`，然后点击 `安装`；
|
||||
|
||||
|
||||
|
||||
4. 等待安装配置窗口打开。
|
||||
|
||||
5. 在自动生成的环境变量表单中填写连接信息。网页表单显示的是配置项名称，APP 内部会把它们保存为对应的环境变量。首次体验时通常只需要填写 `NanoKVM MCP API key`、`Qwen Workspace ID` 和 `Qwen API key`，其他字段可以先保留默认值。
|
||||
|
||||
| 网页显示项 | 对应环境变量 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `Turn detection` | `INTERACT_TYPE` | 有默认值；用于设置轮次检测模式，可选择 `server_vad` 或 `smart_turn` |
|
||||
| `NanoKVM MCP API key` | `NANOKVM_MCP_KEY` | 在 NanoKVM Go 的 `MCP Service` 页面获取 |
|
||||
| `Qwen API key` | `QWEN_API_KEY` | 在百炼控制台创建 API Key |
|
||||
| `Assistant instructions` | `QWEN_INSTRUCTIONS` | 有默认值；用于设置模型的身份、回答方式和任务要求 |
|
||||
| `Base64 instructions` | `QWEN_INSTRUCTIONS_B64` | 可选；填写后会覆盖普通 instructions，首次体验建议留空 |
|
||||
| `Qwen realtime model` | `QWEN_MODEL` | 有默认值；如账号模型权限不同，再改为当前可用的实时语音模型 |
|
||||
| `Qwen region` | `QWEN_REGION` | 有默认值；如账号地域不同，再改为与 Qwen 服务和 Workspace 匹配的地域 |
|
||||
| `Session rotation interval` | `QWEN_SESSION_ROTATE_SECONDS` | 有默认值；用于设置 Qwen 会话轮换间隔 |
|
||||
| `Qwen voice` | `QWEN_VOICE` | 有默认值；用于设置模型回复使用的音色 |
|
||||
| `Qwen Workspace ID` | `QWEN_WORKSPACE_ID` | 从百炼兼容接口地址的 `ws-...` 前缀获取 |
|
||||
|
||||
|
||||
|
||||
> 页面中的具体字段和默认值可能随 APP 版本更新，请以当前环境变量表单和 Qwen 官方文档为准。
|
||||
|
||||
6. 填写完成后，点击安装，并保持 `安装日志` 窗口打开，直到页面显示安装成功。
|
||||
|
||||
Voice Bridge 的安装脚本会自动安装编译依赖，并把固定版本的 Python 依赖安装到 APP 自己的 `python/` 目录。首次安装需要下载和构建 ARM 依赖，通常需要等待数分钟。日志窗口会实时显示软件包下载、构建和安装进度。
|
||||
|
||||
|
||||
|
||||
如果安装失败，请点击 `复制日志` 保存完整日志，并重点检查日志末尾是否出现网络、软件源、存储空间或 Python 包构建错误。
|
||||
|
||||
安装后可以随时在 `设置 > 应用 > 已安装` 中修改 Voice Bridge 的环境变量配置，新配置会在 APP 下次启动时生效。
|
||||
|
||||
|
||||
|
||||
## 运行并测试
|
||||
|
||||
### 启动 APP
|
||||
|
||||
1. 在 NanoKVM Go 触摸屏上进入 `Apps` 页面；
|
||||
2. 选择 `Voice Bridge` 并启动；
|
||||
3. 等待 APP 显示模型和音频连接已就绪。
|
||||
|
||||
<video src="./../../../assets/NanoKVM/go/realtime_voice_bridge/app-voice-bridge.mp4" aria-label="NanoKVM Go 设备端 Voice Bridge APP 启动和运行演示" style="width: 60%; max-width: 480px; display: block; margin: 0 auto;" playsinline controls autoplay loop muted preload="metadata"></video>
|
||||
|
||||
### 发起语音对话
|
||||
|
||||
1. 使用手机拨号，并让被控主机接通；
|
||||
2. 对着手机说一句话；
|
||||
3. 确认 NanoKVM Go 屏幕出现 User transcript；
|
||||
4. 等待 Qwen 回复，确认屏幕出现模型 transcript；
|
||||
5. 确认模型回复的语音能够通过被控主机传回手机。
|
||||
|
||||
已在 Android 和 iPhone 手机上验证该流程可用。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 被控主机听不到模型回复
|
||||
|
||||
在被控主机的系统音频或通话软件中，确认输入设备已选择 NanoKVM Go 的 UAC2 虚拟麦克风，并检查该输入设备是否被静音。
|
||||
|
||||
### APP 没有收到手机声音
|
||||
|
||||
确认手机通话使用的是 USB 音频，并在被控主机的系统音频或通话软件中选择 NanoKVM Go 的 UAC2 虚拟扬声器。当前流程不能使用 DP 音频传输手机通话媒体。
|
||||
|
||||
### APP 无法连接 Qwen
|
||||
|
||||
检查 `Qwen API key`、`Qwen Workspace ID`、`Qwen region` 和 `Qwen realtime model` 是否匹配，并确认 NanoKVM Go 可以访问互联网。账号的模型权限、额度或限流状态也可能导致连接失败。
|
||||
|
||||
### 修改配置后没有生效
|
||||
|
||||
退出 Voice Bridge，在 `设置 > 应用 > 已安装` 中保存新配置后重新启动 APP。环境变量的新值在 APP 下次启动时生效。
|
||||
|
||||
### 如何退出 APP
|
||||
|
||||
退出 Voice Bridge 后，APP 会关闭模型、WebRTC 和媒体会话，不会继续在后台播放。APP 的通用退出手势和管理方法请参考[自定义 APP：退出 APP](./custom_app.html#exit-app)。
|
||||
|
||||
## 了解原理和二次开发
|
||||
|
||||
官方设备端示例源码位于 [NanoKVM-Go-Apps `main` 分支的 `voice-bridge/`](https://github.com/sipeed/NanoKVM-Go-Apps/tree/main/voice-bridge)，共享 App SDK 和开发文档位于该仓库的 [`base` 分支](https://github.com/sipeed/NanoKVM-Go-Apps/tree/base)。
|
||||
|
||||
如果你需要替换 Qwen、接入其他实时语音模型，或者加入知识库、Agent、业务工具和自定义音频处理，请继续阅读[实时语音二次开发](./realtime_voice_bridge_technical.html)。
|
||||
|
||||
参考：[NanoKVM-Go-Apps](https://github.com/sipeed/NanoKVM-Go-Apps) · [阿里云百炼控制台](https://bailian.console.aliyun.com/) · [获取 API Key](https://help.aliyun.com/zh/model-studio/get-api-key) · [获取 Workspace ID](https://help.aliyun.com/zh/model-studio/obtain-the-app-id-and-workspace-id) · [Qwen-Omni-Realtime 文档](https://help.aliyun.com/zh/model-studio/realtime)
|
||||
@@ -573,6 +573,12 @@ items:
|
||||
file: kvm/NanoKVM_Go/system/flashing.md
|
||||
- label: 扩展：自定义 APP
|
||||
file: kvm/NanoKVM_Go/custom_app.md
|
||||
- label: AI 实时语音对话
|
||||
items:
|
||||
- label: 快速体验
|
||||
file: kvm/NanoKVM_Go/realtime_voice_bridge.md
|
||||
- label: 二次开发
|
||||
file: kvm/NanoKVM_Go/realtime_voice_bridge_technical.md
|
||||
- label: FAQ
|
||||
file: kvm/NanoKVM_Go/faq.md
|
||||
- label: NanoKVM PCIe
|
||||
|
||||
Reference in New Issue
Block a user