wx44wx/AI-VideoAssistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation to enhance clarity and resource configuration for RAS

Browse Source 
- Revised the introduction in index.md to emphasize the need for resource configuration before creating an AI assistant.
- Added a new section detailing the configuration process for ASR, LLM, and TTS resources.
- Updated the quickstart guide to reflect the new resource management steps and included troubleshooting tips for common issues.
- Removed the outdated API guide as it has been integrated into the new resource configuration workflow.
This commit is contained in:
Xin Wang
2026-03-02 17:30:48 +08:00
parent 85315ba6ca
commit a003134477
4 changed files with 420 additions and 419 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
docs/content/quickstart/index.md
View File

@@ -4,99 +4,221 @@
## 概述
本指南将帮助你快速创建一个能够进行语音对话的智能助手。你可以选择通过控制台或 API 两种方式创建。
本指南将帮助你通过控制台快速创建一个能够进行语音对话的智能助手。在创建助手之前，需要先在资源库（Library）中配置所需的模型资源。
## 前提条件
- 已部署 Realtime Agent Studio (RAS) 服务
- 已配置至少一个 LLM 模型
- 已配置至少一个 TTS 语音
- 拥有 LLM / ASR / TTS 服务的 API Key
## 选择创建方式
## 配置流程
| 方式 | 适用场景 | 复杂度 |
|------|---------|--------|
| [通过控制台](dashboard.md) | 快速体验、可视化配置 | 简单 |
| [通过 API](api.md) | 程序化创建、批量管理 | 中等 |
创建助手前，需要先准备好三种核心资源：
```
┌─────────────────────────────────────────────────────────┐
│ 资源库配置 │
├─────────────────────────────────────────────────────────┤
│ 1. 语音识别 (ASR) ─→ 将用户语音转为文字 │
│ 2. 模型接入 (LLM) ─→ 理解用户意图并生成回复 │
│ 3. 声音资源 (TTS) ─→ 将文字回复转为语音输出 │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 创建助手 │
├─────────────────────────────────────────────────────────┤
│ 配置提示词 → 选择模型 → 配置语音 → 测试 → 发布 │
└─────────────────────────────────────────────────────────┘
```
---
## 方式一：通过控制台创建
## 第一步：配置资源库
### 步骤 1：创建助手
在创建助手之前，需要先在资源库中添加 ASR、LLM、TTS 三种资源。
1. 登录控制台，进入 **助手管理** 页面
2. 点击 **新建助手**
3. 输入助手名称，如 "客服助手"
### 1.1 添加语音识别模型 (ASR)
### 步骤 2：配置提示词
语音识别模型负责将用户的语音输入转换为文字。
在 **全局设置** 中配置系统提示词：
1. 在左侧导航栏点击 **语音识别**
2. 点击 **添加模型** 按钮
3. 填写配置信息：
| 配置项 | 说明 | 示例值 |
|-------|------|--------|
| 模型名称 | 自定义显示名称 | SenseVoice CN |
| 接口类型 | 选择 OpenAI Compatible | OpenAI Compatible |
| 语言 | 识别语言 | 中文 (Chinese) |
| Model Name | 模型标识符 | FunAudioLLM/SenseVoiceSmall |
| Base URL | API 服务地址 | https://api.siliconflow.cn/v1 |
| API Key | 服务密钥 | sk-xxxxxxxx |
4. 可选配置：
- **热词**：添加专有名词提高识别准确率
- **标点增强**：自动添加标点符号
- **文本归一化**：规范化数字、日期等格式
5. 点击 **确认添加**
!!! tip "试听识别功能"
添加完成后，可以点击列表中的试听按钮，上传或录制音频测试识别效果。
### 1.2 添加大语言模型 (LLM)
大语言模型是助手的"大脑"，负责理解用户意图并生成回复。
1. 在左侧导航栏点击 **模型接入**
2. 点击 **添加模型** 按钮
3. 填写配置信息：
| 配置项 | 说明 | 示例值 |
|-------|------|--------|
| 厂商 | 接口类型 | OpenAI Compatible |
| 模型类型 | 文本/嵌入/重排 | 文本 |
| 模型名称 | 自定义显示名称 | GPT-4o Mini |
| 模型标识 | API 中的 model 参数 | gpt-4o-mini |
| Base URL | API 服务地址 | https://api.openai.com/v1 |
| API Key | 服务密钥 | sk-xxxxxxxx |
| 温度 | 输出随机性 (0-2) | 0.7 |
| 上下文长度 | 最大 token 数 | 8192 |
4. 点击 **确认添加**
!!! tip "预览功能"
添加完成后，可以点击预览按钮测试模型是否配置正确。
### 1.3 添加声音资源 (TTS)
声音资源用于将助手的文字回复转换为语音输出。
1. 在左侧导航栏点击 **声音资源**
2. 点击 **添加声音** 按钮
3. 填写配置信息：
| 配置项 | 说明 | 示例值 |
|-------|------|--------|
| 厂商 | 接口类型 | OpenAI Compatible 或 DashScope |
| 声音名称 | 自定义显示名称 | 客服小美 |
| 模型 | TTS 模型标识 | FunAudioLLM/CosyVoice2-0.5B |
| 声音 ID | 音色标识 | FunAudioLLM/CosyVoice2-0.5B:anna |
| Base URL | API 服务地址 | https://api.siliconflow.cn/v1 |
| API Key | 服务密钥 | sk-xxxxxxxx |
| 语速 | 说话速度 (0.5-2.0) | 1.0 |
| 增益 | 音量调节 (-10 to 10 dB) | 0 |
| 音调 | 声音高低 (-12 to 12) | 0 |
| 性别 | 声音性别 | 女 |
| 语言 | 声音语言 | 中文 |
4. 点击 **确认添加**
!!! tip "试听功能"
添加完成后，可以在列表中点击播放按钮试听声音效果。
---
## 第二步：创建助手
资源配置完成后，可以开始创建助手。
### 2.1 新建助手
1. 在左侧导航栏点击 **助手管理**
2. 点击 **新建助手** 按钮
3. 系统会自动创建一个名为 "New Assistant" 的助手
### 2.2 配置全局设置
在助手详情页的 **全局** 标签页中配置：
#### 基本信息
- **助手名称**：修改为有意义的名称，如 "客服助手"
- **语言**：选择助手的对话语言
#### 系统提示词
配置系统提示词，定义助手的角色和行为：
```
你是一个友好的客服助手。你的任务是帮助用户解答问题。
要求：
- 保持友好和专业的语气
- 回答要简洁明了
- 回答要简洁明了，每次回复控制在 2-3 句话
- 如果不确定答案，请如实告知
```
### 步骤 3：配置语音
#### 开场白配置
在 **语音配置** 中：
设置对话开始时助手的问候语：
1. 选择 TTS 引擎
2. 选择合适的音色
3. 调整语速为 1.0
- **首回合模式**：选择 "助手先说" 让助手主动开场
- **开场白内容**：如 "你好，我是智能客服助手，请问有什么可以帮您？"
### 步骤 4：测试助手
### 2.3 配置模型
1. 点击 **保存**
2. 点击 **测试** 按钮
3. 输入 "你好，你能做什么？"
4. 验证回复是否符合预期
在 **模型** 标签页中选择之前添加的资源：
### 步骤 5：发布助手
| 配置项 | 说明 |
|-------|------|
| LLM 模型 | 选择在模型接入中添加的大语言模型 |
| ASR 模型 | 选择在语音识别中添加的 ASR 模型 |
1. 确认测试通过后，点击 **发布**
2. 复制生成的 `assistant_id`
### 2.4 配置语音
在 **语音** 标签页中配置：
| 配置项 | 说明 |
|-------|------|
| 启用语音输出 | 开启后助手会用语音回复 |
| 选择声音 | 选择在声音资源中添加的音色 |
| 语速 | 可微调当前助手的说话速度 |
### 2.5 保存配置
完成配置后，点击页面顶部的 **保存** 按钮。
---
## 方式二：通过 API 创建
## 第三步：测试助手
### 步骤 1：创建助手
### 3.1 打开测试面板
```bash
curl -X POST "http://localhost:8080/api/v1/assistants" \
-H "Content-Type: application/json" \
-d '{
"name": "客服助手",
"prompt": "你是一个友好的客服助手。",
"language": "zh-CN",
"temperature": 0.7
}'
```
点击助手卡片右上角的 **测试** 按钮，打开实时调试面板。
### 步骤 2：配置语音
### 3.2 进行对话测试
```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/{assistant_id}" \
-H "Content-Type: application/json" \
-d '{
"voice": {
"vendor": "aliyun",
"voice_id": "xiaoyun",
"speed": 1.0
}
}'
```
| 测试场景 | 示例问题 | 预期结果 |
|---------|---------|---------|
| 基础问候 | "你好" | 助手友好回应 |
| 功能询问 | "你能做什么？" | 介绍自身能力 |
| 业务问题 | 根据你的场景设计 | 正确回答 |
| 边界测试 | 无关问题 | 婉拒或引导 |
### 步骤 3：测试连接
### 3.3 检查各环节
在调试面板中可以看到：
- **ASR 输出**：用户语音识别结果
- **LLM 输入/输出**：模型的输入和生成内容
- **TTS 状态**：语音合成状态
---
## 第四步：发布助手
测试通过后：
1. 点击 **发布** 按钮
2. 复制生成的连接信息：
- `assistant_id`：用于 API 调用
- WebSocket 地址：用于实时对话
### 嵌入到应用
```javascript
const ws = new WebSocket('ws://localhost:8000/ws?assistant_id=YOUR_ASSISTANT_ID');
const ws = new WebSocket('ws://your-server/ws?assistant_id=YOUR_ASSISTANT_ID');
ws.onopen = () => {
ws.send(JSON.stringify({
@@ -116,6 +238,34 @@ ws.onmessage = (event) => {
---
## 常见问题
### 资源库中添加模型失败？
1. 检查 API Key 是否正确
2. 确认 Base URL 格式正确（通常以 `/v1` 结尾）
3. 验证网络能否访问对应的 API 服务
### 助手不回复？
1. 检查是否已选择 LLM 模型
2. 确认 LLM 模型配置正确（可在模型接入页面预览测试）
3. 查看浏览器控制台是否有错误
### 语音识别不准确？
1. 检查是否选择了正确的语言
2. 尝试添加热词提高专有名词识别率
3. 确保录音设备工作正常
### 语音无法播放？
1. 检查浏览器是否允许自动播放音频
2. 确认已选择声音并正确配置
3. 在声音资源页面点击试听确认配置正确
---
## 下一步
恭喜！你已成功创建了第一个 AI 助手。接下来可以：