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

Update documentation for Realtime Agent Studio with enhanced content and structure

Browse Source 
- Revised site name and description for clarity and detail.
- Updated navigation structure to better reflect the organization of content.
- Improved changelog entries for better readability and consistency.
- Migrated assistant configuration and prompt guidelines to new documentation paths.
- Enhanced core concepts section to clarify the roles and capabilities of assistants and engines.
- Streamlined workflow documentation to provide clearer guidance on configuration and usage.
This commit is contained in:
Xin Wang
2026-03-09 05:38:43 +08:00
parent 65ae2287d5
commit b300b469dc
34 changed files with 1776 additions and 2981 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,221 +1,69 @@
# 快速开始
# 快速开始
5 分钟创建你的第一个 AI 助手。
本页负责“创建第一个助手”的最短路径。环境要求、配置文件和部署方式统一放在 [环境与部署](../getting-started/index.md)。
## 概述
## 目标
本指南将帮助你通过控制台快速创建一个能够进行语音对话的智能助手。在创建助手之前，需要先在资源库（Library）中配置所需的模型资源。
完成本页后，你应该已经：
1. 准备好 1 个 LLM、1 个 ASR、1 个 TTS 资源
2. 创建并保存 1 个助手
3. 完成至少 1 轮测试对话
4. 拿到接入应用所需的 `assistant_id` 和 WebSocket 地址
## 前提条件
- 已部署 Realtime Agent Studio (RAS) 服务
- 拥有 LLM / ASR / TTS 服务的 API Key
- 已部署 Realtime Agent Studio（RAS）服务
- 已准备可用的 LLM / ASR / TTS 凭证
- 已能访问控制台与 WebSocket 服务
## 配置流程
## 第一步：准备资源
创建助手前，需要先准备好三种核心资源：
创建助手之前，先准备三类资源：
```
┌─────────────────────────────────────────────────────────┐
│ 资源库配置 │
├─────────────────────────────────────────────────────────┤
│ 1. 语音识别 (ASR) ─→ 将用户语音转为文字 │
│ 2. 模型接入 (LLM) ─→ 理解用户意图并生成回复 │
│ 3. 声音资源 (TTS) ─→ 将文字回复转为语音输出 │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 创建助手 │
├─────────────────────────────────────────────────────────┤
│ 配置提示词 → 选择模型 → 配置语音 → 测试 → 发布 │
└─────────────────────────────────────────────────────────┘
```
- **LLM 模型**：决定助手如何理解和生成回复。详见 [LLM 模型](../customization/models.md)
- **ASR 资源**：决定语音输入如何转写。详见 [语音识别](../customization/asr.md)
- **TTS 声音资源**：决定回复如何被合成为语音。详见 [声音资源](../customization/voices.md)
---
## 第一步：配置资源库
在创建助手之前，需要先在资源库中添加 ASR、LLM、TTS 三种资源。
### 1.1 添加语音识别模型 (ASR)
语音识别模型负责将用户的语音输入转换为文字。
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 "试听功能"
添加完成后，可以在列表中点击播放按钮试听声音效果。
---
如果你想先检查“资源是否准备齐”，可以看 [资源准备清单](dashboard.md)。
## 第二步：创建助手
资源配置完成后，可以开始创建助手。
1. 进入控制台中的 **助手** 页面
2. 新建一个助手，并填写最小必要信息：
- **助手名称**：让团队知道它服务于什么场景
- **系统提示词**：先定义角色、任务和限制
- **首轮模式**：决定由助手先说还是等待用户开口
3. 绑定默认模型：
- 文本生成使用一个 LLM
- 语音输入使用一个 ASR
- 语音输出使用一个 TTS 声音资源
### 2.1 新建助手
如果你想把助手设计得更稳，继续阅读：
1. 在左侧导航栏点击 **助手管理**
2. 点击 **新建助手** 按钮
3. 系统会自动创建一个名为 "New Assistant" 的助手
- [助手概念](../concepts/assistants.md)
- [配置选项](../concepts/assistants/configuration.md)
- [提示词指南](../concepts/assistants/prompts.md)
### 2.2 配置全局设置
## 第三步：补充能力
在助手详情页的 **全局** 标签页中配置：
最小助手可以只依赖提示词和模型；更复杂的场景通常还需要以下能力：
#### 基本信息
- **知识库**：让助手回答私有领域问题。见 [知识库](../customization/knowledge-base.md)
- **工具**：让助手执行查单、预约、查询等外部操作。见 [工具](../customization/tools.md)
- **工作流**：让助手处理多步骤、多分支流程。见 [工作流](../customization/workflows.md)
- **助手名称**：修改为有意义的名称，如 "客服助手"
- **语言**：选择助手的对话语言
## 第四步：测试并发布
#### 系统提示词
1. 打开助手测试面板，先验证文本对话，再验证语音输入输出
2. 观察事件流、转写、工具调用和最终回复是否符合预期
3. 保存当前配置，并确认该助手已可用于外部接入
配置系统提示词，定义助手的角色和行为：
更系统的验证方式见 [测试调试](../concepts/assistants/testing.md)。
```
你是一个友好的客服助手。你的任务是帮助用户解答问题。
## 第五步：接入应用
要求：
- 保持友好和专业的语气
- 回答要简洁明了，每次回复控制在 2-3 句话
- 如果不确定答案，请如实告知
```
#### 开场白配置
设置对话开始时助手的问候语：
- **首回合模式**：选择 "助手先说" 让助手主动开场
- **开场白内容**：如 "你好，我是智能客服助手，请问有什么可以帮您？"
### 2.3 配置模型
在 **模型** 标签页中选择之前添加的资源：
| 配置项 | 说明 |
|-------|------|
| LLM 模型 | 选择在模型接入中添加的大语言模型 |
| ASR 模型 | 选择在语音识别中添加的 ASR 模型 |
### 2.4 配置语音
在 **语音** 标签页中配置：
| 配置项 | 说明 |
|-------|------|
| 启用语音输出 | 开启后助手会用语音回复 |
| 选择声音 | 选择在声音资源中添加的音色 |
| 语速 | 可微调当前助手的说话速度 |
### 2.5 保存配置
完成配置后，点击页面顶部的 **保存** 按钮。
---
## 第三步：测试助手
### 3.1 打开测试面板
点击助手卡片右上角的 **测试** 按钮，打开实时调试面板。
### 3.2 进行对话测试
| 测试场景 | 示例问题 | 预期结果 |
|---------|---------|---------|
| 基础问候 | "你好" | 助手友好回应 |
| 功能询问 | "你能做什么？" | 介绍自身能力 |
| 业务问题 | 根据你的场景设计 | 正确回答 |
| 边界测试 | 无关问题 | 婉拒或引导 |
### 3.3 检查各环节
在调试面板中可以看到：
- **ASR 输出**：用户语音识别结果
- **LLM 输入/输出**：模型的输入和生成内容
- **TTS 状态**：语音合成状态
---
## 第四步：发布助手
测试通过后：
1. 点击 **发布** 按钮
2. 复制生成的连接信息：
- `assistant_id`：用于 API 调用
- WebSocket 地址：用于实时对话
### 嵌入到应用
最小接入方式是使用 WebSocket API 建立实时会话：
```javascript
const ws = new WebSocket('ws://your-server/ws?assistant_id=YOUR_ASSISTANT_ID');
@@ -223,54 +71,28 @@ const ws = new WebSocket('ws://your-server/ws?assistant_id=YOUR_ASSISTANT_ID');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'session.start',
audio: {
encoding: 'pcm_s16le',
sample_rate_hz: 16000,
channels: 1
}
audio: { encoding: 'pcm_s16le', sample_rate_hz: 16000, channels: 1 }
}));
};
ws.onmessage = (event) => {
console.log('收到消息:', event.data);
};
```
---
你通常只需要两项信息：
## 常见问题
- `assistant_id`：指定接入哪个助手
- WebSocket 地址：由引擎服务提供实时对话入口
### 资源库中添加模型失败？
完整协议见 [WebSocket 协议](../api-reference/websocket.md)。
1. 检查 API Key 是否正确
2. 确认 Base URL 格式正确（通常以 `/v1` 结尾）
3. 验证网络能否访问对应的 API 服务
## 常见卡点
### 助手不回复？
1. 检查是否已选择 LLM 模型
2. 确认 LLM 模型配置正确（可在模型接入页面预览测试）
3. 查看浏览器控制台是否有错误
### 语音识别不准确？
1. 检查是否选择了正确的语言
2. 尝试添加热词提高专有名词识别率
3. 确保录音设备工作正常
### 语音无法播放？
1. 检查浏览器是否允许自动播放音频
2. 确认已选择声音并正确配置
3. 在声音资源页面点击试听确认配置正确
---
- 资源配置不生效：回到 [资源准备清单](dashboard.md) 检查三类资源是否都已准备好
- 助手不回复：先看 [测试调试](../concepts/assistants/testing.md)，再进入 [故障排查](../resources/troubleshooting.md)
- 回复质量不稳定：优先检查 [提示词指南](../concepts/assistants/prompts.md) 与 [知识库](../customization/knowledge-base.md)
## 下一步
恭喜！你已成功创建了第一个 AI 助手。接下来可以：
- [环境与部署](../getting-started/index.md) - 补全环境、配置和部署细节
- [构建助手](../concepts/assistants.md) - 深入配置助手、模型、知识库、工具与工作流
- [API 参考](../api-reference/index.md) - 查看管理接口与实时协议
- [配置知识库](../customization/knowledge-base.md) - 让助手回答专业问题
- [添加工具](../customization/tools.md) - 扩展助手能力
- [查看 API 文档](../api-reference/websocket.md) - 深入了解协议细节
- [Docker 部署](../deployment/index.md) - 使用容器运行