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

247
docs/content/quickstart/dashboard.md
View File

@@ -1,233 +1,44 @@
# 资源库配置详解
# 资源准备清单
本页面详细介绍资源库中各类资源的配置方法和最佳实践。
本页保留原“资源库配置详解”链接，但在本轮文档收敛后，它只承担快速开始阶段的资源核对职责。
## 语音识别 (ASR) 配置
## 你至少要准备什么
### 支持的接口类型
在创建第一个助手前，至少确认以下三类资源都已经可用：
| 接口类型 | 说明 |
|---------|------|
| OpenAI Compatible | 兼容 OpenAI 语音识别 API 格式的服务 |
| 资源 | 为什么需要 | 正式说明页 |
|------|------------|------------|
| **LLM 模型** | 负责理解与生成回复 | [LLM 模型](../customization/models.md) |
| **ASR 资源** | 负责把语音输入转写为文本 | [语音识别](../customization/asr.md) |
| **TTS 声音资源** | 负责把文本回复合成为语音 | [声音资源](../customization/voices.md) |
### 配置字段说明
## 上手前自检
| 字段 | 必填 | 说明 |
|-----|-----|------|
| 模型名称 | 是 | 自定义显示名称，便于识别 |
| 接口类型 | 是 | 当前支持 OpenAI Compatible |
| 语言 | 是 | 识别语言：中文/英文/多语言 |
| Model Name | 否 | API 请求中的 model 参数 |
| Base URL | 是 | API 服务地址 |
| API Key | 是 | 服务认证密钥 |
| 热词 | 否 | 逗号分隔的专有名词列表 |
| 标点增强 | 否 | 是否自动添加标点 |
| 文本归一化 | 否 | 规范化数字、日期等格式 |
| 启用 | 否 | 是否在选择列表中显示 |
### LLM
### 推荐配置示例
- 已配置供应商、模型名称、Base URL 和凭证
- 已明确该模型用于文本生成、嵌入还是重排
- 已准备保守的默认参数，而不是先追求极端效果
**硅基流动 SenseVoice**
### ASR
```
模型名称：SenseVoice 中文
Model Name：FunAudioLLM/SenseVoiceSmall
Base URL：https://api.siliconflow.cn/v1
语言：中文
```
- 已确认目标语言与模型匹配
- 已准备必要热词或专有名词词表
- 已能用固定样本测试识别准确率和延迟
### 测试识别效果
### TTS
1. 在 ASR 列表中找到目标模型
2. 点击 **试听识别** 按钮
3. 选择以下测试方式之一：
- **上传文件**：拖拽或选择音频文件
- **麦克风录音**：点击录音按钮开始录制
4. 点击 **开始识别** 查看结果
5. 检查识别文本、延迟和置信度
- 已选择主音色，并完成至少一次试听
- 已确认该声音适合实时对话，而不是仅适合离线播报
- 已为默认语速、音量等参数设定初始值
---
## 不在本页展开的内容
## 大语言模型 (LLM) 配置
字段说明、供应商差异、参数建议和最佳实践已经分别收敛到正式能力页：
### 支持的模型类型
- [LLM 模型](../customization/models.md)
- [语音识别](../customization/asr.md)
- [声音资源](../customization/voices.md)
- [TTS 参数](../customization/tts.md)
| 类型 | 用途 |
|-----|------|
| 文本 (text) | 对话生成，用于助手核心交互 |
| 嵌入 (embedding) | 向量化，用于知识库检索 |
| 重排 (rerank) | 结果重排序，优化检索结果 |
### 配置字段说明
| 字段 | 必填 | 说明 |
|-----|-----|------|
| 厂商 | 是 | 当前支持 OpenAI Compatible |
| 模型类型 | 是 | 文本/嵌入/重排 |
| 模型名称 | 是 | 自定义显示名称 |
| 模型标识 | 否 | API 请求中的 model 参数 |
| Base URL | 是 | API 服务地址 |
| API Key | 是 | 服务认证密钥 |
| 温度 | 否 | 输出随机性 (0-2)，仅文本模型 |
| 上下文长度 | 否 | 最大 token 数 |
| 启用 | 否 | 是否在选择列表中显示 |
### 推荐配置示例
**OpenAI GPT-4o Mini**
```
模型名称：GPT-4o Mini
模型类型：文本
模型标识：gpt-4o-mini
Base URL：https://api.openai.com/v1
温度：0.7
上下文长度：8192
```
**硅基流动 Qwen**
```
模型名称：Qwen2.5-7B
模型类型：文本
模型标识：Qwen/Qwen2.5-7B-Instruct
Base URL：https://api.siliconflow.cn/v1
温度：0.7
```
### 测试模型效果
1. 在 LLM 列表中找到目标模型
2. 点击 **预览** 按钮
3. 配置测试参数：
- **System Prompt**：系统提示词
- **User Message**：测试消息
- **Temperature**：温度参数
- **Max Tokens**：最大输出长度
4. 点击 **开始预览** 查看模型回复
5. 检查回复内容、延迟和 token 用量
---
## 声音资源 (TTS) 配置
### 支持的接口类型
| 接口类型 | 说明 |
|---------|------|
| OpenAI Compatible | 兼容 OpenAI TTS API 格式的服务 |
| DashScope | 阿里云 DashScope 语音合成服务 |
### 配置字段说明
| 字段 | 必填 | 说明 |
|-----|-----|------|
| 厂商 | 是 | OpenAI Compatible 或 DashScope |
| 声音名称 | 是 | 自定义显示名称 |
| 模型 | 是 | TTS 模型标识 |
| 声音 ID | 是 | 音色标识符 |
| Base URL | 否 | API 服务地址 |
| API Key | 是 | 服务认证密钥 |
| 语速 | 否 | 说话速度 (0.5-2.0)，默认 1.0 |
| 增益 | 否 | 音量调节 (-10 to 10 dB) |
| 音调 | 否 | 声音高低 (-12 to 12) |
| 性别 | 否 | 声音性别标签 |
| 语言 | 否 | 声音语言标签 |
| 备注 | 否 | 声音特点描述 |
### 推荐配置示例
**硅基流动 CosyVoice**
```
厂商：OpenAI Compatible
声音名称：Anna 中文女声
模型：FunAudioLLM/CosyVoice2-0.5B
声音 ID：FunAudioLLM/CosyVoice2-0.5B:anna
Base URL：https://api.siliconflow.cn/v1
语速：1.0
性别：女
语言：中文
```
**DashScope TTS**
```
厂商：DashScope
声音名称：Cherry
模型：qwen3-tts-flash-realtime
声音 ID：Cherry
Base URL：wss://dashscope.aliyuncs.com/api-ws/v1/realtime
语速：1.0
```
### CosyVoice 可用音色
| 音色 ID | 性别 | 风格 |
|--------|-----|------|
| alex | 男 | 成熟稳重 |
| anna | 女 | 温柔亲切 |
| bella | 女 | 活泼甜美 |
| benjamin | 男 | 年轻活力 |
| charles | 男 | 专业商务 |
| claire | 女 | 清新自然 |
| david | 男 | 沉稳大气 |
| diana | 女 | 优雅知性 |
### 试听声音效果
1. 在声音列表中找到目标声音
2. 点击 **播放** 按钮
3. 系统会自动合成一段试听语音
4. 检查声音效果是否符合预期
### 克隆声音
如需使用自定义声音：
1. 点击 **克隆声音** 按钮
2. 上传参考音频文件（WAV/MP3）
3. 填写声音名称和描述
4. 点击 **开始克隆**
!!! note "声音克隆说明"
声音克隆功能需要 TTS 服务支持。上传的参考音频建议为 10-30 秒的清晰人声录音。
---
## 配置最佳实践
### 资源命名规范
建议使用清晰的命名规范，便于后续管理：
```
[厂商/模型]-[用途/语言]-[特点]
```
示例：
- `SF-SenseVoice-中文`
- `OpenAI-GPT4o-对话`
- `SF-CosyVoice-Anna女声`
### 多环境管理
如果有测试和生产环境，建议：
1. 为不同环境创建独立的资源配置
2. 在名称中标注环境，如 `GPT4o-Prod`、`GPT4o-Test`
3. 通过"启用"开关控制可见性
### 成本优化
| 场景 | 推荐配置 |
|-----|---------|
| 开发测试 | 使用低成本模型，如 GPT-4o-mini |
| 生产环境 | 根据质量要求选择合适模型 |
| 高并发 | 考虑使用本地部署的开源模型 |
---
## 下一步
资源配置完成后，请返回 [快速开始](index.md) 继续创建助手。
准备完成后，请回到 [快速开始](index.md) 继续创建助手。

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) - 使用容器运行