# 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汉字)