306 lines
7.3 KiB
Markdown
306 lines
7.3 KiB
Markdown
# AI配置测试保存功能说明
|
||
|
||
## 功能概述
|
||
|
||
在 web-admin 的 AI 配置管理页面中，测试接口成功后可以将测试时使用的参数保存到数据库中，包括：
|
||
- API完整URL
|
||
- API Token
|
||
- Bot ID
|
||
- Workflow ID
|
||
- 自定义请求头
|
||
- 自定义请求参数
|
||
- 是否支持流式输出
|
||
|
||
## 使用流程
|
||
|
||
### 1. 打开测试对话框
|
||
在 AI 配置列表中，点击某个配置的"测试"按钮，打开测试对话框。
|
||
|
||
### 2. 配置测试参数
|
||
测试对话框会自动填充当前配置的参数：
|
||
- **请求URL**: 从配置的 `apiBaseUrl` 字段获取
|
||
- **请求头**: 自动构建，包含 `Authorization` 和 `Content-Type`
|
||
- **请求体**: 自动构建，包含 `bot_id`、`user_id`、`stream`、`additional_messages` 等
|
||
|
||
### 3. 修改测试参数（可选）
|
||
您可以根据需要修改：
|
||
- 请求URL
|
||
- 请求头中的参数
|
||
- 请求体中的参数
|
||
- 测试消息内容
|
||
- 是否启用流式响应
|
||
|
||
### 4. 发送测试请求
|
||
点击"发送测试请求"或"发送流式测试"按钮，系统会向配置的API发送请求。
|
||
|
||
### 5. 查看响应结果
|
||
右侧会显示：
|
||
- 状态码
|
||
- 响应头
|
||
- 响应体
|
||
|
||
### 6. 保存测试配置
|
||
如果测试成功（状态码为200），会显示"保存测试配置"按钮。点击该按钮，系统会：
|
||
|
||
#### 6.1 解析请求头
|
||
- 提取 `Authorization` 头中的 Token（移除 "Bearer " 前缀）
|
||
- 将其他自定义请求头保存到 `customHeaders` 字段（JSON格式）
|
||
|
||
#### 6.2 解析请求体
|
||
- 提取 `bot_id` 保存到 `botId` 字段
|
||
- 提取 `workflow_id` 保存到 `workflowId` 字段
|
||
- 提取 `stream` 保存到 `supportStream` 字段
|
||
- 将其他自定义参数保存到 `customParams` 字段（JSON格式）
|
||
|
||
#### 6.3 更新配置
|
||
调用后端接口 `/aiConfig/updateFromTest`，更新配置信息。
|
||
|
||
## 后端接口
|
||
|
||
### 接口地址
|
||
```
|
||
PUT /aiConfig/updateFromTest
|
||
```
|
||
|
||
### 请求参数
|
||
```json
|
||
{
|
||
"id": "配置ID",
|
||
"apiBaseUrl": "完整的API URL",
|
||
"apiToken": "API访问令牌",
|
||
"botId": "Bot ID（Coze专用）",
|
||
"workflowId": "Workflow ID（Coze专用）",
|
||
"customHeaders": "自定义请求头（JSON字符串）",
|
||
"customParams": "自定义参数（JSON字符串）",
|
||
"supportStream": 1
|
||
}
|
||
```
|
||
|
||
### 响应示例
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新成功",
|
||
"data": {
|
||
"id": "1234567890",
|
||
"configName": "测试配置",
|
||
"apiBaseUrl": "https://api.coze.cn/v3/chat",
|
||
"apiToken": "pat_xxx",
|
||
"botId": "bot_123",
|
||
"workflowId": "workflow_456",
|
||
"customHeaders": "{\"X-Custom-Header\":\"value\"}",
|
||
"customParams": "{\"custom_param\":\"value\"}",
|
||
"supportStream": 1,
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
## 参数提取规则
|
||
|
||
### 1. API Token提取
|
||
从请求头的 `Authorization` 字段中提取：
|
||
```json
|
||
{
|
||
"Authorization": "Bearer pat_xxx"
|
||
}
|
||
```
|
||
提取结果：`apiToken = "pat_xxx"`
|
||
|
||
### 2. Bot ID提取
|
||
从请求体的 `bot_id` 字段中提取：
|
||
```json
|
||
{
|
||
"bot_id": "bot_123"
|
||
}
|
||
```
|
||
提取结果：`botId = "bot_123"`
|
||
|
||
### 3. Workflow ID提取
|
||
从请求体的 `workflow_id` 字段中提取：
|
||
```json
|
||
{
|
||
"workflow_id": "workflow_456"
|
||
}
|
||
```
|
||
提取结果：`workflowId = "workflow_456"`
|
||
|
||
### 4. 流式支持提取
|
||
从请求体的 `stream` 字段中提取：
|
||
```json
|
||
{
|
||
"stream": true
|
||
}
|
||
```
|
||
提取结果：`supportStream = 1`
|
||
|
||
### 5. 自定义请求头
|
||
移除 `Authorization` 和 `Content-Type` 后的其他请求头：
|
||
```json
|
||
{
|
||
"X-Custom-Header": "value",
|
||
"X-Another-Header": "value2"
|
||
}
|
||
```
|
||
保存为JSON字符串到 `customHeaders` 字段
|
||
|
||
### 6. 自定义参数
|
||
移除 `bot_id`、`workflow_id`、`stream`、`user_id`、`additional_messages` 后的其他参数：
|
||
```json
|
||
{
|
||
"custom_param": "value",
|
||
"another_param": "value2"
|
||
}
|
||
```
|
||
保存为JSON字符串到 `customParams` 字段
|
||
|
||
## 使用示例
|
||
|
||
### 示例1：标准Coze配置
|
||
|
||
**测试前配置**:
|
||
```json
|
||
{
|
||
"apiBaseUrl": "https://api.coze.cn",
|
||
"apiToken": "old_token",
|
||
"botId": "old_bot_id"
|
||
}
|
||
```
|
||
|
||
**测试请求**:
|
||
- URL: `https://api.coze.cn/v3/chat`
|
||
- 请求头:
|
||
```json
|
||
{
|
||
"Authorization": "Bearer new_token",
|
||
"Content-Type": "application/json"
|
||
}
|
||
```
|
||
- 请求体:
|
||
```json
|
||
{
|
||
"bot_id": "new_bot_id",
|
||
"user_id": "test_user",
|
||
"stream": false,
|
||
"additional_messages": [...]
|
||
}
|
||
```
|
||
|
||
**保存后配置**:
|
||
```json
|
||
{
|
||
"apiBaseUrl": "https://api.coze.cn/v3/chat",
|
||
"apiToken": "new_token",
|
||
"botId": "new_bot_id",
|
||
"supportStream": 0,
|
||
"customHeaders": "",
|
||
"customParams": ""
|
||
}
|
||
```
|
||
|
||
### 示例2：带自定义参数的配置
|
||
|
||
**测试请求**:
|
||
- URL: `https://api.coze.cn/v3/chat`
|
||
- 请求头:
|
||
```json
|
||
{
|
||
"Authorization": "Bearer token_123",
|
||
"Content-Type": "application/json",
|
||
"X-Custom-Header": "custom_value"
|
||
}
|
||
```
|
||
- 请求体:
|
||
```json
|
||
{
|
||
"bot_id": "bot_456",
|
||
"workflow_id": "workflow_789",
|
||
"stream": true,
|
||
"user_id": "test_user",
|
||
"additional_messages": [...],
|
||
"custom_param": "param_value"
|
||
}
|
||
```
|
||
|
||
**保存后配置**:
|
||
```json
|
||
{
|
||
"apiBaseUrl": "https://api.coze.cn/v3/chat",
|
||
"apiToken": "token_123",
|
||
"botId": "bot_456",
|
||
"workflowId": "workflow_789",
|
||
"supportStream": 1,
|
||
"customHeaders": "{\"X-Custom-Header\":\"custom_value\"}",
|
||
"customParams": "{\"custom_param\":\"param_value\"}"
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **测试成功才能保存**: 只有当测试请求返回状态码200时，才会显示"保存测试配置"按钮
|
||
2. **JSON格式验证**: 保存前会验证请求头和请求体是否为有效的JSON格式
|
||
3. **自动刷新**: 保存成功后会自动刷新配置列表
|
||
4. **字段覆盖**: 保存时只更新提供的字段，未提供的字段保持原值
|
||
5. **Token安全**: API Token会完整保存到数据库，请确保数据库安全
|
||
|
||
## 错误处理
|
||
|
||
### 1. 请求头格式错误
|
||
```
|
||
错误信息：请求头格式错误，无法解析
|
||
原因：请求头不是有效的JSON格式
|
||
解决：检查请求头的JSON格式是否正确
|
||
```
|
||
|
||
### 2. 请求体格式错误
|
||
```
|
||
错误信息：请求体格式错误，无法解析
|
||
原因：请求体不是有效的JSON格式
|
||
解决：检查请求体的JSON格式是否正确
|
||
```
|
||
|
||
### 3. 配置不存在
|
||
```
|
||
错误信息：测试配置不存在
|
||
原因：testConfig为空
|
||
解决：重新打开测试对话框
|
||
```
|
||
|
||
### 4. 保存失败
|
||
```
|
||
错误信息：保存失败: [具体错误信息]
|
||
原因：后端接口调用失败
|
||
解决：检查网络连接和后端服务状态
|
||
```
|
||
|
||
## 开发说明
|
||
|
||
### 前端文件
|
||
- **页面**: `web-admin/src/views/aiconfig/AiConfigList.vue`
|
||
- **API**: `web-admin/src/api/aiconfig.ts`
|
||
- **类型**: `web-admin/src/types/aiconfig.ts`
|
||
|
||
### 后端文件
|
||
- **Controller**: `backend-single/src/main/java/com/emotion/controller/AiConfigController.java`
|
||
- **Service**: `backend-single/src/main/java/com/emotion/service/AiConfigService.java`
|
||
- **ServiceImpl**: `backend-single/src/main/java/com/emotion/service/impl/AiConfigServiceImpl.java`
|
||
- **Request DTO**: `backend-single/src/main/java/com/emotion/dto/request/aiconfig/AiConfigTestUpdateRequest.java`
|
||
|
||
### 数据库字段
|
||
- `api_base_url`: API完整URL
|
||
- `api_token`: API访问令牌
|
||
- `bot_id`: Bot ID
|
||
- `workflow_id`: Workflow ID
|
||
- `custom_headers`: 自定义请求头（JSON字符串）
|
||
- `custom_params`: 自定义参数（JSON字符串）
|
||
- `support_stream`: 是否支持流式输出（0-不支持，1-支持）
|
||
|
||
## 更新日志
|
||
|
||
### 2025-12-22
|
||
- 新增测试后保存配置功能
|
||
- 新增 `AiConfigTestUpdateRequest` DTO
|
||
- 新增 `updateFromTestRequest` 服务方法
|
||
- 新增 `/aiConfig/updateFromTest` 接口
|
||
- 前端新增"保存测试配置"按钮和处理逻辑
|