463 lines
11 KiB
Markdown
463 lines
11 KiB
Markdown
# 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汉字) |