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.

2026-03-01 22:38:50 +08:00
parent 6a46ec69f4
commit 2418df80e5
33 changed files with 3664 additions and 693 deletions
--- a/docs/content/quickstart/api.md
+++ b/docs/content/quickstart/api.md
@@ -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)