Revamp documentation structure in mkdocs.yml by reorganizing navigation for improved accessibility. Remove outdated content from previous sections and introduce new topics including detailed guides on assistant management, configuration options, and tool integrations. Enhance API reference documentation with comprehensive error codes and WebSocket protocol details. Add new sections for automated testing, data analysis, and knowledge base management, ensuring a cohesive and user-friendly documentation experience.
This commit is contained in:
Xin Wang
241
docs/content/quickstart/api.md
Normal file
241
docs/content/quickstart/api.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 通过 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)
|
||||
149
docs/content/quickstart/dashboard.md
Normal file
149
docs/content/quickstart/dashboard.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 通过控制台创建助手
|
||||
|
||||
本指南详细介绍如何通过 Web 控制台创建和配置 AI 助手。
|
||||
|
||||
## 步骤 1：登录控制台
|
||||
|
||||
1. 打开浏览器访问控制台地址（如 `http://localhost:3000`）
|
||||
2. 使用账号密码登录
|
||||
|
||||
## 步骤 2：创建助手
|
||||
|
||||
|
||||
|
||||
1. 在左侧导航栏点击 **助手管理**
|
||||
2. 点击右上角 **新建助手** 按钮
|
||||
3. 在弹出的对话框中输入：
|
||||
- **助手名称**：为你的助手起一个名字，如 "产品咨询助手"
|
||||
- **描述**：简单描述助手的用途（可选）
|
||||
|
||||
4. 点击 **创建**
|
||||
|
||||
## 步骤 3：配置基本设置
|
||||
|
||||
创建完成后，你将进入助手配置页面。
|
||||
|
||||
### 全局设置
|
||||
|
||||
| 配置项 | 建议值 | 说明 |
|
||||
|-------|--------|------|
|
||||
| 系统提示词 | 见下方示例 | 定义助手的角色和行为 |
|
||||
| 开场白 | "你好，我是产品咨询助手，请问有什么可以帮您？" | 对话开始时的问候 |
|
||||
| 温度 | 0.7 | 平衡创意和准确性 |
|
||||
|
||||
### 系统提示词示例
|
||||
|
||||
```
|
||||
你是一个专业的产品咨询助手。你的主要任务是：
|
||||
|
||||
1. 解答用户关于产品功能的问题
|
||||
2. 提供使用建议和最佳实践
|
||||
3. 帮助用户解决常见问题
|
||||
|
||||
请注意：
|
||||
- 保持友好和专业的语气
|
||||
- 回答简洁明了，避免冗长
|
||||
- 如果不确定答案，请如实告知并建议联系人工客服
|
||||
- 不要编造不存在的功能或信息
|
||||
```
|
||||
|
||||
## 步骤 4：配置语音
|
||||
|
||||
切换到 **语音配置** 标签页：
|
||||
|
||||
### TTS 设置
|
||||
|
||||
1. **选择 TTS 引擎**
|
||||
- 阿里云：多音色、高自然度
|
||||
- 火山引擎：低延迟
|
||||
- Minimax：高性价比
|
||||
|
||||
2. **选择音色**
|
||||
- 根据助手定位选择合适的声音
|
||||
- 建议先试听再确定
|
||||
|
||||
3. **调整参数**
|
||||
- 语速：1.0（正常速度）
|
||||
- 音量：80%
|
||||
- 音调：1.0
|
||||
|
||||
### ASR 设置
|
||||
|
||||
1. **选择 ASR 引擎**
|
||||
- Whisper：通用识别
|
||||
- SenseVoice：中文识别更准
|
||||
|
||||
2. **设置语言**
|
||||
- 选择 "中文" 或 "自动检测"
|
||||
|
||||
## 步骤 5：关联知识库（可选）
|
||||
|
||||
如果你已创建知识库，可以在 **知识** 标签页进行关联：
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
详细集成指南请参考 [API 参考](../api-reference/websocket.md)。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 助手不回复？
|
||||
|
||||
1. 检查 LLM 模型是否配置正确
|
||||
2. 查看浏览器控制台是否有错误
|
||||
3. 确认后端服务正常运行
|
||||
|
||||
### 语音无法播放？
|
||||
|
||||
1. 检查浏览器是否允许自动播放
|
||||
2. 确认 TTS 配置正确
|
||||
3. 检查音量设置
|
||||
|
||||
## 下一步
|
||||
|
||||
- [通过 API 创建助手](api.md)
|
||||
- [配置知识库](../customization/knowledge-base.md)
|
||||
- [添加工具](../customization/tools.md)
|
||||
126
docs/content/quickstart/index.md
Normal file
126
docs/content/quickstart/index.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# 快速开始
|
||||
|
||||
5 分钟创建你的第一个 AI 助手。
|
||||
|
||||
## 概述
|
||||
|
||||
本指南将帮助你快速创建一个能够进行语音对话的智能助手。你可以选择通过控制台或 API 两种方式创建。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- 已部署 AI Video Assistant 服务
|
||||
- 已配置至少一个 LLM 模型
|
||||
- 已配置至少一个 TTS 语音
|
||||
|
||||
## 选择创建方式
|
||||
|
||||
| 方式 | 适用场景 | 复杂度 |
|
||||
|------|---------|--------|
|
||||
| [通过控制台](dashboard.md) | 快速体验、可视化配置 | 简单 |
|
||||
| [通过 API](api.md) | 程序化创建、批量管理 | 中等 |
|
||||
|
||||
---
|
||||
|
||||
## 方式一：通过控制台创建
|
||||
|
||||
### 步骤 1：创建助手
|
||||
|
||||
1. 登录控制台，进入 **助手管理** 页面
|
||||
2. 点击 **新建助手**
|
||||
3. 输入助手名称，如 "客服助手"
|
||||
|
||||
### 步骤 2：配置提示词
|
||||
|
||||
在 **全局设置** 中配置系统提示词：
|
||||
|
||||
```
|
||||
你是一个友好的客服助手。你的任务是帮助用户解答问题。
|
||||
|
||||
要求：
|
||||
- 保持友好和专业的语气
|
||||
- 回答要简洁明了
|
||||
- 如果不确定答案，请如实告知
|
||||
```
|
||||
|
||||
### 步骤 3：配置语音
|
||||
|
||||
在 **语音配置** 中：
|
||||
|
||||
1. 选择 TTS 引擎
|
||||
2. 选择合适的音色
|
||||
3. 调整语速为 1.0
|
||||
|
||||
### 步骤 4：测试助手
|
||||
|
||||
1. 点击 **保存**
|
||||
2. 点击 **测试** 按钮
|
||||
3. 输入 "你好，你能做什么？"
|
||||
4. 验证回复是否符合预期
|
||||
|
||||
### 步骤 5：发布助手
|
||||
|
||||
1. 确认测试通过后，点击 **发布**
|
||||
2. 复制生成的 `assistant_id`
|
||||
|
||||
---
|
||||
|
||||
## 方式二：通过 API 创建
|
||||
|
||||
### 步骤 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：配置语音
|
||||
|
||||
```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：测试连接
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:8000/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
|
||||
}
|
||||
}));
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
console.log('收到消息:', event.data);
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
恭喜！你已成功创建了第一个 AI 助手。接下来可以：
|
||||
|
||||
- [配置知识库](../customization/knowledge-base.md) - 让助手回答专业问题
|
||||
- [添加工具](../customization/tools.md) - 扩展助手能力
|
||||
- [查看 API 文档](../api-reference/websocket.md) - 深入了解协议细节
|
||||
- [部署到生产环境](../deployment/index.md) - 正式上线
|
||||
Reference in New Issue
Block a user