zyc/lty

Fork 0

zyc 0c610c1e49 first commit

2026-03-17 13:17:02 +08:00

11 KiB

Raw Permalink Blame History

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，整数类型
认证: 需要
请求体:

{
  "message": "你好，请介绍一下自己",
  "input_type": "text",
  "output_type": "text"
}

请求参数说明：

参数名	类型	必填	描述
message	string	是	用户输入的消息内容
input_type	string	否	输入类型，默认为"text"，支持"text"、"audio"
output_type	string	否	输出类型，默认为"text"，支持"text"、"audio"

响应示例：

{
  "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"

响应示例：

{
  "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回复。

请求体:

{
  "message": "请播报今日天气",
  "input_type": "text",
  "output_type": "audio"
}

响应示例：

{
  "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
请求体:

{
  "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	否	对话上下文信息

响应示例：

{
  "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
请求体:

{
  "message": "能详细说说机器学习吗？",
  "conversation_id": "conv_20230101_120000_abc123",
  "input_type": "text",
  "output_type": "text"
}

响应示例：

{
  "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 错误响应格式

{
  "status": "error",
  "code": 400,
  "message": "音频文件格式不支持",
  "details": {
    "supported_formats": ["mp3", "wav", "m4a", "amr"],
    "received_format": "ogg"
  }
}

6. 使用示例

6.1 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 客户端示例

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

11 KiB Raw Permalink Blame History Unescape Escape

AI对话系统 API 文档

接口基础信息

API 概览

1. 单轮对话

1.1 发起单轮对话

1.2 语音输入对话

1.3 语音输出对话

2. 多轮对话

2.1 创建多轮对话

2.2 继续多轮对话

2.3 多轮对话语音功能

3. 支持的音频格式

4. AI服务提供商配置

4.1 Kimi (Moonshot AI)

4.2 音频服务提供商

5. 错误响应

5.1 常见错误码

5.2 错误响应格式

6. 使用示例

6.1 Python 客户端示例

6.2 JavaScript 客户端示例

7. 性能和限制

7.1 速率限制

7.2 响应时间

7.3 上下文限制

11 KiB

Raw Permalink Blame History