This commit is contained in:
Xin Wang
2026-03-02 22:51:03 +08:00
11 changed files with 550 additions and 435 deletions

View File

@@ -1,6 +1,6 @@
# 错误码
本文档列出 AI Video Assistant API 的所有错误码及其说明。
本文档列出 Realtime Agent Studio (RAS) API 的所有错误码及其说明。
## 协议错误

View File

@@ -1,10 +1,10 @@
# API 参考
本节提供 AI Video Assistant 的完整 API 文档。
本节提供 Realtime Agent Studio (RAS) 的完整 API 文档。
## API 概览
AI Video Assistant 提供两种类型的 API
Realtime Agent Studio (RAS) 提供两种类型的 API
| API 类型 | 用途 | 协议 |
|---------|------|------|
@@ -229,4 +229,4 @@ async with client.connect(assistant.id) as conv:
- [WebSocket 协议](websocket.md) - 实时对话协议详解
- [错误码](errors.md) - 错误处理参考
- [快速开始](../quickstart/api.md) - API 使用示例
- [快速开始](../quickstart/index.md) - 快速创建助手

View File

@@ -1,6 +1,6 @@
# 助手管理
助手是 AI Video Assistant 的核心模块,用于创建和配置智能对话机器人。每个助手都可以独立配置提示词、语音、知识库和工具。
助手是 Realtime Agent Studio (RAS) 的核心模块,用于创建和配置智能对话机器人。每个助手都可以独立配置提示词、语音、知识库和工具。
## 概述

View File

@@ -1,6 +1,6 @@
# 部署指南
本章节介绍如何将 AI Video Assistant 部署到生产环境。
本章节介绍如何将 Realtime Agent Studio (RAS) 部署到生产环境。
## 部署方式

View File

@@ -1,6 +1,6 @@
# 生产环境部署
本文档介绍如何将 AI Video Assistant 部署到生产环境,包括 Nginx 配置、SSL 证书、性能优化等。
本文档介绍如何将 Realtime Agent Studio (RAS) 部署到生产环境,包括 Nginx 配置、SSL 证书、性能优化等。
## Nginx 部署

View File

@@ -1,10 +1,10 @@
# 安装部署
本章节介绍如何安装和配置 AI Video Assistant 开发环境。
本章节介绍如何安装和配置 Realtime Agent Studio (RAS) 开发环境。
## 概述
AI Video Assistant 由以下组件构成:
Realtime Agent Studio (RAS) 由以下组件构成:
| 组件 | 说明 |
|------|------|

View File

@@ -1,9 +1,62 @@
# AI Video Assistant
# 实时交互智能体工作平台RAS
AI Video Assistant 是一款基于大语言模型的智能对话与工作流管理平台支持模型集成、语音合成、自动化测试等功能,帮助企业快速构建智能客服系统
实时交互智能体工作平台Realtime Agent Studio简称 RAS是一款大语言模型为核心,构建实时交互音视频智能体的工作平台支持管线式的全双工交互引擎和原生多模态模型两种核心,覆盖实时交互智能体构建过程中的配置、测试、发布、监控流程环节,平台包含大模型集成、语音识别、语音合成、自动化测试等功能,帮助用户快速构建实时交互智能体
可以将该平台看作VapiRetellElevenAgents的开源替代。
![仪表盘](images/dashboard.png)
## 功能特色
### 实时交互引擎
平台的核心是一个低延迟、高并发的实时交互引擎,支持两种架构模式:
- **管线式全双工引擎**将语音识别ASR、大语言模型LLM、语音合成TTS串联成流水线支持语音打断实现自然的对话体验
- **原生多模态模型支持**:直接接入 GPT-4o Realtime、Gemini Live 等端到端多模态模型,获得更低延迟和更自然的语音交互
- **智能打断处理**支持基于声音活动和语义的turn-detection模型引擎自动处理音频截断和状态同步
### 智能体配置管理
提供可视化的智能体配置界面,无需编码即可创建和调整智能体:
- **系统提示词编辑**:支持角色设定,会话动态变量
- **模型选择与参数调优**:灵活切换 LLM/ASR/TTS 供应商,调整温度、采样等参数
- **工具/函数调用配置**webhook工具通过网络请求访问外部资源客户端工具通过与用户交互获取信息以及内建工具比如代码执行器计算工具。
- **知识库关联**:接入 RAG 系统,让智能体基于私有文档回答问题
- **工作流编辑**:使用可视化流程编辑器构建包含多个环节的交互助手及其上下文切换
### 交互测试工具
内置完整的测试工具链,保障智能体上线质量:
- **实时调试控制台**:在线测试体验智能体交互 ASR/LLM/TTS 各环节的输入输出
- **自动化测试工具**支持固定测试预设问答对批量测试和智能测试AI自动生成测试用例自动执行并生成测试报告
### 开放接口
提供标准化的 API 接口,便于集成到现有系统:
- **WebSocket 实时协议**:支持音视频流式传输、双向通信
- **RESTful 管理接口**:助手 CRUD、会话管理、配置导入导出
- **Webhook 回调**:会话开始/结束、工具调用、异常告警等事件通知
- **SDK 支持**:提供 JavaScript、Python、移动端 SDK简化客户端集成
### 交互历史监控
全面的会话记录和数据分析能力:
- **完整会话回放**保存音频、转写文本、LLM 响应、工具调用的完整链路
- **实时仪表盘**:并发会话数、平均响应时间、错误率等关键指标可视化
- **会话检索与筛选**:按时间、助手、用户、关键词等维度快速定位会话
### 自主部署
支持私有化部署,数据安全可控:
- **Docker 一键部署**:提供 docker-compose 配置,一行命令启动完整平台
- **模型本地化**:支持云端模型和本地私有化模型两种方案
## 核心功能
| 功能模块 | 描述 |
@@ -16,6 +69,75 @@ AI Video Assistant 是一款基于大语言模型的智能对话与工作流管
| **自动化测试** | 批量测试与质量评估 |
| **仪表盘** | 实时数据统计与可视化分析 |
## 开发计划Roadmap
### 已完成 (Completed)
#### 实时交互引擎
- [x] 管线式全双工引擎 - ASR/LLM/TTS 流水线
- [x] 智能打断处理 - VAD + EOU 检测
- [x] OpenAI兼容的 ASR TTS 接口适配
- [x] DashScope TTS 接口适配
#### 智能体配置管理
- [x] 系统提示词编辑 - prompt 配置,动态变量注入
- [x] 模型选择 - LLM/ASR/TTS 模型管理
- [x] 工具调用配置 - webhook 工具 + 客户端工具
#### 交互测试工具
- [x] 实时调试控制台 - WebSocket 调试连接示例
#### 开放接口
- [x] WebSocket 协议 - /ws 端点
- [x] RESTful 接口 - 完整的 CRUD API
#### 交互历史监控
- [x] 完整会话回放 - 音频 + 转写 + LLM 响应
- [x] 会话检索筛选 - 按时间/助手/状态筛选
---
### 开发中 (In Progress)
#### 智能体配置管理
- [ ] 私有化部署的 ASR TTS 适配
- [ ] 工作流编辑 - 可视化流程编排
- [ ] 知识库关联 - RAG 文档管理
#### 实时交互引擎
- [ ] 原生多模态模型支持 - 由于GPT-4o Realtime, Gemini Live国内环境问题计划加入Step Audio
#### 开放接口
- [ ] SDK 支持 - JavaScript/Python SDK
- [ ] WebRTC 协议 - /webrtc 端点
#### 效果评估
- [ ] 自动化测试工具 - 固定测试 + 智能测试
---
### 待实现 (To Do)
#### 开放接口
- [ ] Webhook 回调 - 会话事件通知
#### 效果评估
- [ ] 实时仪表盘 - 基础统计看板,需完善
---
## 技术栈
| 层级 | 技术 |
|------|------|
| Frontend | React, TypeScript, Tailwind CSS |
| State | Zustand, React Query |
| Backend | FastAPI (Python) |
| Engine | Python |
| Database | SQLite |
---
## 快速导航
<div class="grid cards" markdown>
@@ -53,7 +175,3 @@ AI Video Assistant 是一款基于大语言模型的智能对话与工作流管
使用问题与故障排查
</div>
## 技术支持
如有问题,请提交 Issue 或联系技术支持团队。

View File

@@ -1,241 +0,0 @@
# 通过 API 创建助手
本指南介绍如何通过 REST API 程序化创建和管理 AI 助手。
## 前提条件
- 已部署 API 服务(默认端口 8080
- 已配置 LLM 和 TTS 模型
- 有可用的 HTTP 客户端curl、Postman 等)
## 步骤 1创建助手
### 请求
```bash
curl -X POST "http://localhost:8080/api/v1/assistants" \
-H "Content-Type: application/json" \
-d '{
"name": "客服助手",
"prompt": "你是一个友好的客服助手,负责解答用户问题。保持简洁、专业的回复风格。",
"opener": "你好,我是客服助手,请问有什么可以帮您?",
"language": "zh-CN",
"temperature": 0.7,
"max_tokens": 2048
}'
```
### 响应
```json
{
"success": true,
"data": {
"id": "asst_abc123",
"name": "客服助手",
"prompt": "你是一个友好的客服助手...",
"opener": "你好,我是客服助手...",
"language": "zh-CN",
"temperature": 0.7,
"created_at": "2025-01-01T00:00:00Z"
}
}
```
记下返回的 `id`,后续步骤需要使用。
## 步骤 2配置语音
### 配置 TTS
```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
-H "Content-Type: application/json" \
-d '{
"voice": {
"vendor": "aliyun",
"voice_id": "xiaoyun",
"speed": 1.0,
"volume": 80,
"pitch": 1.0
}
}'
```
### 配置 ASR
```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
-H "Content-Type: application/json" \
-d '{
"asr": {
"vendor": "sensevoice",
"language": "zh-CN"
}
}'
```
## 步骤 3关联 LLM 模型
```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
-H "Content-Type: application/json" \
-d '{
"llm_id": "llm_xyz789"
}'
```
## 步骤 4关联知识库可选
```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
-H "Content-Type: application/json" \
-d '{
"knowledge_base_id": "kb_def456",
"knowledge": {
"similarity_threshold": 0.7,
"top_k": 3
}
}'
```
## 步骤 5发布助手
```bash
curl -X POST "http://localhost:8080/api/v1/assistants/asst_abc123/publish"
```
## 步骤 6测试 WebSocket 连接
### JavaScript 示例
```javascript
const assistantId = 'asst_abc123';
const ws = new WebSocket(`ws://localhost:8000/ws?assistant_id=${assistantId}`);
ws.onopen = () => {
console.log('连接已建立');
// 发送 session.start
ws.send(JSON.stringify({
type: 'session.start',
audio: {
encoding: 'pcm_s16le',
sample_rate_hz: 16000,
channels: 1
}
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('收到事件:', data.type);
if (data.type === 'session.started') {
// 发送文本消息测试
ws.send(JSON.stringify({
type: 'input.text',
text: '你好,你能做什么?'
}));
}
if (data.type === 'assistant.response.final') {
console.log('助手回复:', data.data.text);
}
};
ws.onerror = (error) => {
console.error('连接错误:', error);
};
ws.onclose = () => {
console.log('连接已关闭');
};
```
### Python 示例
```python
import asyncio
import websockets
import json
async def test_assistant():
uri = "ws://localhost:8000/ws?assistant_id=asst_abc123"
async with websockets.connect(uri) as ws:
# 发送 session.start
await ws.send(json.dumps({
"type": "session.start",
"audio": {
"encoding": "pcm_s16le",
"sample_rate_hz": 16000,
"channels": 1
}
}))
# 等待 session.started
response = await ws.recv()
print(f"收到: {response}")
# 发送文本消息
await ws.send(json.dumps({
"type": "input.text",
"text": "你好,你能做什么?"
}))
# 接收响应
while True:
response = await ws.recv()
data = json.loads(response)
print(f"事件: {data['type']}")
if data['type'] == 'assistant.response.final':
print(f"回复: {data['data']['text']}")
break
asyncio.run(test_assistant())
```
## 完整 API 参考
### 助手管理 API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/assistants | 获取助手列表 |
| POST | /api/v1/assistants | 创建助手 |
| GET | /api/v1/assistants/{id} | 获取助手详情 |
| PATCH | /api/v1/assistants/{id} | 更新助手 |
| DELETE | /api/v1/assistants/{id} | 删除助手 |
| POST | /api/v1/assistants/{id}/publish | 发布助手 |
### 助手字段说明
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 助手名称 |
| prompt | string | 是 | 系统提示词 |
| opener | string | 否 | 开场白 |
| language | string | 否 | 语言代码 |
| temperature | number | 否 | 温度参数0-1 |
| max_tokens | number | 否 | 最大输出长度 |
| llm_id | string | 否 | 关联的 LLM 模型 ID |
| voice | object | 否 | TTS 配置 |
| asr | object | 否 | ASR 配置 |
## 错误处理
常见错误及解决方案:
| 错误码 | 说明 | 解决方案 |
|--------|------|---------|
| 400 | 请求参数错误 | 检查请求体格式 |
| 404 | 助手不存在 | 确认 assistant_id 正确 |
| 500 | 服务器错误 | 查看服务端日志 |
## 下一步
- [WebSocket 协议详解](../api-reference/websocket.md)
- [错误码参考](../api-reference/errors.md)
- [配置知识库](../customization/knowledge-base.md)

View File

@@ -1,149 +1,233 @@
# 通过控制台创建助手
# 资源库配置详解
指南详细介绍如何通过 Web 控制台创建和配置 AI 助手
页面详细介绍资源库中各类资源的配置方法和最佳实践
## 步骤 1登录控制台
## 语音识别 (ASR) 配置
1. 打开浏览器访问控制台地址(如 `http://localhost:3000`
2. 使用账号密码登录
### 支持的接口类型
## 步骤 2创建助手
| 接口类型 | 说明 |
|---------|------|
| OpenAI Compatible | 兼容 OpenAI 语音识别 API 格式的服务 |
![创建助手](../images/assistants.png)
### 配置字段说明
1. 在左侧导航栏点击 **助手管理**
2. 点击右上角 **新建助手** 按钮
3. 在弹出的对话框中输入:
- **助手名称**:为你的助手起一个名字,如 "产品咨询助手"
- **描述**:简单描述助手的用途(可选)
| 字段 | 必填 | 说明 |
|-----|-----|------|
| 模型名称 | 是 | 自定义显示名称,便于识别 |
| 接口类型 | 是 | 当前支持 OpenAI Compatible |
| 语言 | 是 | 识别语言:中文/英文/多语言 |
| Model Name | 否 | API 请求中的 model 参数 |
| Base URL | 是 | API 服务地址 |
| API Key | 是 | 服务认证密钥 |
| 热词 | 否 | 逗号分隔的专有名词列表 |
| 标点增强 | 否 | 是否自动添加标点 |
| 文本归一化 | 否 | 规范化数字、日期等格式 |
| 启用 | 否 | 是否在选择列表中显示 |
4. 点击 **创建**
### 推荐配置示例
## 步骤 3配置基本设置
创建完成后,你将进入助手配置页面。
### 全局设置
| 配置项 | 建议值 | 说明 |
|-------|--------|------|
| 系统提示词 | 见下方示例 | 定义助手的角色和行为 |
| 开场白 | "你好,我是产品咨询助手,请问有什么可以帮您?" | 对话开始时的问候 |
| 温度 | 0.7 | 平衡创意和准确性 |
### 系统提示词示例
**硅基流动 SenseVoice**
```
你是一个专业的产品咨询助手。你的主要任务是:
1. 解答用户关于产品功能的问题
2. 提供使用建议和最佳实践
3. 帮助用户解决常见问题
请注意:
- 保持友好和专业的语气
- 回答简洁明了,避免冗长
- 如果不确定答案,请如实告知并建议联系人工客服
- 不要编造不存在的功能或信息
模型名称SenseVoice 中文
Model NameFunAudioLLM/SenseVoiceSmall
Base URLhttps://api.siliconflow.cn/v1
语言:中文
```
## 步骤 4配置语音
### 测试识别效果
切换到 **语音配置** 标签页:
1. 在 ASR 列表中找到目标模型
2. 点击 **试听识别** 按钮
3. 选择以下测试方式之一:
- **上传文件**:拖拽或选择音频文件
- **麦克风录音**:点击录音按钮开始录制
4. 点击 **开始识别** 查看结果
5. 检查识别文本、延迟和置信度
### TTS 设置
---
1. **选择 TTS 引擎**
- 阿里云:多音色、高自然度
- 火山引擎:低延迟
- Minimax高性价比
## 大语言模型 (LLM) 配置
2. **选择音色**
- 根据助手定位选择合适的声音
- 建议先试听再确定
### 支持的模型类型
3. **调整参数**
- 语速1.0(正常速度)
- 音量80%
- 音调1.0
| 类型 | 用途 |
|-----|------|
| 文本 (text) | 对话生成,用于助手核心交互 |
| 嵌入 (embedding) | 向量化,用于知识库检索 |
| 重排 (rerank) | 结果重排序,优化检索结果 |
### ASR 设置
### 配置字段说明
1. **选择 ASR 引擎**
- Whisper通用识别
- SenseVoice中文识别更准
| 字段 | 必填 | 说明 |
|-----|-----|------|
| 厂商 | 是 | 当前支持 OpenAI Compatible |
| 模型类型 | 是 | 文本/嵌入/重排 |
| 模型名称 | 是 | 自定义显示名称 |
| 模型标识 | 否 | API 请求中的 model 参数 |
| Base URL | 是 | API 服务地址 |
| API Key | 是 | 服务认证密钥 |
| 温度 | 否 | 输出随机性 (0-2),仅文本模型 |
| 上下文长度 | 否 | 最大 token 数 |
| 启用 | 否 | 是否在选择列表中显示 |
2. **设置语言**
- 选择 "中文" 或 "自动检测"
### 推荐配置示例
## 步骤 5关联知识库可选
**OpenAI GPT-4o Mini**
如果你已创建知识库,可以在 **知识** 标签页进行关联:
1. 点击 **添加知识库**
2. 选择要关联的知识库
3. 设置检索参数:
- 相似度阈值0.7
- 返回数量3
## 步骤 6测试助手
1. 点击页面右上角的 **保存** 按钮
2. 点击 **测试** 按钮打开测试面板
3. 进行对话测试:
**测试用例建议:**
| 测试类型 | 示例问题 |
|---------|---------|
| 基础问候 | "你好" |
| 功能询问 | "你能做什么?" |
| 业务问题 | "产品有哪些功能?" |
| 边界测试 | "帮我写一首诗" |
4. 检查回复是否符合预期
5. 如有问题,返回修改配置
## 步骤 7发布助手
测试通过后:
1. 点击 **发布** 按钮
2. 确认发布
3. 复制生成的信息:
- `assistant_id`:用于 API 调用
- WebSocket 地址:用于实时对话
## 嵌入到网页
发布后,你可以将助手嵌入到你的网站:
```html
<!-- 添加到你的网页 -->
<script>
const ws = new WebSocket('ws://your-server/ws?assistant_id=YOUR_ASSISTANT_ID');
// ... 实现对话逻辑
</script>
```
模型名称GPT-4o Mini
模型类型:文本
模型标识gpt-4o-mini
Base URLhttps://api.openai.com/v1
温度0.7
上下文长度8192
```
详细集成指南请参考 [API 参考](../api-reference/websocket.md)。
**硅基流动 Qwen**
## 常见问题
```
模型名称Qwen2.5-7B
模型类型:文本
模型标识Qwen/Qwen2.5-7B-Instruct
Base URLhttps://api.siliconflow.cn/v1
温度0.7
```
### 助手不回复?
### 测试模型效果
1. 检查 LLM 模型是否配置正确
2. 查看浏览器控制台是否有错误
3. 确认后端服务正常运行
1. LLM 列表中找到目标模型
2. 点击 **预览** 按钮
3. 配置测试参数:
- **System Prompt**:系统提示词
- **User Message**:测试消息
- **Temperature**:温度参数
- **Max Tokens**:最大输出长度
4. 点击 **开始预览** 查看模型回复
5. 检查回复内容、延迟和 token 用量
### 语音无法播放?
---
1. 检查浏览器是否允许自动播放
2. 确认 TTS 配置正确
3. 检查音量设置
## 声音资源 (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
声音 IDFunAudioLLM/CosyVoice2-0.5B:anna
Base URLhttps://api.siliconflow.cn/v1
语速1.0
性别:女
语言:中文
```
**DashScope TTS**
```
厂商DashScope
声音名称Cherry
模型qwen3-tts-flash-realtime
声音 IDCherry
Base URLwss://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 |
| 生产环境 | 根据质量要求选择合适模型 |
| 高并发 | 考虑使用本地部署的开源模型 |
---
## 下一步
- [通过 API 创建助手](api.md)
- [配置知识库](../customization/knowledge-base.md)
- [添加工具](../customization/tools.md)
资源配置完成后,请返回 [快速开始](index.md) 继续创建助手。

View File

@@ -4,99 +4,221 @@
## 概述
本指南将帮助你快速创建一个能够进行语音对话的智能助手。你可以选择通过控制台或 API 两种方式创建
本指南将帮助你通过控制台快速创建一个能够进行语音对话的智能助手。在创建助手之前需要先在资源库Library中配置所需的模型资源
## 前提条件
- 已部署 AI Video Assistant 服务
- 已配置至少一个 LLM 模型
- 已配置至少一个 TTS 语音
- 已部署 Realtime Agent Studio (RAS) 服务
- 拥有 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 助手。接下来可以:

View File

@@ -1,7 +1,7 @@
site_name: "AI Video Assistant"
site_description: "AI 视频助手 - 智能对话与工作流管理平台"
site_name: "实时交互智能体工作平台 (RAS)"
site_description: "实时交互智能体工作平台 (Realtime Agent Studio) - 智能对话与工作流管理平台"
copyright: "2025"
site_author: "AI Video Assistant Team"
site_author: "RAS Team"
docs_dir: "content"
site_dir: "site"
@@ -10,8 +10,7 @@ nav:
- 首页: index.md
- 快速开始:
- 概览: quickstart/index.md
- 通过控制台: quickstart/dashboard.md
- 通过 API: quickstart/api.md
- 资源库配置: quickstart/dashboard.md
- 安装部署:
- 概览: getting-started/index.md
- 环境要求: getting-started/requirements.md
@@ -81,6 +80,11 @@ markdown_extensions:
- pymdownx.snippets
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- tables
- attr_list
- md_in_html