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

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.

Browse Source
This commit is contained in:
Xin Wang
2026-03-01 22:38:50 +08:00
parent 6a46ec69f4
commit 2418df80e5
33 changed files with 3664 additions and 693 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/content/features/autotest.md → docs/content/analysis/autotest.md
View File

0
docs/content/features/dashboard.md → docs/content/analysis/dashboard.md
View File

166
docs/content/analysis/evaluation.md Normal file
View File

@@ -0,0 +1,166 @@
# 效果评估
效果评估帮助你系统地衡量和改进助手的对话质量。
## 评估维度
### 核心指标
| 指标 | 说明 | 计算方式 |
|------|------|---------|
| **解决率** | 用户问题被成功解决的比例 | 已解决 / 总对话数 |
| **准确率** | 回复内容正确的比例 | 正确回复 / 总回复数 |
| **满意度** | 用户满意的对话比例 | 满意评价 / 总评价数 |
| **转人工率** | 需要人工介入的比例 | 转人工数 / 总对话数 |
### 性能指标
| 指标 | 说明 | 建议值 |
|------|------|--------|
| **首次响应时间** | 用户输入到首次回复的时间 | < 2s |
| **平均对话轮次** | 解决问题需要的平均轮数 | < 5 轮 |
| **平均对话时长** | 单次对话的平均时长 | 视场景而定 |
## 配置评估标准
在助手配置中设置评估标准：
### 解决标准
定义什么情况视为"问题已解决"：
```
评估标准：solved_inquiry
描述：用户的问题得到了满意的解答
成功条件：
- 用户明确表示问题已解决
- 用户表示感谢并结束对话
- 用户获得了所需信息
失败条件：
- 用户要求转人工
- 用户多次重复相同问题
- 用户表达不满
```
### 质量标准
定义回复质量的评估维度：
```
评估维度：
1. 准确性 - 信息是否正确
2. 完整性 - 是否回答了用户所有问题
3. 相关性 - 回复是否切题
4. 简洁性 - 是否避免了冗余信息
5. 语气 - 是否保持了友好专业的态度
```
## 数据收集
### 自动收集
系统自动收集以下数据：
- 对话内容和时间戳
- 工具调用记录
- 错误和异常
- 转人工事件
### 用户反馈
配置用户反馈收集：
1. 对话结束后显示满意度评价
2. 收集用户评分（1-5 分）
3. 可选的文字反馈
### 数据提取
配置需要从对话中提取的信息：
```
数据提取项：
1. user_intent
描述：用户的主要意图
类型：string
2. issue_category
描述：问题分类
类型：enum [产品问题, 订单问题, 技术问题, 其他]
3. resolution_status
描述：解决状态
类型：enum [已解决, 未解决, 转人工]
```
## 评估报告
### 查看报告
在 **数据分析** > **效果评估** 页面查看：
1. **总体概览** - 核心指标趋势图
2. **分类分析** - 按问题类型的评估结果
3. **时段分析** - 不同时间段的表现
4. **详细记录** - 单条对话的评估结果
### 报告示例
```
评估报告 - 2025年1月
总对话数：1,234
解决率：78.5%
准确率：85.2%
平均满意度：4.2/5
转人工率：12.3%
问题分类分布：
- 产品问题：45%
- 订单问题：30%
- 技术问题：15%
- 其他：10%
改进建议：
1. 订单问题解决率较低（65%），建议补充订单相关知识库
2. 技术问题转人工率高（25%），建议增加技术支持工具
```
## 持续改进
### 改进流程
1. **收集数据** - 持续收集对话和评估数据
2. **分析问题** - 找出低分对话的共性
3. **制定方案** - 针对问题制定改进措施
4. **实施改进** - 更新提示词、知识库或工具
5. **验证效果** - 观察改进后的指标变化
### 常见改进措施
| 问题 | 改进措施 |
|------|---------|
| 回复不准确 | 优化提示词，补充知识库 |
| 无法理解问题 | 增加示例，优化 ASR 热词 |
| 回复太长 | 在提示词中限制长度 |
| 缺少专业知识 | 上传相关文档到知识库 |
| 工具调用失败 | 检查工具配置和 API 状态 |
### A/B 测试
对比不同配置的效果：
1. 创建助手的变体版本
2. 按比例分配流量
3. 收集两个版本的评估数据
4. 比较各项指标
5. 选择效果更好的版本
## 下一步
- [自动化测试](autotest.md) - 批量测试助手
- [历史记录](history.md) - 查看对话详情
- [提示词指南](../assistants/prompts.md) - 优化提示词

0
docs/content/features/history.md → docs/content/analysis/history.md
View File

299
docs/content/api-reference.md
View File

@@ -1,299 +0,0 @@
# API 参考
本节提供 AI Video Assistant 的 API 接口文档，包括 WebSocket 实时通信协议和后端 REST API。
---
## WebSocket 实时通信
WebSocket 端点提供双向实时语音对话能力，支持音频流输入输出和文本消息交互。
### 连接地址
```
ws://<host>/ws?assistant_id=<assistant_id>
```
- `assistant_id` 为必填 query 参数，用于从数据库加载该助手的运行时配置。
### 传输规则
- **文本帧**：JSON 格式控制消息
- **二进制帧**：PCM 音频数据（`pcm_s16le`, 16kHz, 单声道）
- 帧长度必须是 640 字节的整数倍（20ms 音频 = 640 bytes）
---
### 消息流程
```
Client -> session.start
Server <- session.started
Server <- config.resolved
Client -> (binary pcm frames...)
Server <- input.speech_started / transcript.delta / transcript.final
Server <- assistant.response.delta / assistant.response.final
Server <- output.audio.start
Server <- (binary pcm frames...)
Server <- output.audio.end
Client -> session.stop
Server <- session.stopped
```
---
### 客户端 -> 服务端消息
#### 1. Session Start: `session.start`
客户端连接后发送的第一个消息，用于启动对话会话。
```json
{
"type": "session.start",
"audio": {
"encoding": "pcm_s16le",
"sample_rate_hz": 16000,
"channels": 1
},
"metadata": {
"channel": "web",
"source": "web_debug",
"history": {
"userId": 1
},
"overrides": {
"systemPrompt": "你是简洁助手",
"greeting": "你好，我能帮你什么？",
"output": {
"mode": "audio"
}
},
"dynamicVariables": {
"customer_name": "Alice",
"plan_tier": "Pro"
}
}
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"session.start"` |
| `audio` | object | 否 | 音频格式描述 |
| `audio.encoding` | string | 否 | 固定为 `"pcm_s16le"` |
| `audio.sample_rate_hz` | number | 否 | 固定为 `16000` |
| `audio.channels` | number | 否 | 固定为 `1` |
| `metadata` | object | 否 | 运行时配置 |
**metadata 支持的字段**：
- `channel` - 渠道标识
- `source` - 来源标识
- `history.userId` - 历史记录用户 ID
- `overrides` - 可覆盖字段（仅限安全白名单）
- `dynamicVariables` - 动态变量（支持 `{{variable}}` 占位符）
**`metadata.overrides` 白名单字段**：
- `systemPrompt`
- `greeting`
- `firstTurnMode`
- `generatedOpenerEnabled`
- `output`
- `bargeIn`
- `knowledgeBaseId`
- `knowledge`
- `tools`
- `openerAudio`
**限制**：
- `metadata.workflow` 会被忽略（不触发 workflow 事件）
- 禁止提交 `metadata.services`
- 禁止提交 `assistantId` / `appId` / `app_id` / `configVersionId` / `config_version_id`
- 禁止提交包含密钥语义的字段（如 `apiKey` / `token` / `secret` / `password` / `authorization`）
---
#### 2. Text Input: `input.text`
发送文本输入，跳过 ASR 识别，直接触发 LLM 回复。
```json
{
"type": "input.text",
"text": "你能做什么？"
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"input.text"` |
| `text` | string | 是 | 用户文本内容 |
---
#### 3. Response Cancel: `response.cancel`
请求中断当前回答。
```json
{
"type": "response.cancel",
"graceful": false
}
```
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `type` | string | 是 | - | 固定为 `"response.cancel"` |
| `graceful` | boolean | 否 | `false` | `false` 立即打断 |
---
#### 4. Tool Call Results: `tool_call.results`
回传客户端执行的工具结果。
```json
{
"type": "tool_call.results",
"results": [
{
"tool_call_id": "call_abc123",
"name": "weather",
"output": { "temp_c": 21, "condition": "sunny" },
"status": { "code": 200, "message": "ok" }
}
]
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"tool_call.results"` |
| `results` | array | 否 | 工具结果列表 |
| `results[].tool_call_id` | string | 是 | 工具调用 ID |
| `results[].name` | string | 是 | 工具名称 |
| `results[].output` | any | 否 | 工具输出 |
| `results[].status` | object | 是 | 执行状态 |
---
#### 5. Session Stop: `session.stop`
结束对话会话。
```json
{
"type": "session.stop",
"reason": "client_disconnect"
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"session.stop"` |
| `reason` | string | 否 | 结束原因 |
---
#### 6. Binary Audio
在 `session.started` 之后可持续发送二进制 PCM 音频。
- **格式**：`pcm_s16le`
- **采样率**：16000 Hz
- **声道**：1（单声道）
- **帧长**：20ms = 640 bytes
---
### 服务端 -> 客户端事件
#### 事件包络
所有 JSON 事件都包含统一包络字段：
```json
{
"type": "event.name",
"timestamp": 1730000000000,
"sessionId": "sess_xxx",
"seq": 42,
"source": "asr",
"trackId": "audio_in",
"data": {}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | string | 事件类型 |
| `timestamp` | number | 事件时间戳（毫秒） |
| `sessionId` | string | 会话 ID |
| `seq` | number | 递增序号 |
| `source` | string | 事件来源 (`asr`/`llm`/`tts`/`tool`) |
| `trackId` | string | 事件轨道 (`audio_in`/`audio_out`/`control`) |
| `data` | object | 业务数据 |
---
#### 会话控制类事件
| 事件 | 说明 |
|---|---|
| `session.started` | 会话启动成功 |
| `config.resolved` | 服务端最终配置快照 |
| `heartbeat` | 保活心跳（默认 50 秒间隔） |
| `session.stopped` | 会话结束确认 |
| `error` | 统一错误事件 |
---
#### ASR 识别事件
| 事件 | 字段 | 说明 |
|---|---|---|
| `input.speech_started` | `probability` | 检测到语音开始 |
| `input.speech_stopped` | `probability` | 检测到语音结束 |
| `transcript.delta` | `text` | ASR 增量识别文本 |
| `transcript.final` | `text` | ASR 最终识别文本 |
---
#### LLM/TTS 输出事件
| 事件 | 字段 | 说明 |
|---|---|---|
| `assistant.response.delta` | `text` | 助手增量文本输出 |
| `assistant.response.final` | `text` | 助手完整文本输出 |
| `assistant.tool_call` | `tool_call_id`, `tool_name`, `arguments` | 工具调用通知 |
| `assistant.tool_result` | `tool_call_id`, `ok`, `result` | 工具执行结果 |
| `output.audio.start` | - | TTS 音频开始 |
| `output.audio.end` | - | TTS 音频结束 |
| `response.interrupted` | - | 回答被打断 |
| `metrics.ttfb` | `latencyMs` | 首包音频时延 |
---
### 错误码
| 错误码 | 说明 |
|---|---|
| `protocol.invalid_json` | JSON 格式错误 |
| `protocol.invalid_message` | 消息格式错误 |
| `protocol.order` | 消息顺序错误 |
| `protocol.assistant_id_required` | 缺少 `assistant_id` query 参数 |
| `protocol.invalid_override` | metadata 覆盖字段不合法 |
| `assistant.not_found` | assistant 不存在 |
| `assistant.config_unavailable` | assistant 配置不可用 |
| `audio.invalid_pcm` | PCM 数据无效 |
| `audio.frame_size_mismatch` | 音频帧大小不匹配 |
| `server.internal` | 服务端内部错误 |
---
### 心跳与超时
- **心跳间隔**：默认 50 秒（`heartbeat_interval_sec`）
- **空闲超时**：默认 60 秒（`inactivity_timeout_sec`）
- 客户端应持续发送音频或轻量消息避免被判定闲置

88
docs/content/api-reference/errors.md Normal file
View File

@@ -0,0 +1,88 @@
# 错误码
本文档列出 AI Video Assistant API 的所有错误码及其说明。
## 协议错误
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| `protocol.invalid_json` | JSON 格式错误 | 检查发送的 JSON 是否合法 |
| `protocol.invalid_message` | 消息格式错误 | 检查消息结构是否符合协议 |
| `protocol.order` | 消息顺序错误 | 确保先发送 `session.start` |
| `protocol.assistant_id_required` | 缺少 `assistant_id` query 参数 | 在连接 URL 中添加 `assistant_id` 参数 |
| `protocol.invalid_override` | metadata 覆盖字段不合法 | 检查 overrides 字段是否在白名单内 |
## 助手错误
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| `assistant.not_found` | 助手不存在 | 检查 `assistant_id` 是否正确 |
| `assistant.config_unavailable` | 助手配置不可用 | 确认助手已正确配置并发布 |
## 音频错误
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| `audio.invalid_pcm` | PCM 数据无效 | 检查音频格式是否为 `pcm_s16le` |
| `audio.frame_size_mismatch` | 音频帧大小不匹配 | 确保帧长度是 640 字节的整数倍 |
## 服务器错误
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| `server.internal` | 服务端内部错误 | 查看服务端日志排查问题 |
## 错误响应格式
所有错误都通过 `error` 事件返回：
```json
{
"type": "error",
"timestamp": 1730000000000,
"sessionId": "sess_xxx",
"data": {
"code": "protocol.invalid_json",
"message": "Invalid JSON format",
"details": {}
}
}
```
## HTTP API 错误
REST API 使用标准 HTTP 状态码：
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（缺少或无效的认证信息） |
| 403 | 禁止访问（权限不足） |
| 404 | 资源不存在 |
| 422 | 请求实体无法处理 |
| 500 | 服务器内部错误 |
### HTTP 错误响应示例
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"field": "name",
"reason": "required"
}
}
}
```
## 错误处理最佳实践
1. **始终检查错误响应** - 不要假设请求一定成功
2. **实现重试机制** - 对于临时性错误（如网络问题）实现指数退避重试
3. **记录错误日志** - 保存错误详情用于问题排查
4. **友好的用户提示** - 将技术错误转换为用户可理解的提示

196
docs/content/api-reference/index.md Normal file
View File

@@ -0,0 +1,196 @@
# API 参考
本节提供 AI Video Assistant 的完整 API 文档。
## API 概览
AI Video Assistant 提供两种类型的 API：
| API 类型 | 用途 | 协议 |
|---------|------|------|
| **REST API** | 管理助手、模型、知识库等资源 | HTTP |
| **WebSocket API** | 实时语音对话 | WebSocket |
## REST API
### 基础地址
```
http://localhost:8080/api/v1
```
### 认证
REST API 使用 Bearer Token 认证：
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
http://localhost:8080/api/v1/assistants
```
### 通用响应格式
**成功响应**
```json
{
"success": true,
"data": { ... }
}
```
**列表响应**
```json
{
"success": true,
"data": {
"items": [...],
"total": 100,
"page": 1,
"page_size": 20
}
}
```
**错误响应**
```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "错误描述"
}
}
```
### 主要端点
#### 助手管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /assistants | 获取助手列表 |
| POST | /assistants | 创建助手 |
| GET | /assistants/{id} | 获取助手详情 |
| PATCH | /assistants/{id} | 更新助手 |
| DELETE | /assistants/{id} | 删除助手 |
#### 模型管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /llm | 获取 LLM 模型列表 |
| POST | /llm | 添加 LLM 模型 |
| GET | /asr | 获取 ASR 模型列表 |
| POST | /asr | 添加 ASR 模型 |
| GET | /voices | 获取语音列表 |
| POST | /voices | 添加语音配置 |
#### 知识库管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /knowledge-bases | 获取知识库列表 |
| POST | /knowledge-bases | 创建知识库 |
| POST | /knowledge-bases/{id}/documents | 上传文档 |
| DELETE | /knowledge-bases/{id}/documents/{doc_id} | 删除文档 |
#### 历史记录
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /history | 获取对话历史 |
| GET | /history/{id} | 获取对话详情 |
| GET | /history/stats | 获取统计数据 |
## WebSocket API
### 连接地址
```
ws://localhost:8000/ws?assistant_id=<assistant_id>
```
### 协议概述
WebSocket API 使用双向消息通信：
- **文本帧**：JSON 格式的控制消息
- **二进制帧**：PCM 音频数据
### 详细文档
- [WebSocket 协议](websocket.md) - 完整的消息格式和流程
- [错误码](errors.md) - 错误码列表和处理方式
## SDK
### JavaScript SDK
```bash
npm install @ai-video-assistant/sdk
```
```javascript
import { AIVideoAssistant } from '@ai-video-assistant/sdk';
const assistant = new AIVideoAssistant({
apiUrl: 'http://localhost:8080',
wsUrl: 'ws://localhost:8000'
});
// 创建助手
const result = await assistant.create({
name: '客服助手',
prompt: '你是一个友好的客服助手'
});
// 开始对话
const conversation = await assistant.connect(result.id);
conversation.on('response', (text) => {
console.log('助手回复:', text);
});
```
### Python SDK
```bash
pip install ai-video-assistant
```
```python
from ai_video_assistant import AIVideoAssistant
client = AIVideoAssistant(
api_url="http://localhost:8080",
ws_url="ws://localhost:8000"
)
# 创建助手
assistant = client.assistants.create(
name="客服助手",
prompt="你是一个友好的客服助手"
)
# 开始对话
async with client.connect(assistant.id) as conv:
response = await conv.send_text("你好")
print(f"助手回复: {response}")
```
## 速率限制
| 端点类型 | 限制 |
|---------|------|
| REST API | 100 请求/分钟 |
| WebSocket | 10 并发连接/用户 |
超出限制会返回 `429 Too Many Requests`。
## 下一步
- [WebSocket 协议](websocket.md) - 实时对话协议详解
- [错误码](errors.md) - 错误处理参考
- [快速开始](../quickstart/api.md) - API 使用示例

853
docs/content/api-reference/websocket.md Normal file
View File

@@ -0,0 +1,853 @@
# WebSocket 协议
WebSocket 端点提供双向实时语音对话能力，支持音频流输入输出和文本消息交互。
## 连接地址
```
ws://<host>/ws?assistant_id=<assistant_id>
```
- `assistant_id` 为必填 query 参数，用于从数据库加载该助手的运行时配置。
## 传输规则
- **文本帧**：JSON 格式控制消息
- **二进制帧**：PCM 音频数据（`pcm_s16le`, 16kHz, 单声道）
- 帧长度必须是 640 字节的整数倍（20ms 音频 = 640 bytes）
---
## 消息流程
```
Client -> session.start
Server <- session.started
Server <- config.resolved
Client -> (binary pcm frames...)
Server <- input.speech_started / transcript.delta / transcript.final
Server <- assistant.response.delta / assistant.response.final
Server <- output.audio.start
Server <- (binary pcm frames...)
Server <- output.audio.end
Client -> session.stop
Server <- session.stopped
```
---
## 客户端 -> 服务端消息
### 1. Session Start: `session.start`
客户端连接后发送的第一个消息，用于启动对话会话。
```json
{
"type": "session.start",
"audio": {
"encoding": "pcm_s16le",
"sample_rate_hz": 16000,
"channels": 1
},
"metadata": {
"channel": "web",
"source": "web_debug",
"history": {
"userId": 1
},
"overrides": {
"systemPrompt": "你是简洁助手",
"greeting": "你好，我能帮你什么？",
"output": {
"mode": "audio"
}
},
"dynamicVariables": {
"customer_name": "Alice",
"plan_tier": "Pro"
}
}
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"session.start"` |
| `audio` | object | 否 | 音频格式描述 |
| `audio.encoding` | string | 否 | 固定为 `"pcm_s16le"` |
| `audio.sample_rate_hz` | number | 否 | 固定为 `16000` |
| `audio.channels` | number | 否 | 固定为 `1` |
| `metadata` | object | 否 | 运行时配置 |
**metadata 支持的字段**：
- `channel` - 渠道标识
- `source` - 来源标识
- `history.userId` - 历史记录用户 ID
- `overrides` - 可覆盖字段（仅限安全白名单）
- `dynamicVariables` - 动态变量（支持 `{{variable}}` 占位符）
**`metadata.overrides` 白名单字段**：
- `systemPrompt`
- `greeting`
- `firstTurnMode`
- `generatedOpenerEnabled`
- `output`
- `bargeIn`
- `knowledgeBaseId`
- `knowledge`
- `tools`
- `openerAudio`
**限制**：
- `metadata.workflow` 会被忽略（不触发 workflow 事件）
- 禁止提交 `metadata.services`
- 禁止提交 `assistantId` / `appId` / `app_id` / `configVersionId` / `config_version_id`
- 禁止提交包含密钥语义的字段（如 `apiKey` / `token` / `secret` / `password` / `authorization`）
---
### 2. Text Input: `input.text`
发送文本输入，跳过 ASR 识别，直接触发 LLM 回复。
```json
{
"type": "input.text",
"text": "你能做什么？"
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"input.text"` |
| `text` | string | 是 | 用户文本内容 |
---
### 3. Response Cancel: `response.cancel`
请求中断当前回答。
```json
{
"type": "response.cancel",
"graceful": false
}
```
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `type` | string | 是 | - | 固定为 `"response.cancel"` |
| `graceful` | boolean | 否 | `false` | `false` 立即打断 |
---
### 4. Tool Call Results: `tool_call.results`
回传客户端执行的工具结果。
```json
{
"type": "tool_call.results",
"results": [
{
"tool_call_id": "call_abc123",
"name": "weather",
"output": { "temp_c": 21, "condition": "sunny" },
"status": { "code": 200, "message": "ok" }
}
]
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"tool_call.results"` |
| `results` | array | 否 | 工具结果列表 |
| `results[].tool_call_id` | string | 是 | 工具调用 ID |
| `results[].name` | string | 是 | 工具名称 |
| `results[].output` | any | 否 | 工具输出 |
| `results[].status` | object | 是 | 执行状态 |
| `results[].status.code` | number | 是 | HTTP 状态码（200-299 表示成功） |
| `results[].status.message` | string | 是 | 状态描述 |
---
### 5. Session Stop: `session.stop`
结束对话会话。
```json
{
"type": "session.stop",
"reason": "client_disconnect"
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 固定为 `"session.stop"` |
| `reason` | string | 否 | 结束原因 |
---
### 6. Binary Audio
在 `session.started` 之后可持续发送二进制 PCM 音频。
- **格式**：`pcm_s16le`
- **采样率**：16000 Hz
- **声道**：1（单声道）
- **帧长**：20ms = 640 bytes
---
## 服务端 -> 客户端事件
### 事件包络
所有 JSON 事件都包含统一包络字段：
```json
{
"type": "event.name",
"timestamp": 1730000000000,
"sessionId": "sess_xxx",
"seq": 42,
"source": "asr",
"trackId": "audio_in",
"data": {}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | string | 事件类型 |
| `timestamp` | number | 事件时间戳（Unix 毫秒） |
| `sessionId` | string | 会话 ID |
| `seq` | number | 递增序号（用于重放/恢复） |
| `source` | string | 事件来源：`asr` / `llm` / `tts` / `tool` / `system` / `client` / `server` |
| `trackId` | string | 事件轨道：`audio_in` / `audio_out` / `control` |
| `data` | object | 业务数据（可选） |
**轨道 ID 说明**：
| trackId | 说明 | 相关事件 |
|---------|------|---------|
| `audio_in` | ASR/VAD 输入侧事件 | `input.*`, `transcript.*` |
| `audio_out` | 助手输出侧事件 | `assistant.*`, `output.audio.*`, `response.interrupted`, `metrics.ttfb` |
| `control` | 会话控制事件 | `session.*`, `error`, `config.resolved`, `heartbeat` |
---
### 会话控制类事件
#### `session.started`
会话启动成功，客户端收到此事件后可以开始发送音频。
```json
{
"type": "session.started",
"timestamp": 1730000000000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 1,
"trackId": "control",
"tracks": {
"audio_in": "audio_in",
"audio_out": "audio_out",
"control": "control"
},
"audio": {
"encoding": "pcm_s16le",
"sample_rate_hz": 16000,
"channels": 1
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `sessionId` | string | 会话唯一标识符 |
| `trackId` | string | 固定为 `"control"` |
| `tracks` | object | 可用轨道列表 |
| `tracks.audio_in` | string | 输入轨道 ID |
| `tracks.audio_out` | string | 输出轨道 ID |
| `tracks.control` | string | 控制轨道 ID |
| `audio` | object | 音频格式配置 |
| `audio.encoding` | string | 编码格式 |
| `audio.sample_rate_hz` | number | 采样率 |
| `audio.channels` | number | 声道数 |
---
#### `config.resolved`
服务端最终配置快照，在 `session.started` 后立即发送。
```json
{
"type": "config.resolved",
"timestamp": 1730000000001,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 2,
"trackId": "control",
"config": {
"assistantId": "asst_abc123",
"configVersionId": "ver_xyz789",
"output": {
"mode": "audio"
},
"services": {
"llm": {
"provider": "openai",
"model": "gpt-4"
},
"asr": {
"provider": "sensevoice",
"model": "paraformer"
},
"tts": {
"provider": "aliyun",
"model": "xiaoyun",
"enabled": true
}
},
"tools": ["weather", "calculator"]
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"control"` |
| `config` | object | 已解析的运行时配置 |
| `config.assistantId` | string | 助手 ID |
| `config.configVersionId` | string | 配置版本 ID |
| `config.output` | object | 输出配置 |
| `config.output.mode` | string | 输出模式：`"audio"` / `"text"` |
| `config.services` | object | 服务配置（不包含密钥） |
| `config.tools` | array | 可用工具列表 |
---
#### `heartbeat`
保活心跳事件，默认每 50 秒发送一次。
```json
{
"type": "heartbeat",
"timestamp": 1730000050000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 10
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `timestamp` | number | 心跳时间戳 |
---
#### `session.stopped`
会话结束确认。
```json
{
"type": "session.stopped",
"timestamp": 1730000100000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 50,
"reason": "client_requested"
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `reason` | string | 结束原因：`"client_requested"` / `"timeout"` / `"error"` |
---
### ASR 识别事件
#### `input.speech_started`
检测到语音开始（VAD）。
```json
{
"type": "input.speech_started",
"timestamp": 1730000010000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 5,
"source": "asr",
"trackId": "audio_in",
"probability": 0.95
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_in"` |
| `probability` | number | 语音检测置信度（0-1） |
---
#### `input.speech_stopped`
检测到语音结束（VAD）。
```json
{
"type": "input.speech_stopped",
"timestamp": 1730000012000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 8,
"source": "asr",
"trackId": "audio_in",
"probability": 0.92
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_in"` |
| `probability` | number | 静音检测置信度（0-1） |
---
#### `transcript.delta`
ASR 增量识别文本（实时转写）。
```json
{
"type": "transcript.delta",
"timestamp": 1730000011000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 6,
"source": "asr",
"trackId": "audio_in",
"text": "你好",
"data": {
"text": "你好",
"turn_id": "turn_001",
"utterance_id": "utt_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_in"` |
| `text` | string | 增量识别文本 |
| `data.text` | string | 增量识别文本（同 `text`） |
| `data.turn_id` | string | 当前对话轮次 ID |
| `data.utterance_id` | string | 当前语句 ID |
**节流说明**：服务端默认每 300ms 合并一次 delta 事件。
---
#### `transcript.final`
ASR 最终识别文本（语句结束）。
```json
{
"type": "transcript.final",
"timestamp": 1730000012500,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 9,
"source": "asr",
"trackId": "audio_in",
"text": "你好，请问今天天气怎么样",
"data": {
"text": "你好，请问今天天气怎么样",
"turn_id": "turn_001",
"utterance_id": "utt_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_in"` |
| `text` | string | 最终识别文本 |
| `data.text` | string | 最终识别文本（同 `text`） |
| `data.turn_id` | string | 当前对话轮次 ID |
| `data.utterance_id` | string | 当前语句 ID |
---
### LLM/TTS 输出事件
#### `assistant.response.delta`
助手增量文本输出（流式生成）。
```json
{
"type": "assistant.response.delta",
"timestamp": 1730000013000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 12,
"source": "llm",
"trackId": "audio_out",
"text": "今天天气",
"data": {
"text": "今天天气",
"turn_id": "turn_001",
"response_id": "resp_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `source` | string | 固定为 `"llm"` |
| `text` | string | 增量文本内容 |
| `data.text` | string | 增量文本内容（同 `text`） |
| `data.turn_id` | string | 当前对话轮次 ID |
| `data.response_id` | string | 当前回复 ID |
**节流说明**：服务端默认每 80ms 合并一次 delta 事件。
---
#### `assistant.response.final`
助手完整文本输出（回复结束）。
```json
{
"type": "assistant.response.final",
"timestamp": 1730000015000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 18,
"source": "llm",
"trackId": "audio_out",
"text": "今天天气晴朗，气温25度，适合外出。",
"data": {
"text": "今天天气晴朗，气温25度，适合外出。",
"turn_id": "turn_001",
"response_id": "resp_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `source` | string | 固定为 `"llm"` |
| `text` | string | 完整回复文本 |
| `data.text` | string | 完整回复文本（同 `text`） |
| `data.turn_id` | string | 当前对话轮次 ID |
| `data.response_id` | string | 当前回复 ID |
---
#### `assistant.tool_call`
工具调用通知，通知客户端 LLM 请求调用工具。
```json
{
"type": "assistant.tool_call",
"timestamp": 1730000014000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 14,
"source": "llm",
"trackId": "audio_out",
"tool_call_id": "call_abc123",
"tool_name": "weather",
"arguments": {
"city": "北京"
},
"executor": "server",
"timeout_ms": 30000,
"data": {
"tool_call": {
"id": "call_abc123",
"name": "weather",
"arguments": "{\"city\":\"北京\"}"
},
"turn_id": "turn_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `source` | string | 固定为 `"llm"` |
| `tool_call_id` | string | 工具调用唯一 ID |
| `tool_name` | string | 工具名称 |
| `arguments` | object | 工具参数（已解析的 JSON） |
| `executor` | string | 执行方：`"server"` 服务端执行 / `"client"` 客户端执行 |
| `timeout_ms` | number | 超时时间（毫秒） |
| `data.tool_call` | object | 原始工具调用信息 |
| `data.tool_call.id` | string | 工具调用 ID |
| `data.tool_call.name` | string | 工具名称 |
| `data.tool_call.arguments` | string | 工具参数（JSON 字符串） |
| `data.turn_id` | string | 当前对话轮次 ID |
**注意**：当 `executor = "client"` 时，客户端需要执行工具并返回 `tool_call.results`。
---
#### `assistant.tool_result`
工具执行结果通知。
```json
{
"type": "assistant.tool_result",
"timestamp": 1730000014500,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 15,
"source": "server",
"trackId": "audio_out",
"tool_call_id": "call_abc123",
"tool_name": "weather",
"tool_display_name": "天气查询",
"ok": true,
"error": null,
"result": {
"tool_call_id": "call_abc123",
"name": "weather",
"output": {
"temperature": 25,
"condition": "晴",
"humidity": 40
},
"status": {
"code": 200,
"message": "ok"
}
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `source` | string | 执行方：`"server"` / `"client"` |
| `tool_call_id` | string | 工具调用 ID |
| `tool_name` | string | 工具名称 |
| `tool_display_name` | string | 工具显示名称 |
| `ok` | boolean | 执行是否成功（状态码 200-299 为 true） |
| `error` | object \| null | 错误信息（`ok=false` 时存在） |
| `error.code` | number | 错误状态码 |
| `error.message` | string | 错误描述 |
| `error.retryable` | boolean | 是否可重试 |
| `result` | object | 原始执行结果 |
| `result.output` | any | 工具返回数据 |
| `result.status` | object | 执行状态 |
| `result.status.code` | number | HTTP 状态码 |
| `result.status.message` | string | 状态描述 |
---
#### `output.audio.start`
TTS 音频播放开始标记。
```json
{
"type": "output.audio.start",
"timestamp": 1730000015500,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 19,
"source": "tts",
"trackId": "audio_out",
"data": {
"tts_id": "tts_001",
"turn_id": "turn_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `source` | string | 固定为 `"tts"` |
| `data.tts_id` | string | TTS 播放段 ID |
| `data.turn_id` | string | 当前对话轮次 ID |
**说明**：此事件后服务端将发送二进制 PCM 音频帧。
---
#### `output.audio.end`
TTS 音频播放结束标记。
```json
{
"type": "output.audio.end",
"timestamp": 1730000018000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 25,
"source": "tts",
"trackId": "audio_out",
"data": {
"tts_id": "tts_001",
"turn_id": "turn_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `source` | string | 固定为 `"tts"` |
| `data.tts_id` | string | TTS 播放段 ID |
| `data.turn_id` | string | 当前对话轮次 ID |
---
#### `response.interrupted`
回答被打断（用户插话）。
```json
{
"type": "response.interrupted",
"timestamp": 1730000016000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 20,
"source": "system",
"trackId": "audio_out",
"data": {
"turn_id": "turn_001",
"response_id": "resp_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `data.turn_id` | string | 被打断的对话轮次 ID |
| `data.response_id` | string | 被打断的回复 ID |
---
#### `metrics.ttfb`
首包音频时延指标（Time To First Byte）。
```json
{
"type": "metrics.ttfb",
"timestamp": 1730000015600,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 21,
"source": "system",
"trackId": "audio_out",
"latencyMs": 1520,
"data": {
"latencyMs": 1520,
"turn_id": "turn_001"
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `trackId` | string | 固定为 `"audio_out"` |
| `latencyMs` | number | 首包音频时延（毫秒） |
| `data.latencyMs` | number | 首包音频时延（同 `latencyMs`） |
| `data.turn_id` | string | 当前对话轮次 ID |
**说明**：从用户输入结束到第一个音频包发送的时间。
---
### 错误事件
#### `error`
统一错误事件。
```json
{
"type": "error",
"timestamp": 1730000020000,
"sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
"seq": 30,
"sender": "server",
"code": "llm.timeout",
"message": "LLM request timeout",
"stage": "llm",
"retryable": true,
"trackId": "audio_out",
"data": {
"error": {
"stage": "llm",
"code": "llm.timeout",
"message": "LLM request timeout",
"retryable": true
}
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `sender` | string | 错误来源：`"server"` / `"client"` |
| `code` | string | 错误码 |
| `message` | string | 错误描述 |
| `stage` | string | 错误阶段：`"protocol"` / `"asr"` / `"llm"` / `"tts"` / `"tool"` / `"audio"` |
| `retryable` | boolean | 是否可重试 |
| `trackId` | string | 错误关联的轨道 |
| `data.error` | object | 结构化错误信息 |
| `data.error.stage` | string | 错误阶段 |
| `data.error.code` | string | 错误码 |
| `data.error.message` | string | 错误描述 |
| `data.error.retryable` | boolean | 是否可重试 |
**trackId 约定**：
- `audio_in`：ASR/音频输入相关错误
- `audio_out`：LLM/TTS/工具相关错误
- `control`：协议/会话控制相关错误
---
## 关联 ID 说明
事件中的关联 ID 用于追踪对话流程：
| ID 类型 | 说明 | 生命周期 |
|---------|------|---------|
| `turn_id` | 对话轮次 ID | 一次用户-助手交互 |
| `utterance_id` | 语句 ID | 一次 ASR 最终识别结果 |
| `response_id` | 回复 ID | 一次助手回复生成 |
| `tool_call_id` | 工具调用 ID | 一次工具调用 |
| `tts_id` | TTS 播放段 ID | 一段语音合成播放 |
---
## 心跳与超时
- **心跳间隔**：默认 50 秒（`heartbeat_interval_sec`）
- **空闲超时**：默认 60 秒（`inactivity_timeout_sec`）
- 客户端应持续发送音频或轻量消息避免被判定闲置
## 事件节流
为保持客户端渲染和服务端负载稳定，v1 协议对部分事件进行节流：
| 事件 | 默认节流间隔 | 说明 |
|------|-------------|------|
| `transcript.delta` | 300ms | ASR 增量文本 |
| `assistant.response.delta` | 80ms | LLM 增量文本 |
## 错误处理
详细错误码请参考 [错误码](errors.md)。

113
docs/content/assistants/configuration.md Normal file
View File

@@ -0,0 +1,113 @@
# 配置选项
助手配置界面包含多个标签页，每个标签页负责不同方面的配置。
## 全局设置
全局设置定义助手的核心对话能力。
| 配置项 | 说明 | 建议值 |
|-------|------|--------|
| 助手名称 | 用于标识和管理 | 简洁明确 |
| 系统提示词 | 定义角色、任务和约束 | 详见[提示词指南](prompts.md) |
| 开场白 | 对话开始时的问候语 | 简短友好 |
| 温度参数 | 控制回复随机性 | 0.7（通用）/ 0.3（严谨） |
| 上下文长度 | 保留的历史消息数 | 10-20 |
### 高级选项
- **首轮模式** - 设置首次对话的触发方式
- **打断检测** - 用户打断时的处理策略
- **超时设置** - 无响应时的处理
## 语音配置
配置语音识别和语音合成参数。
### TTS 语音合成
| 配置 | 说明 |
|------|------|
| TTS 引擎 | 选择语音合成服务（阿里/火山/Minimax） |
| 音色 | 选择语音风格和性别 |
| 语速 | 语音播放速度（0.5-2.0） |
| 音量 | 语音输出音量（0-100） |
| 音调 | 语音音调高低（0.5-2.0） |
### ASR 语音识别
| 配置 | 说明 |
|------|------|
| ASR 引擎 | 选择语音识别服务 |
| 语言 | 识别语言（中文/英文/多语言） |
| 热词 | 提高特定词汇识别准确率 |
## 工具绑定
配置助手可调用的外部工具。
### 可用工具类型
| 工具 | 说明 |
|------|------|
| 搜索工具 | 网络搜索获取信息 |
| 天气查询 | 查询天气预报 |
| 计算器 | 数学计算 |
| 知识库检索 | RAG 知识检索 |
| 自定义工具 | HTTP 回调外部 API |
### 配置步骤
1. 在工具列表中勾选需要的工具
2. 配置工具参数（如有）
3. 测试工具调用是否正常
## 知识关联
关联 RAG 知识库，让助手能够回答专业领域问题。
### 配置参数
| 参数 | 说明 | 建议值 |
|------|------|--------|
| 知识库 | 选择要关联的知识库 | - |
| 相似度阈值 | 低于此分数不返回 | 0.7 |
| 返回数量 | 单次检索返回条数 | 3 |
| 检索策略 | 混合/向量/关键词 | 混合 |
### 多知识库
支持关联多个知识库，系统会自动合并检索结果。
## 外部链接
配置第三方服务集成和 Webhook 回调。
### Webhook 配置
| 字段 | 说明 |
|------|------|
| 回调 URL | 接收事件的 HTTP 端点 |
| 事件类型 | 订阅的事件（对话开始/结束/工具调用等） |
| 认证方式 | API Key / Bearer Token / 无 |
### 支持的事件
- `conversation.started` - 对话开始
- `conversation.ended` - 对话结束
- `tool.called` - 工具被调用
- `human.transfer` - 转人工
## 配置导入导出
### 导出配置
1. 在助手详情页点击 **更多**
2. 选择 **导出配置**
3. 下载 JSON 格式的配置文件
### 导入配置
1. 点击 **新建助手**
2. 选择 **从配置导入**
3. 上传配置文件

57
docs/content/assistants/index.md Normal file
View File

@@ -0,0 +1,57 @@
# 助手管理
助手是 AI Video Assistant 的核心模块，用于创建和配置智能对话机器人。每个助手都可以独立配置提示词、语音、知识库和工具。
## 概述
![助手管理](../images/assistants.png)
## 助手能力
| 能力 | 说明 |
|------|------|
| **智能对话** | 基于 LLM 的自然语言理解和生成 |
| **语音交互** | 支持语音识别和语音合成 |
| **知识检索** | 关联知识库回答专业问题 |
| **工具调用** | 调用外部 API 执行操作 |
| **工作流** | 支持复杂的多轮对话流程 |
## 创建助手
### 步骤
1. 进入 **助手管理** 页面
2. 点击 **新建助手** 按钮
3. 填写基本信息
4. 配置各项参数
5. 保存并发布
### 基本信息
| 配置项 | 说明 |
|-------|------|
| 助手名称 | 唯一标识，用于区分不同助手 |
| 提示词 | 定义助手的角色和行为 |
| 温度参数 | 控制回复的随机性（0-1） |
## 调试助手
在助手详情页可进行实时调试：
- **文本对话测试** - 快速验证回复质量
- **语音输入测试** - 测试 ASR 识别效果
- **工具调用验证** - 确认工具正常执行
## 发布助手
配置完成后：
1. 点击 **保存** - 保存当前配置
2. 点击 **发布** - 发布到生产环境
3. 获取 API 调用地址 - 用于集成
## 下一步
- [配置选项](configuration.md) - 详细的配置标签页说明
- [提示词指南](prompts.md) - 如何编写高质量的系统提示词
- [测试调试](testing.md) - 助手测试与问题排查

184
docs/content/assistants/prompts.md Normal file
View File

@@ -0,0 +1,184 @@
# 提示词指南
系统提示词（System Prompt）是定义助手行为的核心配置。本指南介绍如何编写高质量的提示词。
## 提示词结构
一个完整的系统提示词通常包含以下部分：
```
[角色定义]
[任务描述]
[行为约束]
[输出格式]
[示例（可选）]
```
## 编写原则
### 1. 明确角色
告诉助手它是谁：
```
你是一个专业的技术支持工程师，专门负责解答产品使用问题。
```
### 2. 定义任务
明确助手需要完成什么：
```
你的主要任务是：
1. 解答用户关于产品功能的问题
2. 提供使用指导和最佳实践
3. 帮助用户排查常见故障
```
### 3. 设置约束
限制不希望出现的行为：
```
请注意：
- 不要讨论与产品无关的话题
- 不要编造不存在的功能
- 如果不确定答案，请建议用户联系人工客服
```
### 4. 指定风格
定义回复的语气和风格：
```
回复风格要求：
- 使用友好、专业的语气
- 回答简洁明了，避免冗长
- 适当使用列表和步骤说明
```
## 提示词模板
### 客服助手
```
你是 [公司名称] 的智能客服助手。
## 你的职责
- 解答用户关于产品和服务的问题
- 处理常见的投诉和建议
- 引导用户完成操作流程
## 回复要求
- 保持友好和耐心
- 回答简洁，一般不超过 3 句话
- 如果问题复杂，建议转接人工客服
## 禁止行为
- 不要讨论竞争对手
- 不要承诺无法兑现的事项
- 不要透露内部信息
```
### 技术支持
```
你是一个技术支持工程师，专门帮助用户解决技术问题。
## 工作流程
1. 首先了解用户遇到的具体问题
2. 询问必要的环境信息（系统版本、错误信息等）
3. 提供分步骤的解决方案
4. 确认问题是否解决
## 回复格式
- 使用编号列表说明操作步骤
- 提供代码示例时使用代码块
- 复杂问题可以分多次回复
```
### 销售顾问
```
你是一个产品销售顾问，帮助用户了解产品并做出购买决策。
## 沟通策略
- 先了解用户需求，再推荐合适的产品
- 突出产品优势，但不贬低竞品
- 提供真实的价格和优惠信息
## 目标
- 帮助用户找到最适合的方案
- 解答购买相关的疑问
- 促进成交但不过度推销
```
## 动态变量
提示词支持动态变量，使用 `{{变量名}}` 语法：
```
你好 {{customer_name}}，欢迎来到 {{company_name}}。
你当前的会员等级是 {{membership_tier}}。
```
在 `session.start` 时通过 `dynamicVariables` 传入：
```json
{
"type": "session.start",
"metadata": {
"dynamicVariables": {
"customer_name": "张三",
"company_name": "AI 公司",
"membership_tier": "黄金会员"
}
}
}
```
## 常见问题
### 回复太长
在提示词中明确限制：
```
回复长度要求：
- 一般问题：1-2 句话
- 复杂问题：不超过 5 句话
- 避免重复和冗余内容
```
### 答非所问
增加任务边界说明：
```
重要提示：
- 只回答与 [产品/服务] 相关的问题
- 对于无关问题，礼貌地拒绝并引导回正题
```
### 编造信息
强调诚实原则：
```
信息准确性要求：
- 只提供你确定的信息
- 不确定时说"我不太确定，建议您..."
- 绝对不要编造数据或功能
```
## 最佳实践
1. **迭代优化** - 根据实际对话效果持续调整
2. **测试覆盖** - 用各种场景测试提示词效果
3. **版本管理** - 保存历史版本，便于回退
4. **定期复盘** - 分析对话记录，发现改进点
## 下一步
- [测试调试](testing.md) - 验证提示词效果
- [知识库配置](../customization/knowledge-base.md) - 补充专业知识

162
docs/content/assistants/testing.md Normal file
View File

@@ -0,0 +1,162 @@
# 测试调试
本指南介绍如何测试和调试 AI 助手，确保其行为符合预期。
## 测试面板
在助手详情页，点击 **测试** 按钮打开测试面板。
### 功能介绍
| 功能 | 说明 |
|------|------|
| 文本对话 | 直接输入文字进行测试 |
| 语音测试 | 使用麦克风进行语音对话 |
| 查看日志 | 实时查看系统日志 |
| 事件追踪 | 查看 WebSocket 事件流 |
## 测试用例设计
### 基础功能测试
| 测试项 | 输入 | 预期结果 |
|--------|------|---------|
| 问候响应 | "你好" | 友好的问候回复 |
| 功能介绍 | "你能做什么？" | 准确描述能力范围 |
| 开场白 | 连接后自动 | 播放配置的开场白 |
### 业务场景测试
根据助手定位设计测试用例：
```
场景：产品咨询助手
测试用例 1：常见问题
- 输入："产品有哪些功能？"
- 预期：准确列出主要功能
测试用例 2：价格询问
- 输入："多少钱？"
- 预期：提供价格信息或引导方式
测试用例 3：超出范围
- 输入："帮我写一首诗"
- 预期：礼貌拒绝并引导回业务话题
```
### 边界测试
| 测试项 | 输入 | 预期结果 |
|--------|------|---------|
| 空输入 | "" | 提示用户输入内容 |
| 超长输入 | 1000+ 字符 | 正常处理或提示过长 |
| 特殊字符 | "<script>alert(1)</script>" | 安全处理，不执行 |
| 敏感内容 | 不当言论 | 拒绝回复并提示 |
## 日志分析
### 查看日志
在测试面板的 **日志** 标签页，可以看到：
- ASR 识别结果
- LLM 推理过程
- TTS 合成状态
- 工具调用记录
### 常见日志
```
[ASR] transcript.final: "你好，请问有什么可以帮你"
[LLM] request: messages=[...]
[LLM] response: "您好！我是..."
[TTS] synthesizing: "您好！我是..."
[TTS] audio.start
[TTS] audio.end
```
## 事件追踪
在 **事件** 标签页查看完整的 WebSocket 事件流：
```json
{"type": "session.started", "timestamp": 1704067200000}
{"type": "input.speech_started", "timestamp": 1704067201000}
{"type": "transcript.delta", "data": {"text": "你"}}
{"type": "transcript.delta", "data": {"text": "好"}}
{"type": "transcript.final", "data": {"text": "你好"}}
{"type": "assistant.response.delta", "data": {"text": "您"}}
{"type": "assistant.response.final", "data": {"text": "您好！..."}}
{"type": "output.audio.start"}
{"type": "output.audio.end"}
```
## 性能指标
关注以下性能指标：
| 指标 | 说明 | 建议值 |
|------|------|--------|
| TTFB | 首字节时间 | < 500ms |
| 识别延迟 | ASR 处理时间 | < 1s |
| 回复延迟 | LLM 推理时间 | < 2s |
| 合成延迟 | TTS 处理时间 | < 500ms |
## 常见问题排查
### 助手不响应
1. **检查连接状态**
- 确认 WebSocket 连接成功
- 查看是否收到 `session.started` 事件
2. **检查模型配置**
- 确认 LLM 模型 API Key 有效
- 测试模型连接是否正常
3. **查看错误日志**
- 打开浏览器开发者工具
- 检查 Console 和 Network 标签
### 回复质量差
1. **优化提示词**
- 增加更明确的指令
- 添加示例和约束
2. **调整温度参数**
- 降低 temperature 提高一致性
- 适当值通常在 0.3-0.7
3. **补充知识库**
- 上传相关文档
- 提高检索相关性
### 语音问题
1. **ASR 识别不准**
- 检查麦克风权限
- 尝试更换 ASR 引擎
- 添加热词提高识别率
2. **TTS 不播放**
- 检查浏览器自动播放限制
- 确认 TTS 配置正确
## 自动化测试
使用自动化测试功能进行批量测试：
1. 进入 **自动化测试** 页面
2. 创建测试任务
3. 配置测试用例
4. 运行测试并查看报告
详见 [自动化测试](../analysis/autotest.md)。
## 下一步
- [自动化测试](../analysis/autotest.md) - 批量测试
- [历史记录](../analysis/history.md) - 查看对话记录
- [效果评估](../analysis/evaluation.md) - 评估对话质量

0
docs/content/features/knowledge.md → docs/content/customization/knowledge-base.md
View File

0
docs/content/features/models.md → docs/content/customization/models.md
View File

229
docs/content/customization/tools.md Normal file
View File

@@ -0,0 +1,229 @@
# 工具集成
工具（Tools）让助手能够执行外部操作，如查询天气、搜索信息、调用 API 等。
## 概述
工具是助手能力的扩展。当用户的请求需要外部数据或操作时，助手会调用相应的工具。
## 内置工具
| 工具 | 说明 | 参数 |
|------|------|------|
| `search` | 网络搜索 | query: 搜索关键词 |
| `weather` | 天气查询 | city: 城市名称 |
| `calculator` | 数学计算 | expression: 计算表达式 |
| `knowledge` | 知识库检索 | query: 查询内容 |
### 启用内置工具
在助手配置的 **工具** 标签页：
1. 勾选需要启用的工具
2. 配置工具参数（如有）
3. 保存配置
## 自定义工具
支持通过 HTTP 回调实现自定义工具。
### 定义工具
```json
{
"name": "query_order",
"description": "查询用户订单信息",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单编号"
}
},
"required": ["order_id"]
},
"endpoint": {
"url": "https://api.example.com/orders",
"method": "GET",
"headers": {
"Authorization": "Bearer {{api_key}}"
}
}
}
```
### 工具字段说明
| 字段 | 说明 |
|------|------|
| name | 工具名称（英文标识符） |
| description | 工具描述（LLM 用于理解工具用途） |
| parameters | 参数定义（JSON Schema 格式） |
| endpoint | HTTP 调用配置 |
### 参数映射
工具参数自动映射到 HTTP 请求：
- **GET 请求**：参数作为 query string
- **POST 请求**：参数作为 JSON body
## 客户端工具
某些工具需要在客户端执行（如获取地理位置）。
### 工作流程
1. 助手返回 `assistant.tool_call` 事件
2. 客户端执行工具并获取结果
3. 客户端发送 `tool_call.results` 消息
4. 助手继续生成回复
### 服务端事件
```json
{
"type": "assistant.tool_call",
"data": {
"tool_call_id": "call_abc123",
"tool_name": "get_location",
"arguments": {}
}
}
```
### 客户端响应
```json
{
"type": "tool_call.results",
"results": [
{
"tool_call_id": "call_abc123",
"name": "get_location",
"output": {
"latitude": 39.9042,
"longitude": 116.4074,
"city": "北京"
},
"status": {
"code": 200,
"message": "ok"
}
}
]
}
```
## 工具调用示例
### 天气查询
用户："北京今天天气怎么样？"
助手调用工具：
```json
{
"tool_name": "weather",
"arguments": {
"city": "北京"
}
}
```
工具返回：
```json
{
"temperature": 25,
"condition": "晴",
"humidity": 40
}
```
助手回复："北京今天天气晴朗，气温 25 度，湿度 40%。"
### 订单查询
用户："帮我查一下订单 12345"
助手调用工具：
```json
{
"tool_name": "query_order",
"arguments": {
"order_id": "12345"
}
}
```
工具返回：
```json
{
"order_id": "12345",
"status": "已发货",
"tracking": "SF1234567890"
}
```
助手回复："您的订单 12345 已发货，快递单号是 SF1234567890。"
## 工具配置最佳实践
### 1. 清晰的描述
工具描述应该让 LLM 准确理解何时使用：
```
好的描述：
"查询指定城市的实时天气信息，包括温度、天气状况和湿度"
不好的描述：
"天气工具"
```
### 2. 完整的参数定义
```json
{
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称，如 '北京'、'上海'"
},
"date": {
"type": "string",
"description": "日期，格式 YYYY-MM-DD，可选，默认今天"
}
},
"required": ["city"]
}
}
```
### 3. 错误处理
工具应返回清晰的错误信息：
```json
{
"status": {
"code": 404,
"message": "未找到该城市的天气数据"
}
}
```
## 安全注意事项
1. **验证输入** - 不要直接信任用户输入
2. **限制权限** - 工具只应有必要的权限
3. **审计日志** - 记录所有工具调用
4. **速率限制** - 防止滥用
## 下一步
- [知识库配置](knowledge-base.md) - 让助手具备专业知识
- [工作流编排](workflows.md) - 复杂对话流程

0
docs/content/features/voices.md → docs/content/customization/voices.md
View File

0
docs/content/features/workflows.md → docs/content/customization/workflows.md
View File

95
docs/content/deployment.md
View File

@@ -1,95 +0,0 @@
# 部署指南
## 方式一：Docker 部署（推荐）
### 1. 构建镜像
```bash
docker build -t ai-video-assistant-web ./web
```
### 2. 运行容器
```bash
docker run -d \
--name ai-assistant-web \
-p 3000:80 \
ai-video-assistant-web
```
### 3. 使用 Docker Compose
```yaml
version: '3.8'
services:
web:
build: ./web
ports:
- "3000:80"
environment:
- VITE_API_URL=http://api:8080
```
运行：
```bash
docker-compose up -d
```
## 方式二：Nginx 部署
### 1. 构建前端
```bash
cd web
npm run build
```
### 2. 配置 Nginx
```nginx
server {
listen 80;
server_name your-domain.com;
root /var/www/ai-assistant/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
### 3. 启动 Nginx
```bash
sudo nginx -t
sudo systemctl reload nginx
```
## 环境变量配置
| 变量 | 说明 | 默认值 |
|------|------|--------|
| VITE_API_URL | 后端 API 地址 | http://localhost:8080 |
| VITE_GEMINI_API_KEY | Gemini API Key | - |
## 验证部署
1. 访问 http://your-domain.com
2. 检查页面是否正常加载
3. 验证各功能模块是否可用
## 故障排查
| 问题 | 解决方案 |
|------|---------|
| 页面空白 | 检查浏览器控制台错误 |
| API 请求失败 | 确认 VITE_API_URL 配置正确 |
| 静态资源 404 | 检查 nginx try_files 配置 |

161
docs/content/deployment/docker.md Normal file
View File

@@ -0,0 +1,161 @@
# Docker 部署
Docker 是推荐的部署方式，可以快速启动服务并确保环境一致性。
## 前提条件
- Docker 20.10+
- Docker Compose 2.0+（可选）
## 构建镜像
### Web 前端
```bash
docker build -t ai-video-assistant-web ./web
```
### API 服务
```bash
docker build -t ai-video-assistant-api ./api
```
### Engine 服务
```bash
docker build -t ai-video-assistant-engine ./engine
```
## 运行容器
### 单独运行
```bash
# Web 前端
docker run -d \
--name ai-assistant-web \
-p 3000:80 \
ai-video-assistant-web
# API 服务
docker run -d \
--name ai-assistant-api \
-p 8080:8080 \
ai-video-assistant-api
# Engine 服务
docker run -d \
--name ai-assistant-engine \
-p 8000:8000 \
ai-video-assistant-engine
```
## Docker Compose
推荐使用 Docker Compose 管理多个服务：
```yaml
version: '3.8'
services:
web:
build: ./web
ports:
- "3000:80"
environment:
- VITE_API_URL=http://api:8080
depends_on:
- api
api:
build: ./api
ports:
- "8080:8080"
environment:
- DATABASE_URL=postgresql://postgres:password@db:5432/ai_assistant
depends_on:
- db
engine:
build: ./engine
ports:
- "8000:8000"
environment:
- BACKEND_URL=http://api:8080
db:
image: postgres:15
environment:
- POSTGRES_DB=ai_assistant
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:
```
### 启动服务
```bash
# 启动所有服务
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
```
## 镜像优化
### 多阶段构建
Web 前端 Dockerfile 示例：
```dockerfile
# 构建阶段
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# 运行阶段
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
## 健康检查
```yaml
services:
api:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
```
## 常见问题
### 容器启动失败
```bash
# 查看容器日志
docker logs ai-assistant-web
# 进入容器调试
docker exec -it ai-assistant-web sh
```
### 端口冲突
修改 `docker-compose.yml` 中的端口映射，例如 `3001:80`。

42
docs/content/deployment/index.md Normal file
View File

@@ -0,0 +1,42 @@
# 部署指南
本章节介绍如何将 AI Video Assistant 部署到生产环境。
## 部署方式
| 方式 | 适用场景 | 复杂度 |
|------|---------|--------|
| [Docker 部署](docker.md) | 快速部署、容器化环境 | 简单 |
| [生产环境](production.md) | Nginx 反向代理、高可用 | 中等 |
## 快速开始
### Docker 一键部署
```bash
docker build -t ai-video-assistant-web ./web
docker run -d -p 3000:80 --name ai-assistant-web ai-video-assistant-web
```
### 验证部署
1. 访问 http://your-domain.com
2. 检查页面是否正常加载
3. 验证各功能模块是否可用
## 环境变量配置
| 变量 | 说明 | 默认值 |
|------|------|--------|
| VITE_API_URL | 后端 API 地址 | http://localhost:8080 |
| VITE_GEMINI_API_KEY | Gemini API Key | - |
## 故障排查
| 问题 | 解决方案 |
|------|---------|
| 页面空白 | 检查浏览器控制台错误 |
| API 请求失败 | 确认 VITE_API_URL 配置正确 |
| 静态资源 404 | 检查 nginx try_files 配置 |
更多问题请参考 [故障排查](../resources/troubleshooting.md)。

191
docs/content/deployment/production.md Normal file
View File

@@ -0,0 +1,191 @@
# 生产环境部署
本文档介绍如何将 AI Video Assistant 部署到生产环境，包括 Nginx 配置、SSL 证书、性能优化等。
## Nginx 部署
### 1. 构建前端
```bash
cd web
npm run build
```
### 2. 部署静态文件
```bash
sudo mkdir -p /var/www/ai-assistant
sudo cp -r dist/* /var/www/ai-assistant/
```
### 3. 配置 Nginx
创建 `/etc/nginx/sites-available/ai-assistant`：
```nginx
server {
listen 80;
server_name your-domain.com;
root /var/www/ai-assistant;
index index.html;
# Gzip 压缩
gzip on;
gzip_types text/plain text/css application/json application/javascript;
# 静态文件缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
# SPA 路由支持
location / {
try_files $uri $uri/ /index.html;
}
# API 反向代理
location /api {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# WebSocket 代理
location /ws {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 86400;
}
}
```
### 4. 启用站点
```bash
sudo ln -s /etc/nginx/sites-available/ai-assistant /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
## SSL 证书配置
### 使用 Let's Encrypt
```bash
# 安装 certbot
sudo apt install certbot python3-certbot-nginx
# 申请证书
sudo certbot --nginx -d your-domain.com
# 自动续期
sudo certbot renew --dry-run
```
### HTTPS 配置
```nginx
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
# SSL 安全配置
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
# HSTS
add_header Strict-Transport-Security "max-age=31536000" always;
# ... 其他配置同上
}
# HTTP 重定向到 HTTPS
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
```
## 性能优化
### Nginx 优化
```nginx
# 在 http 块中添加
worker_processes auto;
worker_connections 1024;
# 开启 sendfile
sendfile on;
tcp_nopush on;
tcp_nodelay on;
# 缓冲区设置
client_body_buffer_size 10K;
client_header_buffer_size 1k;
client_max_body_size 8m;
```
### 静态资源 CDN
如果使用 CDN，修改构建配置：
```env
# .env.production
VITE_CDN_URL=https://cdn.your-domain.com
```
## 监控与日志
### 访问日志
```nginx
access_log /var/log/nginx/ai-assistant.access.log;
error_log /var/log/nginx/ai-assistant.error.log;
```
### 日志轮转
```bash
# /etc/logrotate.d/nginx
/var/log/nginx/*.log {
daily
rotate 14
compress
delaycompress
missingok
notifempty
}
```
## 备份策略
### 数据库备份
```bash
# PostgreSQL 备份
pg_dump -U postgres ai_assistant > backup_$(date +%Y%m%d).sql
# 定时备份（crontab）
0 2 * * * pg_dump -U postgres ai_assistant > /backups/backup_$(date +\%Y\%m\%d).sql
```
## 高可用部署
对于高可用需求，建议：
1. **负载均衡** - 使用 Nginx upstream 或云负载均衡
2. **数据库主从** - PostgreSQL 主从复制
3. **Redis 集群** - 会话和缓存高可用
4. **健康检查** - 定期检测服务状态

65
docs/content/features/assistants.md
View File

@@ -1,65 +0,0 @@
# 助手管理
助手是 AI Video Assistant 的核心模块，用于创建和配置智能对话机器人。
## 创建助手
![助手管理](../images/assistants.png)
### 基本配置
1. 进入 **助手管理** 页面
2. 点击 **新建助手** 按钮
3. 填写基本信息：
| 配置项 | 说明 |
|-------|------|
| 助手名称 | 唯一标识，用于区分不同助手 |
| 提示词 | 定义助手的角色和行为 |
| 温度参数 | 控制回复的随机性（0-1） |
### 配置标签页
#### 全局设置
- 设置助手的核心对话能力
- 配置上下文长度
- 设置对话开场白
#### 语音配置
| 配置 | 说明 |
|------|------|
| TTS 引擎 | 选择语音合成服务（阿里/火山/Minimax） |
| 音色 | 选择语音风格和性别 |
| 语速 | 语音播放速度 |
| 音量 | 语音输出音量 |
#### 工具绑定
- 配置助手可调用的外部工具
- 启用/禁用特定功能模块
#### 知识关联
- 关联 RAG 知识库
- 配置检索参数（相似度阈值、返回数量）
#### 外部链接
- 配置第三方服务集成
- 设置 Webhook 回调
## 调试助手
在助手详情页可进行实时调试：
- 文本对话测试
- 语音输入测试
- 工具调用验证
## 发布助手
配置完成后：
1. 点击 **保存**
2. 点击 **发布**
3. 获取 API 调用地址

59
docs/content/getting-started.md
View File

@@ -1,59 +0,0 @@
# 快速开始
## 环境准备
### 前置条件
| 软件 | 版本要求 |
|------|---------|
| Node.js | 18.0 或更高 |
| npm/yarn/pnpm | 最新版本 |
| 现代浏览器 | Chrome 90+ / Firefox 90+ / Edge 90+ |
### 检查环境
```bash
node --version
npm --version
```
## 安装步骤
### 1. 克隆项目
```bash
git clone https://github.com/your-repo/AI-VideoAssistant.git
cd AI-VideoAssistant
```
### 2. 安装依赖
```bash
cd web
npm install
```
### 3. 配置环境变量
创建 `.env` 文件：
```env
VITE_API_URL=http://localhost:8080
VITE_GEMINI_API_KEY=your_api_key_here
```
### 4. 启动开发服务器
```bash
npm run dev
```
访问 http://localhost:3000
## 构建生产版本
```bash
npm run build
```
构建产物在 `dist` 目录。

83
docs/content/getting-started/configuration.md Normal file
View File

@@ -0,0 +1,83 @@
# 配置说明
## 环境变量
在项目根目录或 `web` 目录下创建 `.env` 文件：
```env
# API 服务地址
VITE_API_URL=http://localhost:8080
# Gemini API Key（可选）
VITE_GEMINI_API_KEY=your_api_key_here
```
## 变量说明
| 变量 | 必填 | 说明 | 默认值 |
|------|------|------|--------|
| `VITE_API_URL` | 是 | 后端 API 服务地址 | http://localhost:8080 |
| `VITE_GEMINI_API_KEY` | 否 | Google Gemini API 密钥 | - |
## 后端服务配置
后端服务使用独立的配置文件，位于 `api/config/` 目录：
### 数据库配置
```yaml
database:
host: localhost
port: 5432
name: ai_assistant
user: postgres
password: your_password
```
### Redis 配置
```yaml
redis:
host: localhost
port: 6379
db: 0
```
## Engine 服务配置
Engine 服务配置位于 `engine/config/` 目录：
### 助手默认配置
参考 `engine/config/agents/default.yaml`：
```yaml
agent:
name: "默认助手"
language: "zh-CN"
temperature: 0.7
max_tokens: 2048
```
## 多环境配置
### 开发环境
```env
# .env.development
VITE_API_URL=http://localhost:8080
```
### 生产环境
```env
# .env.production
VITE_API_URL=https://api.your-domain.com
```
## 配置优先级
1. 命令行参数
2. 环境变量
3. `.env` 文件
4. 默认值

55
docs/content/getting-started/index.md Normal file
View File

@@ -0,0 +1,55 @@
# 安装部署
本章节介绍如何安装和配置 AI Video Assistant 开发环境。
## 概述
AI Video Assistant 由以下组件构成：
| 组件 | 说明 |
|------|------|
| **Web 前端** | React + TypeScript 构建的管理界面 |
| **API 服务** | Python FastAPI 后端服务 |
| **Engine 服务** | 实时对话引擎（WebSocket） |
## 安装步骤
### 1. 克隆项目
```bash
git clone https://github.com/your-repo/AI-VideoAssistant.git
cd AI-VideoAssistant
```
### 2. 安装依赖
```bash
cd web
npm install
```
### 3. 配置环境变量
创建 `.env` 文件，详见 [配置说明](configuration.md)。
### 4. 启动开发服务器
```bash
npm run dev
```
访问 http://localhost:3000
## 构建生产版本
```bash
npm run build
```
构建产物在 `dist` 目录。
## 下一步
- [环境要求](requirements.md) - 详细的软件版本要求
- [配置说明](configuration.md) - 环境变量配置指南
- [部署指南](../deployment/index.md) - 生产环境部署

65
docs/content/getting-started/requirements.md Normal file
View File

@@ -0,0 +1,65 @@
# 环境要求
## 软件依赖
### 必需软件
| 软件 | 版本要求 | 说明 |
|------|---------|------|
| Node.js | 18.0 或更高 | JavaScript 运行时 |
| npm/yarn/pnpm | 最新版本 | 包管理器 |
| Python | 3.10+ | 后端服务运行环境 |
### 推荐浏览器
| 浏览器 | 版本要求 |
|--------|---------|
| Chrome | 90+ |
| Firefox | 90+ |
| Edge | 90+ |
| Safari | 14+ |
## 检查环境
运行以下命令检查已安装的软件版本：
```bash
# 检查 Node.js 版本
node --version
# 检查 npm 版本
npm --version
# 检查 Python 版本
python --version
```
## 硬件建议
### 开发环境
| 资源 | 建议配置 |
|------|---------|
| CPU | 4 核心以上 |
| 内存 | 8GB 以上 |
| 磁盘 | 20GB 可用空间 |
### 生产环境
| 资源 | 建议配置 |
|------|---------|
| CPU | 8 核心以上 |
| 内存 | 16GB 以上 |
| 磁盘 | 100GB SSD |
| 网络 | 100Mbps 以上 |
## 网络要求
以下域名需要可访问（用于 API 调用）：
| 服务 | 域名 |
|------|------|
| OpenAI | api.openai.com |
| DeepSeek | api.deepseek.com |
| 阿里云 TTS | nls-gateway.cn-shanghai.aliyuncs.com |
| 火山引擎 | openspeech.bytedance.com |

183
docs/content/index.md
View File

@@ -1,6 +1,4 @@
# AI Video Assistant 使用说明
## 产品概述
# AI Video Assistant
AI Video Assistant 是一款基于大语言模型的智能对话与工作流管理平台，支持多模型集成、语音合成、自动化测试等功能，帮助企业快速构建智能客服系统。
@@ -10,190 +8,51 @@ AI Video Assistant 是一款基于大语言模型的智能对话与工作流管
| 功能模块 | 描述 |
|---------|------|
| **仪表盘** | 实时数据统计与可视化分析 |
| **助手管理** | 创建、配置、测试 AI 助手 |
| **工作流** | 可视化流程编排 |
| **模型库** | LLM/ASR/语音模型配置 |
| **知识库** | RAG 文档知识管理 |
| **历史记录** | 对话日志查询与分析 |
| **自动化测试** | 批量测试与质量评估 |
| **仪表盘** | 实时数据统计与可视化分析 |
## 快速开始
## 快速导航
### 环境要求
<div class="grid cards" markdown>
- Node.js 18+
- 现代浏览器（Chrome/Firefox/Edge）
- :rocket: **[快速开始](quickstart/index.md)**
### 启动服务
5 分钟创建你的第一个 AI 助手
```bash
cd web
npm install
npm run dev
```
- :wrench: **[安装部署](getting-started/index.md)**
访问 `http://localhost:3000`
环境准备与安装配置
## 详细使用指南
- :robot: **[助手管理](assistants/index.md)**
### 1. 仪表盘
创建和配置智能对话助手
![仪表盘](images/dashboard.png)
- :gear: **[功能定制](customization/knowledge-base.md)**
仪表盘展示系统核心指标：
- **总对话数** - 累计对话请求数量
- **回答率** - 成功回答的对话占比
- **平均时长** - 单次对话平均持续时间
- **人工转接率** - 需要人工介入的对话比例
知识库、工具、语音、工作流
### 2. 助手管理
- :bar_chart: **[数据分析](analysis/dashboard.md)**
![助手管理](images/assistants.png)
仪表盘、历史记录、测试评估
#### 创建助手
- :book: **[API 参考](api-reference/index.md)**
1. 点击 **创建助手**
2. 配置助手基本信息（名称、提示词）
3. 选择对话语言与音色
4. 绑定知识库和工具
WebSocket 协议与接口文档
#### 配置选项
- :cloud: **[部署指南](deployment/index.md)**
| 标签页 | 配置项 |
|-------|--------|
| 全局 | 名称、提示词、温度参数 |
| 语音 | TTS 引擎、音色、语言 |
| 工具 | 可用工具列表 |
| 知识 | RAG 知识库关联 |
| 链接 | 外部服务配置 |
Docker、Nginx 生产部署
### 3. 工作流
- :question: **[常见问题](resources/faq.md)**
![工作流管理](images/workflows.png)
使用问题与故障排查
#### 工作流节点类型
| 节点 | 功能 |
|------|------|
| 对话节点 | AI 自动回复 |
| 工具节点 | 调用外部工具 |
| 人工节点 | 转接人工客服 |
| 结束节点 | 结束对话流程 |
### 4. 模型配置
![模型库](images/llms.png)
#### 支持的 LLM 模型
- **OpenAI** - GPT-4/GPT-3.5
- **DeepSeek** - DeepSeek Chat
- **SiliconFlow** - 多种开源模型
- **Google Gemini** - Gemini Pro
#### ASR 语音识别
- **Whisper** - OpenAI 语音识别
- **SenseVoice** - 高精度中文识别
### 5. 知识库
![知识库](images/knowledge.png)
#### 创建知识库
1. 进入 **知识库** 页面
2. 点击 **新建知识库**
3. 上传文档（支持 Markdown/PDF/TXT）
4. 配置检索参数
### 6. 历史记录
![历史记录](images/history.png)
查询条件：
- 按时间范围筛选
- 按助手名称搜索
- 查看对话详情与统计
### 7. 自动化测试
![自动化测试](images/autotest.png)
#### 测试类型
| 类型 | 说明 |
|------|------|
| 固定测试 | 预设问答对测试 |
| 智能测试 | AI 生成测试用例 |
#### 评估指标
- 回复准确率
- 回答完整度
- 响应时间
### 8. 语音合成
![语音合成](images/voices.png)
#### 支持的 TTS 引擎
- **阿里云** - 多音色可选
- **火山引擎** - 高自然度
- **Minimax** - 低延迟
### 9. 个人中心
![个人中心](images/profile.png)
管理账户信息与系统设置。
## 部署指南
### Docker 部署（推荐）
```bash
# 构建镜像
docker build -t ai-video-assistant .
# 运行容器
docker run -d -p 3000:3000 --name ai-assistant ai-video-assistant
```
### Nginx 反向代理
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
## 常见问题
### Q: 如何配置 API Key？
进入 **LLM 库** 或 **语音库** 页面，点击对应模型的配置按钮填写 API Key。
### Q: 助手无法回复？
1. 检查模型配置是否正确
2. 确认知识库已正确关联
3. 查看系统日志排查错误
### Q: 语音识别不准确？
- 确认 ASR 模型选择正确
- 检查音频采样率（推荐 16kHz）
- 确认语言设置匹配
</div>
## 技术支持

241
docs/content/quickstart/api.md Normal file
View 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
View File

@@ -0,0 +1,149 @@
# 通过控制台创建助手
本指南详细介绍如何通过 Web 控制台创建和配置 AI 助手。
## 步骤 1：登录控制台
1. 打开浏览器访问控制台地址（如 `http://localhost:3000`）
2. 使用账号密码登录
## 步骤 2：创建助手
![创建助手](../images/assistants.png)
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
View 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) - 正式上线

110
docs/content/resources/faq.md Normal file
View File

@@ -0,0 +1,110 @@
# 常见问题
## API Key 配置
### Q: 如何配置 API Key？
进入 **LLM 库** 或 **语音库** 页面，点击对应模型的配置按钮填写 API Key。
**步骤：**
1. 在左侧导航栏选择 **模型配置**
2. 选择 **LLM 库** 或 **语音库**
3. 点击已添加模型的 **编辑** 按钮
4. 在 API Key 字段填写你的密钥
5. 点击 **保存**
## 助手问题
### Q: 助手无法回复？
可能的原因和解决方案：
1. **检查模型配置是否正确**
- 确认 API Key 已正确填写
- 测试模型连接是否正常
2. **确认知识库已正确关联**
- 进入助手配置的 **知识** 标签页
- 检查是否已选择知识库
3. **查看系统日志排查错误**
- 打开浏览器开发者工具（F12）
- 检查 Console 和 Network 标签页
### Q: 助手回复内容不相关？
- 检查系统提示词是否清晰明确
- 调整 Temperature 参数（降低可提高准确性）
- 确认知识库内容与问题相关
- 增加知识库相似度阈值
## 语音识别
### Q: 语音识别不准确？
1. **确认 ASR 模型选择正确**
- 中文场景推荐使用 SenseVoice
- 英文场景推荐使用 Whisper
2. **检查音频采样率**
- 推荐采样率：16kHz
- 推荐格式：PCM 16-bit
3. **确认语言设置匹配**
- 在 ASR 配置中选择正确的语言
### Q: 语音延迟较高？
- 检查网络连接稳定性
- 尝试切换 ASR 服务提供商
- 降低音频质量以减少传输数据量
## 语音合成
### Q: TTS 声音不自然？
- 尝试不同的音色选项
- 调整语速参数（推荐 0.8-1.2）
- 选择与内容风格匹配的声音
### Q: TTS 无法播放？
1. 检查浏览器是否允许自动播放音频
2. 确认 TTS API Key 配置正确
3. 检查网络连接
## 知识库
### Q: 知识库检索无结果？
- 确认文档已成功上传
- 降低相似度阈值（默认 0.7）
- 增加返回结果数量
- 检查文档内容是否与查询相关
### Q: 文档上传失败？
- 检查文件大小是否超过 10MB
- 确认文件格式支持（MD/PDF/TXT）
- 尝试减小文档内容
## 部署问题
### Q: 页面空白或加载失败？
1. 检查浏览器控制台错误信息
2. 确认后端服务已启动
3. 检查 VITE_API_URL 环境变量配置
### Q: API 请求失败？
- 确认 VITE_API_URL 配置正确
- 检查后端服务是否运行
- 查看网络请求响应状态码
### Q: 静态资源 404？
- 检查 Nginx `try_files` 配置
- 确认构建产物路径正确
- 检查文件权限设置

292
docs/content/resources/troubleshooting.md Normal file
View File

@@ -0,0 +1,292 @@
# 故障排查
本文档汇总常见问题的排查步骤和解决方案。
## 连接问题
### WebSocket 连接失败
**症状**：无法建立 WebSocket 连接，控制台显示连接错误。
**排查步骤**：
1. **检查服务状态**
```bash
# 检查 Engine 服务是否运行
curl http://localhost:8000/health
```
2. **验证连接地址**
- 确认 host 和 port 正确
- 确认 assistant_id 参数存在
3. **检查网络**
- 确认防火墙未阻止 WebSocket
- 检查 Nginx 代理配置（如有）
4. **查看服务日志**
```bash
docker logs ai-assistant-engine
```
**常见原因**：
- Engine 服务未启动
- assistant_id 无效
- 防火墙阻止 WebSocket 端口
---
### API 请求失败
**症状**：REST API 返回错误或超时。
**排查步骤**：
1. **检查 API 服务**
```bash
curl http://localhost:8080/health
```
2. **验证请求格式**
- Content-Type 是否为 application/json
- 请求体是否为有效 JSON
3. **检查认证**
- Authorization header 是否正确
- API Key 是否有效
4. **查看响应详情**
```bash
curl -v http://localhost:8080/api/v1/assistants
```
---
## 助手问题
### 助手不回复
**症状**：发送消息后没有收到助手回复。
**排查步骤**：
1. **检查会话状态**
- 确认收到 `session.started` 事件
- 确认没有 `error` 事件
2. **检查 LLM 配置**
- API Key 是否有效
- 模型配置是否正确
- 测试模型连接
3. **查看日志**
- 检查 LLM 调用是否成功
- 查看是否有超时错误
**常见原因**：
- LLM API Key 无效或过期
- 模型服务不可用
- 请求超时
---
### 回复质量差
**症状**：助手回复不准确、不相关或格式混乱。
**排查步骤**：
1. **检查提示词**
- 是否有明确的角色定义
- 是否有清晰的任务描述
- 是否有必要的约束
2. **调整参数**
- 降低 temperature 提高一致性
- 调整 max_tokens 控制长度
3. **检查知识库**
- 确认知识库已关联
- 测试检索结果是否相关
4. **查看对话历史**
- 分析问题出现的模式
- 收集典型的失败案例
---
## 语音问题
### 语音识别不准确
**症状**：ASR 识别结果与实际说话内容不符。
**排查步骤**：
1. **检查音频质量**
- 麦克风是否正常工作
- 环境是否嘈杂
- 采样率是否正确（16kHz）
2. **验证 ASR 配置**
- 语言设置是否正确
- 是否配置了热词
3. **测试不同引擎**
- 尝试切换 ASR 服务提供商
- 对比识别效果
**改进建议**：
- 添加业务相关的热词
- 使用降噪麦克风
- 选择针对中文优化的 ASR 引擎
---
### 语音无法播放
**症状**：TTS 合成成功但没有声音输出。
**排查步骤**：
1. **检查浏览器设置**
- 是否允许自动播放音频
- 音量是否静音
2. **验证音频数据**
- 确认收到 `output.audio.start` 事件
- 确认收到二进制音频帧
- 确认收到 `output.audio.end` 事件
3. **检查音频解码**
- PCM 格式是否正确解析
- AudioContext 是否正确初始化
4. **测试 TTS 服务**
- 单独测试 TTS 配置
- 检查 TTS API 状态
---
## 部署问题
### Docker 容器启动失败
**症状**：容器无法启动或立即退出。
**排查步骤**：
1. **查看容器日志**
```bash
docker logs <container_name>
```
2. **检查资源限制**
```bash
docker stats
```
3. **验证配置文件**
- 环境变量是否正确
- 配置文件路径是否存在
4. **检查端口冲突**
```bash
netstat -an | grep <port>
```
---
### 页面加载空白
**症状**：浏览器打开页面但内容为空。
**排查步骤**：
1. **检查浏览器控制台**
- 打开 F12 开发者工具
- 查看 Console 错误信息
2. **验证静态资源**
- 检查 Network 标签页
- 确认 JS/CSS 文件加载成功
3. **检查 API 连接**
- 确认 VITE_API_URL 配置正确
- 测试 API 是否可访问
4. **清除缓存**
```bash
# 强制刷新
Ctrl + Shift + R
```
---
## 性能问题
### 响应延迟高
**症状**：从发送消息到收到回复时间过长。
**排查步骤**：
1. **定位延迟环节**
- ASR 处理时间
- LLM 推理时间
- TTS 合成时间
2. **查看性能指标**
- 检查 `metrics.ttfb` 事件
- 分析各环节耗时
3. **优化配置**
- 使用更快的模型
- 减少 max_tokens
- 启用流式输出
4. **检查网络**
- 测试到各 API 的延迟
- 考虑使用更近的服务区域
---
## 日志查看
### 服务端日志
```bash
# Docker 容器日志
docker logs -f ai-assistant-engine
# 查看最近 100 行
docker logs --tail 100 ai-assistant-engine
```
### 客户端日志
在浏览器开发者工具中：
1. **Console** - 查看 JavaScript 错误和日志
2. **Network** - 查看网络请求和响应
3. **WebSocket** - 查看 WS 消息（在 Network 标签页）
### 启用详细日志
设置环境变量启用调试日志：
```bash
# Engine 服务
LOG_LEVEL=debug
# API 服务
DEBUG=true
```
## 获取帮助
如果以上方法无法解决问题：
1. 收集相关日志和错误信息
2. 描述复现步骤
3. 提交 Issue 或联系技术支持