From a0031344771532f9d4a853cd76e27d7f92893352 Mon Sep 17 00:00:00 2001 From: Xin Wang Date: Mon, 2 Mar 2026 17:30:48 +0800 Subject: [PATCH] Update documentation to enhance clarity and resource configuration for RAS - Revised the introduction in index.md to emphasize the need for resource configuration before creating an AI assistant. - Added a new section detailing the configuration process for ASR, LLM, and TTS resources. - Updated the quickstart guide to reflect the new resource management steps and included troubleshooting tips for common issues. - Removed the outdated API guide as it has been integrated into the new resource configuration workflow. --- docs/content/index.md | 20 +- docs/content/quickstart/api.md | 241 -------------------- docs/content/quickstart/dashboard.md | 318 +++++++++++++++++---------- docs/content/quickstart/index.md | 260 +++++++++++++++++----- 4 files changed, 420 insertions(+), 419 deletions(-) delete mode 100644 docs/content/quickstart/api.md diff --git a/docs/content/index.md b/docs/content/index.md index d1802a0..d052c00 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,6 +1,6 @@ # 实时交互智能体工作平台（RAS） -实时交互智能体工作平台（Realtime Agent Studio，简称 RAS）是一款以大语音模型为核心，构建实时交互音视频智能体的工作平台。支持管线式的全双工交互引擎和原生多模态模型两种核心，覆盖实时交互智能体构建过程中的配置、测试、发布、监控流程环节，平台包含大模型集成、语音识别、语音合成、自动化测试等功能，帮助用户快速构建实时交互智能体。 +实时交互智能体工作平台（Realtime Agent Studio，简称 RAS）是一款以大语言模型为核心，构建实时交互音视频智能体的工作平台。支持管线式的全双工交互引擎和原生多模态模型两种核心，覆盖实时交互智能体构建过程中的配置、测试、发布、监控流程环节，平台包含大模型集成、语音识别、语音合成、自动化测试等功能，帮助用户快速构建实时交互智能体。 可以将该平台看作Vapi，Retell，ElevenAgents的开源替代。 @@ -126,6 +126,18 @@ --- +## 技术栈 + +| 层级 | 技术 | +|------|------| +| Frontend | React, TypeScript, Tailwind CSS | +| State | Zustand, React Query | +| Backend | FastAPI (Python) | +| Engine | Python | +| Database | SQLite | + +--- + ## 快速导航
@@ -162,8 +174,4 @@ 使用问题与故障排查 -
- -## 技术支持 - -如有问题，请提交 Issue 或联系技术支持团队。 + \ No newline at end of file diff --git a/docs/content/quickstart/api.md b/docs/content/quickstart/api.md deleted file mode 100644 index ce4ad19..0000000 --- a/docs/content/quickstart/api.md +++ /dev/null @@ -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) diff --git a/docs/content/quickstart/dashboard.md b/docs/content/quickstart/dashboard.md index 1030e35..57643c0 100644 --- a/docs/content/quickstart/dashboard.md +++ b/docs/content/quickstart/dashboard.md @@ -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 Name：FunAudioLLM/SenseVoiceSmall +Base URL：https://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 - - +``` +模型名称：GPT-4o Mini +模型类型：文本 +模型标识：gpt-4o-mini +Base URL：https://api.openai.com/v1 +温度：0.7 +上下文长度：8192 ``` -详细集成指南请参考 [API 参考](../api-reference/websocket.md)。 +**硅基流动 Qwen** -## 常见问题 +``` +模型名称：Qwen2.5-7B +模型类型：文本 +模型标识：Qwen/Qwen2.5-7B-Instruct +Base URL：https://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 +声音 ID：FunAudioLLM/CosyVoice2-0.5B:anna +Base URL：https://api.siliconflow.cn/v1 +语速：1.0 +性别：女 +语言：中文 +``` + +**DashScope TTS** + +``` +厂商：DashScope +声音名称：Cherry +模型：qwen3-tts-flash-realtime +声音 ID：Cherry +Base URL：wss://dashscope.aliyuncs.com/api-ws/v1/realtime +语速：1.0 +``` + +### CosyVoice 可用音色 + +| 音色 ID | 性别 | 风格 | +|--------|-----|------| +| alex | 男 | 成熟稳重 | +| anna | 女 | 温柔亲切 | +| bella | 女 | 活泼甜美 | +| benjamin | 男 | 年轻活力 | +| charles | 男 | 专业商务 | +| claire | 女 | 清新自然 | +| david | 男 | 沉稳大气 | +| diana | 女 | 优雅知性 | + +### 试听声音效果 + +1. 在声音列表中找到目标声音 +2. 点击 **播放** 按钮 +3. 系统会自动合成一段试听语音 +4. 检查声音效果是否符合预期 + +### 克隆声音 + +如需使用自定义声音： + +1. 点击 **克隆声音** 按钮 +2. 上传参考音频文件（WAV/MP3） +3. 填写声音名称和描述 +4. 点击 **开始克隆** + +!!! note "声音克隆说明" + 声音克隆功能需要 TTS 服务支持。上传的参考音频建议为 10-30 秒的清晰人声录音。 + +--- + +## 配置最佳实践 + +### 资源命名规范 + +建议使用清晰的命名规范，便于后续管理： + +``` +[厂商/模型]-[用途/语言]-[特点] +``` + +示例： +- `SF-SenseVoice-中文` +- `OpenAI-GPT4o-对话` +- `SF-CosyVoice-Anna女声` + +### 多环境管理 + +如果有测试和生产环境，建议： + +1. 为不同环境创建独立的资源配置 +2. 在名称中标注环境，如 `GPT4o-Prod`、`GPT4o-Test` +3. 通过"启用"开关控制可见性 + +### 成本优化 + +| 场景 | 推荐配置 | +|-----|---------| +| 开发测试 | 使用低成本模型，如 GPT-4o-mini | +| 生产环境 | 根据质量要求选择合适模型 | +| 高并发 | 考虑使用本地部署的开源模型 | + +--- ## 下一步 -- [通过 API 创建助手](api.md) -- [配置知识库](../customization/knowledge-base.md) -- [添加工具](../customization/tools.md) +资源配置完成后，请返回 [快速开始](index.md) 继续创建助手。 diff --git a/docs/content/quickstart/index.md b/docs/content/quickstart/index.md index 32c0ce1..c339f92 100644 --- a/docs/content/quickstart/index.md +++ b/docs/content/quickstart/index.md @@ -4,99 +4,221 @@ ## 概述 -本指南将帮助你快速创建一个能够进行语音对话的智能助手。你可以选择通过控制台或 API 两种方式创建。 +本指南将帮助你通过控制台快速创建一个能够进行语音对话的智能助手。在创建助手之前，需要先在资源库（Library）中配置所需的模型资源。 ## 前提条件 - 已部署 Realtime Agent Studio (RAS) 服务 -- 已配置至少一个 LLM 模型 -- 已配置至少一个 TTS 语音 +- 拥有 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 助手。接下来可以：