# AI对话系统 API 文档 本文档详细说明AI对话系统的API接口，包括单轮对话和多轮对话功能。 ## 接口基础信息 - **基础路径**: `/api/ai/` - **认证方式**: Token 认证 - **返回格式**: JSON ## API 概览 | 接口路径 | 方法 | 描述 | |---------|------|------| | `/api/ai/chat/{bot_id}/` | POST | 单轮对话 | | `/api/ai/multichat/` | POST | 多轮对话 | ## 1. 单轮对话 ### 1.1 发起单轮对话 使用指定的Bot ID进行单轮对话。 - **URL**: `/api/ai/chat/{bot_id}/` - **方法**: `POST` - **参数**: - `bot_id` (路径参数): Bot ID，整数类型 - **认证**: 需要 - **请求体**: ```json { "message": "你好，请介绍一下自己", "input_type": "text", "output_type": "text" } ``` **请求参数说明：** | 参数名 | 类型 | 必填 | 描述 | |-------|-----|------|-----| | message | string | 是 | 用户输入的消息内容 | | input_type | string | 否 | 输入类型，默认为"text"，支持"text"、"audio" | | output_type | string | 否 | 输出类型，默认为"text"，支持"text"、"audio" | **响应示例：** ```json { "status": "success", "code": 200, "data": { "bot_id": 1, "response": "你好！我是AI助手，很高兴为您服务。我可以帮助您回答问题、进行对话交流...", "input_type": "text", "output_type": "text", "audio_url": null, "timestamp": "2023-01-01T12:00:00Z" } } ``` ### 1.2 语音输入对话 支持语音输入的单轮对话。 - **URL**: `/api/ai/chat/{bot_id}/` - **方法**: `POST` - **Content-Type**: `multipart/form-data` - **请求参数**: | 参数名 | 类型 | 必填 | 描述 | |-------|-----|------|-----| | audio_file | file | 是 | 音频文件(支持mp3, wav, m4a格式) | | input_type | string | 是 | 输入类型，值为"audio" | | output_type | string | 否 | 输出类型，"text"或"audio"，默认为"text" | **响应示例：** ```json { "status": "success", "code": 200, "data": { "bot_id": 1, "transcribed_text": "今天天气怎么样？", "response": "今天天气晴朗，气温25度，适合出行。", "input_type": "audio", "output_type": "text", "audio_url": null, "timestamp": "2023-01-01T12:00:00Z" } } ``` ### 1.3 语音输出对话 获取语音格式的AI回复。 - **请求体**: ```json { "message": "请播报今日天气", "input_type": "text", "output_type": "audio" } ``` **响应示例：** ```json { "status": "success", "code": 200, "data": { "bot_id": 1, "response": "今天北京天气晴朗，气温22-28度，微风，适宜出行。", "input_type": "text", "output_type": "audio", "audio_url": "https://example.com/audio/response_20230101_120000.mp3", "audio_duration": 5.2, "timestamp": "2023-01-01T12:00:00Z" } } ``` ## 2. 多轮对话 ### 2.1 创建多轮对话 启动一个新的多轮对话会话。 - **URL**: `/api/ai/multichat/` - **方法**: `POST` - **请求体**: ```json { "message": "我想了解一下人工智能", "conversation_id": null, "input_type": "text", "output_type": "text", "context": { "user_profile": { "interests": ["技术", "AI"], "level": "初学者" } } } ``` **请求参数说明：** | 参数名 | 类型 | 必填 | 描述 | |-------|-----|------|-----| | message | string | 是 | 用户输入的消息内容 | | conversation_id | string | 否 | 对话会话ID，首次创建为null | | input_type | string | 否 | 输入类型，默认"text" | | output_type | string | 否 | 输出类型，默认"text" | | context | object | 否 | 对话上下文信息 | **响应示例：** ```json { "status": "success", "code": 200, "data": { "conversation_id": "conv_20230101_120000_abc123", "message_id": "msg_001", "response": "人工智能是一个非常有趣的领域！AI技术目前主要包括机器学习、深度学习、自然语言处理等...", "input_type": "text", "output_type": "text", "audio_url": null, "context": { "conversation_history": [ { "role": "user", "content": "我想了解一下人工智能", "timestamp": "2023-01-01T12:00:00Z" }, { "role": "assistant", "content": "人工智能是一个非常有趣的领域！...", "timestamp": "2023-01-01T12:00:01Z" } ] }, "timestamp": "2023-01-01T12:00:01Z" } } ``` ### 2.2 继续多轮对话 在现有会话中继续对话。 - **URL**: `/api/ai/multichat/` - **方法**: `POST` - **请求体**: ```json { "message": "能详细说说机器学习吗？", "conversation_id": "conv_20230101_120000_abc123", "input_type": "text", "output_type": "text" } ``` **响应示例：** ```json { "status": "success", "code": 200, "data": { "conversation_id": "conv_20230101_120000_abc123", "message_id": "msg_002", "response": "机器学习是AI的一个重要分支，它让计算机能够从数据中自动学习规律...", "input_type": "text", "output_type": "text", "audio_url": null, "context": { "conversation_history": [ { "role": "user", "content": "我想了解一下人工智能", "timestamp": "2023-01-01T12:00:00Z" }, { "role": "assistant", "content": "人工智能是一个非常有趣的领域！...", "timestamp": "2023-01-01T12:00:01Z" }, { "role": "user", "content": "能详细说说机器学习吗？", "timestamp": "2023-01-01T12:00:10Z" }, { "role": "assistant", "content": "机器学习是AI的一个重要分支...", "timestamp": "2023-01-01T12:00:11Z" } ], "total_messages": 4 }, "timestamp": "2023-01-01T12:00:11Z" } } ``` ### 2.3 多轮对话语音功能 多轮对话同样支持语音输入输出。 **语音输入示例：** - **Content-Type**: `multipart/form-data` - **请求参数**: | 参数名 | 类型 | 必填 | 描述 | |-------|-----|------|-----| | audio_file | file | 是 | 音频文件 | | conversation_id | string | 是 | 对话会话ID | | input_type | string | 是 | 值为"audio" | | output_type | string | 否 | "text"或"audio" | ## 3. 支持的音频格式 系统支持以下音频格式的输入： - **MP3**: 标准MP3格式 - **WAV**: PCM WAV格式 - **M4A**: AAC M4A格式 - **AMR**: AMR窄带格式 **音频要求：** - 文件大小限制：10MB - 时长限制：60秒 - 采样率：8000-48000Hz - 声道：单声道或立体声 ## 4. AI服务提供商配置 系统当前集成的AI服务： ### 4.1 Kimi (Moonshot AI) - **模型**: moonshot-v1-8k, moonshot-v1-32k - **特点**: 中文优化，上下文理解能力强 - **配置**: `KIMI_API_KEY` 环境变量 ### 4.2 音频服务提供商 系统支持多个音频服务提供商，可通过环境变量 `AUDIO_SERVICE_PROVIDER` 配置： - **aliyun**: 阿里云智能语音服务 - **huoshan**: 火山引擎语音服务 - **tencent**: 腾讯云语音服务 ## 5. 错误响应 ### 5.1 常见错误码 | 错误码 | HTTP状态码 | 描述 | |-------|-----------|------| | 400 | 400 | 请求参数错误 | | 401 | 401 | 未认证或Token无效 | | 413 | 413 | 文件过大 | | 415 | 415 | 不支持的音频格式 | | 429 | 429 | 请求频率过高 | | 500 | 500 | AI服务异常 | ### 5.2 错误响应格式 ```json { "status": "error", "code": 400, "message": "音频文件格式不支持", "details": { "supported_formats": ["mp3", "wav", "m4a", "amr"], "received_format": "ogg" } } ``` ## 6. 使用示例 ### 6.1 Python 客户端示例 ```python import requests import json # 配置 API_BASE = "http://localhost:8000/api/ai" TOKEN = "your-auth-token" headers = { "Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json" } # 单轮对话示例 def single_chat(bot_id, message): url = f"{API_BASE}/chat/{bot_id}/" data = { "message": message, "input_type": "text", "output_type": "text" } response = requests.post(url, headers=headers, json=data) return response.json() # 多轮对话示例 def multi_chat(message, conversation_id=None): url = f"{API_BASE}/multichat/" data = { "message": message, "conversation_id": conversation_id, "input_type": "text", "output_type": "text" } response = requests.post(url, headers=headers, json=data) return response.json() # 使用示例 result = single_chat(1, "你好，请介绍一下自己") print(result) # 开始多轮对话 result1 = multi_chat("我想学习Python编程") conversation_id = result1["data"]["conversation_id"] # 继续对话 result2 = multi_chat("从哪里开始学比较好？", conversation_id) print(result2) ``` ### 6.2 JavaScript 客户端示例 ```javascript class AIClient { constructor(baseUrl, token) { this.baseUrl = baseUrl; this.token = token; } async singleChat(botId, message, inputType = 'text', outputType = 'text') { const response = await fetch(`${this.baseUrl}/chat/${botId}/`, { method: 'POST', headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ message: message, input_type: inputType, output_type: outputType }) }); return await response.json(); } async multiChat(message, conversationId = null, inputType = 'text', outputType = 'text') { const response = await fetch(`${this.baseUrl}/multichat/`, { method: 'POST', headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ message: message, conversation_id: conversationId, input_type: inputType, output_type: outputType }) }); return await response.json(); } } // 使用示例 const client = new AIClient('http://localhost:8000/api/ai', 'your-auth-token'); // 单轮对话 client.singleChat(1, '你好！').then(result => { console.log(result); }); // 多轮对话 client.multiChat('我想了解AI').then(result => { const conversationId = result.data.conversation_id; return client.multiChat('能详细介绍一下吗？', conversationId); }).then(result => { console.log(result); }); ``` ## 7. 性能和限制 ### 7.1 速率限制 - 单轮对话: 每秒最多10次请求 - 多轮对话: 每秒最多5次请求 - 语音输入: 每分钟最多20次请求 ### 7.2 响应时间 - 文本对话: 通常1-3秒 - 语音转文本: 通常2-5秒 - 文本转语音: 通常3-8秒 ### 7.3 上下文限制 - 单轮对话: 无上下文 - 多轮对话: 最多保持50轮对话历史 - Token限制: 单次请求最大8K tokens (约6000汉字)