530d95eea4
- Updated Dockerfile for the API to include build tools for C++11 required for native extensions. - Revised requirements.txt to upgrade several dependencies, including FastAPI and SQLAlchemy. - Expanded docker-compose.yml to add MinIO service for S3-compatible storage and improved health checks for backend and engine services. - Enhanced README.md in the Docker directory to provide detailed service descriptions and quick start instructions. - Updated mkdocs.yml to reflect new navigation structure and added deployment overview documentation. - Introduced new Dockerfiles for the engine and web services, including development configurations for hot reloading.
277 lines
8.6 KiB
Markdown
277 lines
8.6 KiB
Markdown
# 快速开始
|
||
|
||
5 分钟创建你的第一个 AI 助手。
|
||
|
||
## 概述
|
||
|
||
本指南将帮助你通过控制台快速创建一个能够进行语音对话的智能助手。在创建助手之前，需要先在资源库（Library）中配置所需的模型资源。
|
||
|
||
## 前提条件
|
||
|
||
- 已部署 Realtime Agent Studio (RAS) 服务
|
||
- 拥有 LLM / ASR / TTS 服务的 API Key
|
||
|
||
## 配置流程
|
||
|
||
创建助手前，需要先准备好三种核心资源：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 资源库配置 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 1. 语音识别 (ASR) ─→ 将用户语音转为文字 │
|
||
│ 2. 模型接入 (LLM) ─→ 理解用户意图并生成回复 │
|
||
│ 3. 声音资源 (TTS) ─→ 将文字回复转为语音输出 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 创建助手 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 配置提示词 → 选择模型 → 配置语音 → 测试 → 发布 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 第一步：配置资源库
|
||
|
||
在创建助手之前，需要先在资源库中添加 ASR、LLM、TTS 三种资源。
|
||
|
||
### 1.1 添加语音识别模型 (ASR)
|
||
|
||
语音识别模型负责将用户的语音输入转换为文字。
|
||
|
||
1. 在左侧导航栏点击 **语音识别**
|
||
2. 点击 **添加模型** 按钮
|
||
3. 填写配置信息：
|
||
|
||
| 配置项 | 说明 | 示例值 |
|
||
|-------|------|--------|
|
||
| 模型名称 | 自定义显示名称 | SenseVoice CN |
|
||
| 接口类型 | 选择 OpenAI Compatible | OpenAI Compatible |
|
||
| 语言 | 识别语言 | 中文 (Chinese) |
|
||
| Model Name | 模型标识符 | FunAudioLLM/SenseVoiceSmall |
|
||
| Base URL | API 服务地址 | https://api.siliconflow.cn/v1 |
|
||
| API Key | 服务密钥 | sk-xxxxxxxx |
|
||
|
||
4. 可选配置：
|
||
- **热词**：添加专有名词提高识别准确率
|
||
- **标点增强**：自动添加标点符号
|
||
- **文本归一化**：规范化数字、日期等格式
|
||
|
||
5. 点击 **确认添加**
|
||
|
||
!!! tip "试听识别功能"
|
||
添加完成后，可以点击列表中的试听按钮，上传或录制音频测试识别效果。
|
||
|
||
### 1.2 添加大语言模型 (LLM)
|
||
|
||
大语言模型是助手的"大脑"，负责理解用户意图并生成回复。
|
||
|
||
1. 在左侧导航栏点击 **模型接入**
|
||
2. 点击 **添加模型** 按钮
|
||
3. 填写配置信息：
|
||
|
||
| 配置项 | 说明 | 示例值 |
|
||
|-------|------|--------|
|
||
| 厂商 | 接口类型 | OpenAI Compatible |
|
||
| 模型类型 | 文本/嵌入/重排 | 文本 |
|
||
| 模型名称 | 自定义显示名称 | GPT-4o Mini |
|
||
| 模型标识 | API 中的 model 参数 | gpt-4o-mini |
|
||
| Base URL | API 服务地址 | https://api.openai.com/v1 |
|
||
| API Key | 服务密钥 | sk-xxxxxxxx |
|
||
| 温度 | 输出随机性 (0-2) | 0.7 |
|
||
| 上下文长度 | 最大 token 数 | 8192 |
|
||
|
||
4. 点击 **确认添加**
|
||
|
||
!!! tip "预览功能"
|
||
添加完成后，可以点击预览按钮测试模型是否配置正确。
|
||
|
||
### 1.3 添加声音资源 (TTS)
|
||
|
||
声音资源用于将助手的文字回复转换为语音输出。
|
||
|
||
1. 在左侧导航栏点击 **声音资源**
|
||
2. 点击 **添加声音** 按钮
|
||
3. 填写配置信息：
|
||
|
||
| 配置项 | 说明 | 示例值 |
|
||
|-------|------|--------|
|
||
| 厂商 | 接口类型 | OpenAI Compatible 或 DashScope |
|
||
| 声音名称 | 自定义显示名称 | 客服小美 |
|
||
| 模型 | TTS 模型标识 | FunAudioLLM/CosyVoice2-0.5B |
|
||
| 声音 ID | 音色标识 | FunAudioLLM/CosyVoice2-0.5B:anna |
|
||
| Base URL | API 服务地址 | https://api.siliconflow.cn/v1 |
|
||
| API Key | 服务密钥 | sk-xxxxxxxx |
|
||
| 语速 | 说话速度 (0.5-2.0) | 1.0 |
|
||
| 增益 | 音量调节 (-10 to 10 dB) | 0 |
|
||
| 音调 | 声音高低 (-12 to 12) | 0 |
|
||
| 性别 | 声音性别 | 女 |
|
||
| 语言 | 声音语言 | 中文 |
|
||
|
||
4. 点击 **确认添加**
|
||
|
||
!!! tip "试听功能"
|
||
添加完成后，可以在列表中点击播放按钮试听声音效果。
|
||
|
||
---
|
||
|
||
## 第二步：创建助手
|
||
|
||
资源配置完成后，可以开始创建助手。
|
||
|
||
### 2.1 新建助手
|
||
|
||
1. 在左侧导航栏点击 **助手管理**
|
||
2. 点击 **新建助手** 按钮
|
||
3. 系统会自动创建一个名为 "New Assistant" 的助手
|
||
|
||
### 2.2 配置全局设置
|
||
|
||
在助手详情页的 **全局** 标签页中配置：
|
||
|
||
#### 基本信息
|
||
|
||
- **助手名称**：修改为有意义的名称，如 "客服助手"
|
||
- **语言**：选择助手的对话语言
|
||
|
||
#### 系统提示词
|
||
|
||
配置系统提示词，定义助手的角色和行为：
|
||
|
||
```
|
||
你是一个友好的客服助手。你的任务是帮助用户解答问题。
|
||
|
||
要求：
|
||
- 保持友好和专业的语气
|
||
- 回答要简洁明了，每次回复控制在 2-3 句话
|
||
- 如果不确定答案，请如实告知
|
||
```
|
||
|
||
#### 开场白配置
|
||
|
||
设置对话开始时助手的问候语：
|
||
|
||
- **首回合模式**：选择 "助手先说" 让助手主动开场
|
||
- **开场白内容**：如 "你好，我是智能客服助手，请问有什么可以帮您？"
|
||
|
||
### 2.3 配置模型
|
||
|
||
在 **模型** 标签页中选择之前添加的资源：
|
||
|
||
| 配置项 | 说明 |
|
||
|-------|------|
|
||
| LLM 模型 | 选择在模型接入中添加的大语言模型 |
|
||
| ASR 模型 | 选择在语音识别中添加的 ASR 模型 |
|
||
|
||
### 2.4 配置语音
|
||
|
||
在 **语音** 标签页中配置：
|
||
|
||
| 配置项 | 说明 |
|
||
|-------|------|
|
||
| 启用语音输出 | 开启后助手会用语音回复 |
|
||
| 选择声音 | 选择在声音资源中添加的音色 |
|
||
| 语速 | 可微调当前助手的说话速度 |
|
||
|
||
### 2.5 保存配置
|
||
|
||
完成配置后，点击页面顶部的 **保存** 按钮。
|
||
|
||
---
|
||
|
||
## 第三步：测试助手
|
||
|
||
### 3.1 打开测试面板
|
||
|
||
点击助手卡片右上角的 **测试** 按钮，打开实时调试面板。
|
||
|
||
### 3.2 进行对话测试
|
||
|
||
| 测试场景 | 示例问题 | 预期结果 |
|
||
|---------|---------|---------|
|
||
| 基础问候 | "你好" | 助手友好回应 |
|
||
| 功能询问 | "你能做什么？" | 介绍自身能力 |
|
||
| 业务问题 | 根据你的场景设计 | 正确回答 |
|
||
| 边界测试 | 无关问题 | 婉拒或引导 |
|
||
|
||
### 3.3 检查各环节
|
||
|
||
在调试面板中可以看到：
|
||
|
||
- **ASR 输出**：用户语音识别结果
|
||
- **LLM 输入/输出**：模型的输入和生成内容
|
||
- **TTS 状态**：语音合成状态
|
||
|
||
---
|
||
|
||
## 第四步：发布助手
|
||
|
||
测试通过后：
|
||
|
||
1. 点击 **发布** 按钮
|
||
2. 复制生成的连接信息：
|
||
- `assistant_id`：用于 API 调用
|
||
- WebSocket 地址：用于实时对话
|
||
|
||
### 嵌入到应用
|
||
|
||
```javascript
|
||
const ws = new WebSocket('ws://your-server/ws?assistant_id=YOUR_ASSISTANT_ID');
|
||
|
||
ws.onopen = () => {
|
||
ws.send(JSON.stringify({
|
||
type: 'session.start',
|
||
audio: {
|
||
encoding: 'pcm_s16le',
|
||
sample_rate_hz: 16000,
|
||
channels: 1
|
||
}
|
||
}));
|
||
};
|
||
|
||
ws.onmessage = (event) => {
|
||
console.log('收到消息:', event.data);
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 资源库中添加模型失败？
|
||
|
||
1. 检查 API Key 是否正确
|
||
2. 确认 Base URL 格式正确（通常以 `/v1` 结尾）
|
||
3. 验证网络能否访问对应的 API 服务
|
||
|
||
### 助手不回复？
|
||
|
||
1. 检查是否已选择 LLM 模型
|
||
2. 确认 LLM 模型配置正确（可在模型接入页面预览测试）
|
||
3. 查看浏览器控制台是否有错误
|
||
|
||
### 语音识别不准确？
|
||
|
||
1. 检查是否选择了正确的语言
|
||
2. 尝试添加热词提高专有名词识别率
|
||
3. 确保录音设备工作正常
|
||
|
||
### 语音无法播放？
|
||
|
||
1. 检查浏览器是否允许自动播放音频
|
||
2. 确认已选择声音并正确配置
|
||
3. 在声音资源页面点击试听确认配置正确
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
恭喜！你已成功创建了第一个 AI 助手。接下来可以：
|
||
|
||
- [配置知识库](../customization/knowledge-base.md) - 让助手回答专业问题
|
||
- [添加工具](../customization/tools.md) - 扩展助手能力
|
||
- [查看 API 文档](../api-reference/websocket.md) - 深入了解协议细节
|
||
- [Docker 部署](../deployment/index.md) - 使用容器运行
|