liqupan/server

Fork 0

Files

liqupan b767041311 feat ：init

2025-11-02 19:34:16 +08:00

32 KiB

Raw Permalink Blame History

聊天对话接口测试文档

接口概述

本文档提供了聊天对话系统的所有API接口的详细测试用例，包括请求参数、响应结构和示例数据。

统一响应格式

所有接口均采用标准化的JSON响应格式：

{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1640995200000
}

响应字段说明

字段名	类型	说明
code	Integer	状态码（200：成功，400：客户端错误，500：服务器错误）
message	String	响应消息
data	Object	业务数据
timestamp	Long	响应时间戳

参数详细说明

核心参数配置说明

在所有聊天接口中，以下四个参数用于配置模型、模板和语音服务，本节详细说明每个参数的可选值范围及其在数据库中对应的具体内容。

1. modelId（模型ID）

参数说明： 指定使用的大语言模型配置
默认值： 7
数据库表： sys_config
筛选条件： configType = 'llm'

可选值及对应配置：

modelId	configName	provider	modelType	说明
1	gpt-3.5-turbo	openai	chat	OpenAI GPT-3.5 Turbo模型
2	glm-4	zhipu	chat	智谱AI GLM-4模型
3	spark-lite	xfyun	chat	讯飞星火认知大模型Lite版
4	qwen1.5-7b-chat	qwen	chat	阿里云通义千问1.5-7B对话模型
5	lmstudio-local	lmstudio	chat	LM Studio本地部署模型
7	qwen2.5-7b-instruct	qwen	chat	阿里云通义千问2.5-7B指令模型（默认）

使用示例：

{
  "modelId": 7,  // 使用通义千问2.5-7B指令模型
  "message": "你好"
}

2. templateId（模板ID）

参数说明： 指定使用的对话模板，定义AI的角色和行为特征
默认值： 6
数据库表： sys_template

可选值及对应配置：

templateId	templateName	templateContent（角色描述）
1	通用助手	你是一个通用的AI助手，能够回答各种问题，提供有用的信息和建议。请保持友好、专业的态度。
2	教育老师	你是一位经验丰富的教育工作者，擅长用简单易懂的方式解释复杂概念，善于启发学生思考。
3	专业领域专家	你是一位在多个专业领域都有深入研究的专家，能够提供专业、准确的技术建议和解决方案。
4	中英翻译专家	你是一位专业的中英文翻译专家，能够准确、流畅地进行中英文互译，注重语言的准确性和文化背景。
5	知心朋友	你是一位温暖、善解人意的朋友，善于倾听和理解他人的情感，能够提供情感支持和建议。
6	湾湾小何	你是湾湾小何，一个活泼可爱的台湾女孩，说话带有台湾腔调，性格开朗友善，喜欢用台湾的网络用语。

使用示例：

{
  "templateId": 2,  // 使用教育老师模板
  "message": "请解释一下量子力学的基本概念"
}

3. sttConfigId（语音识别配置ID）

参数说明： 指定使用的语音转文字（STT）服务配置
默认值： 9
数据库表： sys_config
筛选条件： configType = 'stt'

可选值及对应配置：

sttConfigId	configName	provider	说明
6	语音识别大模型-字符版	volcengine	火山引擎语音识别服务
9	qwen3-asr-flash	aliyun	阿里云通义千问3 ASR闪电版（默认）

使用示例：

{
  "sttConfigId": 9,  // 使用阿里云通义千问3 ASR
  "audioData": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA..."
}

4. ttsConfigId（语音合成配置ID）

参数说明： 指定使用的文字转语音（TTS）服务配置
默认值： 8
数据库表： sys_config
筛选条件： configType = 'tts'

可选值及对应配置：

ttsConfigId	configName	provider	说明
5	语音合成大模型-字符版	volcengine	火山引擎语音合成服务
8	语音合成服务	aliyun	阿里云语音合成服务（默认）

使用示例：

{
  "ttsConfigId": 8,  // 使用阿里云语音合成
  "text": "你好，欢迎使用语音合成服务"
}

参数组合建议

推荐配置组合：

默认配置（推荐）：

{
  "modelId": 7,        // 通义千问2.5-7B
  "templateId": 6,     // 湾湾小何
  "sttConfigId": 9,    // 阿里云ASR
  "ttsConfigId": 8     // 阿里云TTS
}

教育场景配置：

{
  "modelId": 4,        // 通义千问1.5-7B
  "templateId": 2,     // 教育老师
  "sttConfigId": 9,    // 阿里云ASR
  "ttsConfigId": 8     // 阿里云TTS
}

专业咨询配置：

{
  "modelId": 2,        // 智谱GLM-4
  "templateId": 3,     // 专业领域专家
  "sttConfigId": 9,    // 阿里云ASR
  "ttsConfigId": 8     // 阿里云TTS
}

注意事项

配置有效性： 请确保所选择的配置ID在数据库中存在且状态为可用
服务可用性： 不同的provider可能需要相应的API密钥和服务配置
兼容性： 建议使用相同provider的STT和TTS服务以获得更好的兼容性
默认值： 如果不指定参数，系统将使用上述默认值
权限控制： 某些配置可能需要特定的用户权限才能使用

接口列表

1. 同步对话接口

接口路径： /api/chat/sync
请求方法： POST
Content-Type： application/json

请求参数

参数名	类型	必填	默认值	说明	示例值
message	String	是	-	用户消息内容	"你好，请介绍一下人工智能"
sessionId	String	否	自动生成	会话ID	"session123"
useFunctionCall	Boolean	否	false	是否使用函数调用	false
modelId	Integer	否	7	模型ID	7
templateId	Integer	否	1	模板ID	1
sttConfigId	Integer	否	9	STT配置ID	9
ttsConfigId	Integer	否	8	TTS配置ID	8

请求示例

{
  "message": "你好，请介绍一下人工智能",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}

测试指令

基础测试：

curl -X POST "http://localhost:8080/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你好，请介绍一下人工智能",
    "sessionId": "test_session_001",
    "useFunctionCall": false,
    "modelId": 7,
    "templateId": 1,
    "sttConfigId": 9,
    "ttsConfigId": 8
  }'

最简测试（仅必填参数）：

curl -X POST "http://localhost:8080/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "今天天气怎么样？"
  }'

功能调用测试：

curl -X POST "http://localhost:8080/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "帮我查询一下北京的天气",
    "sessionId": "function_test_001",
    "useFunctionCall": true,
    "modelId": 7,
    "templateId": 1
  }'

响应结构

成功响应：

{
  "code": 200,
  "message": "对话成功",
  "data": {
    "response": "人工智能（AI）是计算机科学的一个分支...",
    "sessionId": "session123"
  },
  "timestamp": 1640995200000
}

失败响应：

{
  "code": 500,
  "message": "系统内部错误: 模型服务不可用",
  "data": null,
  "timestamp": 1640995200000
}

2. 流式对话接口

接口路径： /api/chat/stream
请求方法： POST
Content-Type： application/json
响应类型： text/event-stream

请求参数

参数名	类型	必填	默认值	说明	示例值
message	String	是	-	用户消息内容	"请详细介绍一下人工智能的发展历程"
sessionId	String	否	自动生成	会话ID	"session123"
useFunctionCall	Boolean	否	false	是否使用函数调用	false
modelId	Integer	否	7	模型ID	7
templateId	Integer	否	1	模板ID	1
sttConfigId	Integer	否	9	STT配置ID	9
ttsConfigId	Integer	否	8	TTS配置ID	8

请求示例

{
  "message": "请详细介绍一下人工智能的发展历程",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}

测试指令

基础流式测试：

curl -X POST "http://localhost:8080/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "请详细介绍一下人工智能的发展历程",
    "sessionId": "stream_test_001",
    "useFunctionCall": false,
    "modelId": 7,
    "templateId": 1,
    "sttConfigId": 9,
    "ttsConfigId": 8
  }' \
  --no-buffer

最简流式测试：

curl -X POST "http://localhost:8080/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "写一首关于春天的诗"
  }' \
  --no-buffer

长文本流式测试：

curl -X POST "http://localhost:8080/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "请详细解释量子计算的原理、应用场景和未来发展趋势",
    "sessionId": "long_stream_test_001",
    "modelId": 7,
    "templateId": 1
  }' \
  --no-buffer

响应结构

SSE事件流：

event: start
data: {"sessionId": "session123", "timestamp": 1640995200000}

event: sentence
data: {"content": "人工智能的发展历程可以分为几个重要阶段：", "sessionId": "session123"}

event: sentence
data: {"content": "1. 起源阶段（1940-1956年）...", "sessionId": "session123"}

event: complete
data: {"sessionId": "session123", "totalTokens": 1500, "timestamp": 1640995210000}

错误事件：

event: error
data: 对话失败: 网络连接超时

3. 文本转语音接口

接口路径： /api/chat/tts
请求方法： POST
Content-Type： application/json

请求参数

参数名	类型	必填	默认值	说明	示例值
text	String	是	-	要转换的文本	"你好，欢迎使用语音合成服务"
ttsConfigId	Integer	否	8	TTS配置ID	8

请求示例

{
  "text": "你好，欢迎使用语音合成服务，这是一个测试文本",
  "ttsConfigId": 8
}

测试指令

基础TTS测试：

curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好，欢迎使用语音合成服务，这是一个测试文本",
    "ttsConfigId": 8
  }'

最简TTS测试：

curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "今天天气真不错"
  }'

长文本TTS测试：

curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "人工智能是计算机科学的一个分支，它企图了解智能的实质，并生产出一种新的能以人类智能相似的方式做出反应的智能机器。该领域的研究包括机器人、语言识别、图像识别、自然语言处理和专家系统等。",
    "ttsConfigId": 8
  }'

保存音频文件测试：

curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "这是一个音频文件保存测试",
    "ttsConfigId": 8
  }' | jq -r '.data.audioBase64' | base64 -d > test_audio.wav

响应结构

成功响应：

{
  "code": 200,
  "message": "语音合成成功",
  "data": {
    "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
    "audioPath": "/audio/tts_abc123.mp3",
    "timestamp": 1640995200000
  },
  "timestamp": 1640995200000
}

字段说明：

audioBase64：音频数据的Base64编码，可直接播放或保存为文件。
audioPath：生成的音频文件在服务器上的路径，便于按需下载或复用。
timestamp：生成时间戳，Unix毫秒。

失败响应：

{
  "code": 500,
  "message": "系统内部错误: TTS服务不可用",
  "data": null,
  "timestamp": 1640995200000
}

4. 对话+语音合成接口

接口路径： /api/chat/answer-tts
请求方法： POST
Content-Type： application/json

请求参数

参数名	类型	必填	默认值	说明	示例值
message	String	是	-	用户消息内容	"今天天气怎么样？"
sessionId	String	否	自动生成	会话ID	"session123"
useFunctionCall	Boolean	否	false	是否使用函数调用	false
modelId	Integer	否	7	模型ID	7
templateId	Integer	否	1	模板ID	1
sttConfigId	Integer	否	9	STT配置ID	9
ttsConfigId	Integer	否	8	TTS配置ID	8

请求示例

{
  "message": "今天天气怎么样？",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}

测试指令

基础对话+TTS测试：

curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "今天天气怎么样？",
    "sessionId": "answer_tts_test_001",
    "useFunctionCall": false,
    "modelId": 7,
    "templateId": 1,
    "sttConfigId": 9,
    "ttsConfigId": 8
  }'

最简对话+TTS测试：

curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你好，请自我介绍一下"
  }'

功能调用+TTS测试：

curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "帮我查询一下上海的天气情况",
    "sessionId": "function_tts_test_001",
    "useFunctionCall": true,
    "modelId": 7,
    "templateId": 1,
    "ttsConfigId": 8
  }'

保存对话音频测试：

curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "请简单介绍一下人工智能",
    "sessionId": "save_audio_test_001",
    "ttsConfigId": 8
  }' | jq -r '.data.audioBase64' | base64 -d > answer_audio.wav

响应结构

成功响应：

{
  "code": 200,
  "message": "对话成功",
  "data": {
    "response": "今天天气晴朗，温度适宜，是个不错的天气。",
    "sessionId": "session123",
    "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
    "audioPath": "/audio/tts_20241215_143022_abc123.wav",
    "timestamp": 1640995200000
  },
  "timestamp": 1640995200000
}

字段说明：

response：LLM模型回复的文本内容
sessionId：会话ID，用于标识上下文
audioBase64：将回复文本合成为语音后的Base64编码，可直接播放
audioPath：合成语音文件在服务器上的路径，便于回放或缓存
timestamp：响应时间戳，Unix毫秒

5. 语音对话接口

接口路径： /api/chat/voice-chat
请求方法： POST
Content-Type： application/json

请求参数

参数名	类型	必填	默认值	说明	示例值
audioData	String	是	-	Base64编码的音频数据	"UklGRiQAAABXQVZFZm10IBAAAAABAAEA..."
sessionId	String	否	自动生成	会话ID	"session123"
useFunctionCall	Boolean	否	false	是否使用函数调用	false
modelId	Integer	否	7	模型ID	7
templateId	Integer	否	1	模板ID	1
sttConfigId	Integer	否	9	STT配置ID	9
ttsConfigId	Integer	否	8	TTS配置ID	8

请求示例

{
  "audioData": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}

测试指令

基础语音对话测试（需要先准备音频文件）：

# 1. 先将音频文件转换为Base64
AUDIO_BASE64=$(base64 -w 0 test_audio.wav)

# 2. 发送语音对话请求
curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"voice_chat_test_001\",
    \"useFunctionCall\": false,
    \"modelId\": 7,
    \"templateId\": 1,
    \"sttConfigId\": 9,
    \"ttsConfigId\": 8
  }"

最简语音对话测试：

# 使用最少参数进行语音对话
AUDIO_BASE64=$(base64 -w 0 simple_audio.wav)

curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\"
  }"

功能调用语音对话测试：

# 语音询问天气并启用功能调用
AUDIO_BASE64=$(base64 -w 0 weather_question.wav)

curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"voice_function_test_001\",
    \"useFunctionCall\": true,
    \"modelId\": 7,
    \"templateId\": 1,
    \"sttConfigId\": 9,
    \"ttsConfigId\": 8
  }"

保存语音对话结果：

# 进行语音对话并保存返回的音频
AUDIO_BASE64=$(base64 -w 0 input_audio.wav)

curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"save_voice_test_001\",
    \"ttsConfigId\": 8
  }" | jq -r '.data.audioData' | base64 -d > voice_response.wav

响应结构

成功响应：

{
  "code": 200,
  "message": "语音对话成功",
  "data": {
    "sttResult": {
      "text": "今天天气怎么样？",
      "audioFormat": "wav",
      "audioSize": 245760,
      "sttProvider": "qwen3-asr-flash"
    },
    "llmResult": {
      "response": "今天天气晴朗，温度适宜，是个不错的天气。",
      "inputText": "今天天气怎么样？"
    },
    "ttsResult": {
      "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
      "audioPath": "/audio/voice_chat_20241215_143022_abc123.wav",
      "timestamp": 1640995202000
    },
    "sessionId": "session123",
    "timestamp": 1640995202000
  },
  "timestamp": 1640995202000
}

字段说明：

sttResult：语音识别结果对象
- text：识别出的文本内容
- audioFormat：输入音频格式
- audioSize：输入音频文件大小（字节）
- sttProvider：使用的STT服务提供商
llmResult：大语言模型处理结果对象
- response：LLM模型回复的文本内容
- inputText：输入给LLM的文本（即STT识别结果）
ttsResult：语音合成结果对象
- audioBase64：TTS合成后的音频Base64编码，可直接播放
- audioPath：TTS合成音频文件在服务器上的路径
- timestamp：TTS合成时间戳
sessionId：会话ID，用于标识上下文
timestamp：响应时间戳，Unix毫秒

6. 清除会话接口

接口路径： /api/chat/session/{sessionId}
请求方法： DELETE

路径参数

参数名	类型	必填	说明	示例值
sessionId	String	是	要清除的会话ID	"session123"

请求示例

DELETE /api/chat/session/session123

测试指令

清除指定会话：

curl -X DELETE "http://localhost:8080/api/chat/session/session123"

清除测试会话：

curl -X DELETE "http://localhost:8080/api/chat/session/test_session_001"

批量清除多个会话：

# 清除多个测试会话
for session in test_session_001 test_session_002 test_session_003; do
  curl -X DELETE "http://localhost:8080/api/chat/session/$session"
  echo "已清除会话: $session"
done

响应结构

成功响应：

{
  "code": 200,
  "message": "会话清除成功",
  "data": {
    "sessionId": "session123",
    "timestamp": 1640995200000
  },
  "timestamp": 1640995200000
}

7. 清除缓存接口

接口路径： /api/chat/cache
请求方法： DELETE

查询参数

参数名	类型	必填	说明	示例值
sessionId	String	否	指定会话ID（不传则清除所有）	"session123"

请求示例

DELETE /api/chat/cache?sessionId=session123
DELETE /api/chat/cache

测试指令

清除指定会话缓存：

curl -X DELETE "http://localhost:8080/api/chat/cache?sessionId=session123"

清除所有缓存：

curl -X DELETE "http://localhost:8080/api/chat/cache"

清除测试会话缓存：

curl -X DELETE "http://localhost:8080/api/chat/cache?sessionId=test_session_001"

批量清除多个会话缓存：

# 清除多个测试会话的缓存
for session in test_session_001 test_session_002 test_session_003; do
  curl -X DELETE "http://localhost:8080/api/chat/cache?sessionId=$session"
  echo "已清除会话缓存: $session"
done

响应结构

清除指定会话：

{
  "code": 200,
  "message": "缓存清除成功",
  "data": {
    "sessionId": "session123"
  },
  "timestamp": 1640995200000
}

清除所有会话：

{
  "code": 200,
  "message": "缓存清除成功",
  "data": {
    "clearedSessions": 15
  },
  "timestamp": 1640995200000
}

8. 上传音频文件进行语音对话

接口路径： /api/chat/upload-voice-chat
请求方法： POST
Content-Type： multipart/form-data

请求参数

参数名	类型	必填	默认值	说明	示例值
audioFile	File	是	-	音频文件	audio.wav
sessionId	String	否	自动生成	会话ID	"session123"
useFunctionCall	Boolean	否	false	是否使用函数调用	false
modelId	Integer	否	7	模型ID	7
templateId	Integer	否	1	模板ID	1
sttConfigId	Integer	否	9	STT配置ID	9
ttsConfigId	Integer	否	8	TTS配置ID	8
description	String	否	-	音频描述	"用户语音输入"

请求示例

curl -X POST "http://localhost:8080/api/chat/upload-voice-chat" \
  -F "audioFile=@audio.wav" \
  -F "sessionId=session123" \
  -F "useFunctionCall=false" \
  -F "modelId=7" \
  -F "templateId=1" \
  -F "sttConfigId=9" \
  -F "ttsConfigId=8" \
  -F "description=用户语音输入"

响应结构

成功响应：

{
  "code": 200,
  "message": "文件上传成功",
  "data": {
    "sttResult": {
      "text": "今天天气怎么样？",
      "audioFormat": "wav",
      "audioSize": 1024000,
      "sttProvider": "qwen3-asr-flash"
    },
    "llmResult": {
      "response": "今天天气晴朗，温度适宜，是个不错的天气。",
      "inputText": "今天天气怎么样？"
    },
    "ttsResult": {
      "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
      "audioPath": "/audio/upload_voice_chat_20241215_143022_abc123.wav",
      "timestamp": 1640995202000
    },
    "sessionId": "session123",
    "originalFileName": "audio.wav",
    "fileSize": 1024000,
    "contentType": "audio/wav",
    "description": "用户语音输入",
    "timestamp": 1640995202000
  },
  "timestamp": 1640995202000
}

字段说明：

sttResult：语音识别结果对象
- text：识别出的文本内容
- audioFormat：输入音频格式
- audioSize：输入音频文件大小（字节）
- sttProvider：使用的STT服务提供商
llmResult：大语言模型处理结果对象
- response：LLM模型回复的文本内容
- inputText：输入给LLM的文本（即STT识别结果）
ttsResult：语音合成结果对象
- audioBase64：TTS合成后的音频Base64编码，可直接播放
- audioPath：TTS合成音频文件在服务器上的路径
- timestamp：TTS合成时间戳
sessionId：会话ID，用于标识上下文
originalFileName：用户上传的原始文件名
fileSize：用户上传文件的大小（字节）
contentType：上传文件的MIME类型
description：音频描述信息
timestamp：响应时间戳，Unix毫秒

文件验证失败：

{
  "code": 400,
  "message": "参数验证失败: 不支持的音频格式",
  "data": null,
  "timestamp": 1640995200000
}

文件上传异常：

{
  "code": 400,
  "message": "文件上传失败: 文件大小超过限制",
  "data": null,
  "timestamp": 1640995200000
}

错误码说明

错误码	说明	常见原因
200	成功	请求处理成功
400	客户端错误	参数验证失败、文件格式不支持等
500	服务器错误	系统内部错误、服务不可用等

常见错误消息

错误消息	说明	解决方案
消息内容不能为空	message参数为空	检查请求参数
文本内容不能为空	text参数为空	检查请求参数
音频数据不能为空	audioData参数为空	检查音频数据
音频文件不能为空	上传的文件为空	检查上传文件
音频文件大小不能超过50MB	文件过大	压缩音频文件
音频文件大小不能小于1KB	文件过小	检查文件完整性
不支持的音频格式	文件格式不支持	使用支持的格式（wav、mp3、m4a、flac、ogg、aac、wma、amr）
无效的音频文件头	文件头格式错误	检查文件是否损坏或格式正确
文件上传失败	文件保存异常	检查服务器存储空间和权限
系统未配置任何LLM模型	模型配置缺失	联系管理员配置模型
会话不存在	指定的会话ID不存在	检查会话ID或创建新会话

测试建议

参数验证测试： 测试必填参数缺失、参数类型错误等场景
边界值测试： 测试文件大小限制、文本长度限制等
异常场景测试： 测试网络异常、服务不可用等情况
并发测试： 测试多用户同时访问的性能表现
安全测试： 测试恶意文件上传、SQL注入等安全问题

完整测试流程示例

基础功能测试流程

#!/bin/bash
# 聊天功能API完整测试脚本

BASE_URL="http://localhost:8080"
SESSION_ID="complete_test_$(date +%s)"

echo "=== 聊天功能API完整测试 ==="
echo "测试会话ID: $SESSION_ID"
echo "服务器地址: $BASE_URL"
echo ""

# 1. 同步对话测试
echo "1. 测试同步对话接口..."
curl -X POST "$BASE_URL/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"你好，请简单介绍一下自己\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq '.'
echo ""

# 2. TTS测试
echo "2. 测试TTS接口..."
curl -X POST "$BASE_URL/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "这是一个TTS测试，语音合成功能正常工作"
  }' | jq '.'
echo ""

# 3. 对话+TTS测试
echo "3. 测试对话+TTS接口..."
curl -X POST "$BASE_URL/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"请用一句话总结人工智能的作用\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq '.'
echo ""

# 4. 流式对话测试
echo "4. 测试流式对话接口..."
curl -X POST "$BASE_URL/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d "{
    \"message\": \"请简单介绍一下机器学习\",
    \"sessionId\": \"$SESSION_ID\"
  }" \
  --no-buffer | head -20
echo ""

# 5. 清除会话测试
echo "5. 测试清除会话接口..."
curl -X DELETE "$BASE_URL/api/chat/session/$SESSION_ID" | jq '.'
echo ""

# 6. 清除缓存测试
echo "6. 测试清除缓存接口..."
curl -X DELETE "$BASE_URL/api/chat/cache" | jq '.'
echo ""

echo "=== 测试完成 ==="

语音功能测试流程

#!/bin/bash
# 语音功能测试脚本（需要准备测试音频文件）

BASE_URL="http://localhost:8080"
SESSION_ID="voice_test_$(date +%s)"
AUDIO_FILE="test_audio.wav"  # 需要准备的测试音频文件

echo "=== 语音功能测试 ==="
echo "测试会话ID: $SESSION_ID"
echo "音频文件: $AUDIO_FILE"
echo ""

# 检查音频文件是否存在
if [ ! -f "$AUDIO_FILE" ]; then
  echo "错误: 音频文件 $AUDIO_FILE 不存在"
  echo "请准备一个测试音频文件（支持格式：wav、mp3、m4a、flac、ogg、aac、wma、amr）"
  exit 1
fi

# 1. 语音对话测试（Base64方式）
echo "1. 测试语音对话接口（Base64方式）..."
AUDIO_BASE64=$(base64 -w 0 "$AUDIO_FILE")
curl -X POST "$BASE_URL/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq '.'
echo ""

# 2. 上传音频文件测试
echo "2. 测试上传音频文件接口..."
curl -X POST "$BASE_URL/api/chat/upload-voice-chat" \
  -F "audioFile=@$AUDIO_FILE" \
  -F "sessionId=$SESSION_ID" \
  -F "description=语音功能测试" | jq '.'
echo ""

# 3. 保存返回的音频
echo "3. 测试保存返回音频..."
curl -X POST "$BASE_URL/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"这是一个音频保存测试\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq -r '.data.audioBase64' | base64 -d > "response_audio_$SESSION_ID.wav"
echo "音频已保存为: response_audio_$SESSION_ID.wav"
echo ""

echo "=== 语音功能测试完成 ==="

快速健康检查脚本

#!/bin/bash
# API健康检查脚本

BASE_URL="http://localhost:8080"

echo "=== API健康检查 ==="

# 检查各个接口的基本可用性
endpoints=(
  "POST /api/chat/sync"
  "POST /api/chat/stream" 
  "POST /api/chat/tts"
  "POST /api/chat/answer-tts"
  "POST /api/chat/voice-chat"
  "POST /api/chat/upload-voice-chat"
  "DELETE /api/chat/cache"
)

for endpoint in "${endpoints[@]}"; do
  method=$(echo $endpoint | cut -d' ' -f1)
  path=$(echo $endpoint | cut -d' ' -f2)
  
  echo -n "检查 $endpoint ... "
  
  if [ "$method" = "POST" ]; then
    response=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$BASE_URL$path" \
      -H "Content-Type: application/json" \
      -d '{"message":"health check"}' 2>/dev/null)
  else
    response=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "$BASE_URL$path" 2>/dev/null)
  fi
  
  if [ "$response" = "200" ] || [ "$response" = "400" ]; then
    echo "✓ 可用 (HTTP $response)"
  else
    echo "✗ 不可用 (HTTP $response)"
  fi
done

echo "=== 健康检查完成 ==="

注意事项

所有接口都支持跨域访问（CORS）
音频文件支持格式：wav、mp3、m4a、flac、ogg、aac、wma、amr
音频文件大小限制：最大50MB，最小1KB
会话ID如果不提供，系统会自动生成
流式接口需要支持SSE（Server-Sent Events）
所有时间戳均为Unix时间戳（毫秒）
TTS相关响应统一包含audioBase64与audioPath两个字段，前者便于直接播放，后者便于文件管理与复用
测试脚本需要安装jq工具用于JSON格式化：sudo apt-get install jq
语音功能测试需要准备相应格式的音频文件
建议在测试环境中运行完整测试流程，避免影响生产数据

32 KiB Raw Permalink Blame History Unescape Escape

聊天对话接口测试文档

接口概述

统一响应格式

响应字段说明

参数详细说明

核心参数配置说明

1. modelId（模型ID）

2. templateId（模板ID）

3. sttConfigId（语音识别配置ID）

4. ttsConfigId（语音合成配置ID）

参数组合建议

注意事项

接口列表

1. 同步对话接口

请求参数

请求示例

测试指令

响应结构

2. 流式对话接口

请求参数

请求示例

测试指令

响应结构

3. 文本转语音接口

请求参数

请求示例

测试指令

响应结构

4. 对话+语音合成接口

请求参数

请求示例

测试指令

响应结构

5. 语音对话接口

请求参数

请求示例

测试指令

响应结构

6. 清除会话接口

路径参数

请求示例

测试指令

响应结构

7. 清除缓存接口

查询参数

请求示例

测试指令

响应结构

8. 上传音频文件进行语音对话

请求参数

请求示例

响应结构

错误码说明

常见错误消息

测试建议

完整测试流程示例

基础功能测试流程

语音功能测试流程

快速健康检查脚本

注意事项

32 KiB

Raw Permalink Blame History