436 lines
11 KiB
Markdown
436 lines
11 KiB
Markdown
# 语音评测模块接口文档
|
||
|
||
## 概述
|
||
语音评测模块用于语文课程的语音跟读和自动评测功能，支持学生录制语音、上传音频、自动评测并记录评测结果。
|
||
|
||
## 数据库表
|
||
|
||
### voice_evaluation（语音评测表）
|
||
```sql
|
||
CREATE TABLE `voice_evaluation` (
|
||
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '评测ID',
|
||
`student_id` bigint NOT NULL COMMENT '学员ID',
|
||
`course_id` bigint DEFAULT NULL COMMENT '课程ID',
|
||
`content` text NOT NULL COMMENT '评测内容（课文或文字）',
|
||
`audio_path` varchar(500) DEFAULT NULL COMMENT '音频文件路径',
|
||
`score` decimal(10,2) DEFAULT NULL COMMENT '评分（总分，0-100）',
|
||
`accuracy` decimal(10,2) DEFAULT NULL COMMENT '准确度（0-100）',
|
||
`fluency` decimal(10,2) DEFAULT NULL COMMENT '流畅度（0-100）',
|
||
`completeness` decimal(10,2) DEFAULT NULL COMMENT '完整度（0-100）',
|
||
`pronunciation` decimal(10,2) DEFAULT NULL COMMENT '发音得分（0-100）',
|
||
`result_detail` text DEFAULT NULL COMMENT '评测详情（JSON格式）',
|
||
`evaluation_time` datetime DEFAULT NULL COMMENT '评测时间',
|
||
`create_by` varchar(64) DEFAULT '' COMMENT '创建者',
|
||
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
|
||
`update_by` varchar(64) DEFAULT '' COMMENT '更新者',
|
||
`update_time` datetime DEFAULT NULL COMMENT '更新时间',
|
||
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
|
||
PRIMARY KEY (`id`),
|
||
KEY `idx_student_id` (`student_id`),
|
||
KEY `idx_course_id` (`course_id`),
|
||
KEY `idx_evaluation_time` (`evaluation_time`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='语音评测表';
|
||
```
|
||
|
||
---
|
||
|
||
## 后端接口
|
||
|
||
### 1. 上传音频并进行评测（App端）
|
||
|
||
**接口URL**: `/study/voiceEvaluation/uploadAndEvaluate`
|
||
**请求方式**: `POST`
|
||
**权限要求**: 学员登录（无需特殊权限）
|
||
|
||
**请求参数**:
|
||
- `file` (MultipartFile, 必填): 音频文件（支持mp3、wav等格式）
|
||
- `content` (String, 必填): 评测内容（课文或文字）
|
||
- `courseId` (Long, 可选): 课程ID
|
||
- `language` (String, 可选): 语言类型，默认"zh-CN"（中文）
|
||
|
||
**请求示例**:
|
||
```javascript
|
||
// UniApp端使用uni.uploadFile
|
||
uni.uploadFile({
|
||
url: baseURL + '/study/voiceEvaluation/uploadAndEvaluate',
|
||
filePath: recordPath,
|
||
name: 'file',
|
||
formData: {
|
||
content: '评测内容',
|
||
courseId: courseId || '',
|
||
language: 'zh-CN'
|
||
},
|
||
header: {
|
||
'Authorization': 'Bearer ' + token
|
||
}
|
||
})
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "评测完成",
|
||
"data": {
|
||
"evaluation": {
|
||
"id": 1,
|
||
"studentId": 100,
|
||
"courseId": 1,
|
||
"content": "评测内容",
|
||
"audioPath": "/upload/voice/xxx.mp3",
|
||
"score": 85.5,
|
||
"accuracy": 90.0,
|
||
"fluency": 85.0,
|
||
"completeness": 88.0,
|
||
"pronunciation": 87.0,
|
||
"resultDetail": "{\"words\":[...]}",
|
||
"evaluationTime": "2025-01-15 10:30:00"
|
||
},
|
||
"audioUrl": "http://1.15.149.240:8081/upload/voice/xxx.mp3"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取我的语音评测记录（App端）
|
||
|
||
**接口URL**: `/study/voiceEvaluation/my-records`
|
||
**请求方式**: `GET`
|
||
**权限要求**: 学员登录
|
||
|
||
**请求参数**:
|
||
- `courseId` (Long, 可选): 课程ID，不传则查询所有记录
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"studentId": 100,
|
||
"studentName": "张三",
|
||
"courseId": 1,
|
||
"courseName": "语文课程",
|
||
"content": "评测内容",
|
||
"audioPath": "/upload/voice/xxx.mp3",
|
||
"score": 85.5,
|
||
"accuracy": 90.0,
|
||
"fluency": 85.0,
|
||
"completeness": 88.0,
|
||
"pronunciation": 87.0,
|
||
"evaluationTime": "2025-01-15 10:30:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 查询语音评测列表（管理后台）
|
||
|
||
**接口URL**: `/study/voiceEvaluation/list`
|
||
**请求方式**: `GET`
|
||
**权限要求**: `study:voiceEvaluation:list`
|
||
|
||
**请求参数**:
|
||
- `pageNum` (Integer): 页码
|
||
- `pageSize` (Integer): 每页数量
|
||
- `studentName` (String, 可选): 学员姓名
|
||
- `courseName` (String, 可选): 课程名称
|
||
- `beginTime` (String, 可选): 开始时间（格式：yyyy-MM-dd）
|
||
- `endTime` (String, 可选): 结束时间（格式：yyyy-MM-dd）
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"rows": [
|
||
{
|
||
"id": 1,
|
||
"studentId": 100,
|
||
"studentName": "张三",
|
||
"courseId": 1,
|
||
"courseName": "语文课程",
|
||
"content": "评测内容",
|
||
"score": 85.5,
|
||
"accuracy": 90.0,
|
||
"fluency": 85.0,
|
||
"completeness": 88.0,
|
||
"pronunciation": 87.0,
|
||
"evaluationTime": "2025-01-15 10:30:00"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取语音评测详情
|
||
|
||
**接口URL**: `/study/voiceEvaluation/{id}`
|
||
**请求方式**: `GET`
|
||
**权限要求**: `study:voiceEvaluation:query`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"studentId": 100,
|
||
"studentName": "张三",
|
||
"courseId": 1,
|
||
"courseName": "语文课程",
|
||
"content": "评测内容",
|
||
"audioPath": "/upload/voice/xxx.mp3",
|
||
"score": 85.5,
|
||
"accuracy": 90.0,
|
||
"fluency": 85.0,
|
||
"completeness": 88.0,
|
||
"pronunciation": 87.0,
|
||
"resultDetail": "{\"words\":[...],\"sentence\":{...}}",
|
||
"evaluationTime": "2025-01-15 10:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 删除语音评测
|
||
|
||
**接口URL**: `/study/voiceEvaluation/{ids}`
|
||
**请求方式**: `DELETE`
|
||
**权限要求**: `study:voiceEvaluation:remove`
|
||
|
||
**请求参数**:
|
||
- `ids` (Long[]): 评测ID数组
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 导出语音评测列表
|
||
|
||
**接口URL**: `/study/voiceEvaluation/export`
|
||
**请求方式**: `POST`
|
||
**权限要求**: `study:voiceEvaluation:export`
|
||
|
||
**请求参数**: 同查询列表接口
|
||
|
||
**响应**: Excel文件下载
|
||
|
||
---
|
||
|
||
## 第三方语音服务集成
|
||
|
||
### 语音服务接口
|
||
|
||
系统提供了 `IVoiceEvaluationService` 接口，用于集成第三方语音评测服务。
|
||
|
||
**接口定义**:
|
||
```java
|
||
public interface IVoiceEvaluationService {
|
||
/**
|
||
* 语音评测
|
||
* @param audioPath 音频文件路径
|
||
* @param content 评测内容
|
||
* @param language 语言类型
|
||
* @return 评测结果
|
||
*/
|
||
Map<String, Object> evaluateVoice(String audioPath, String content, String language);
|
||
|
||
/**
|
||
* 检查服务是否可用
|
||
* @return true-可用，false-不可用
|
||
*/
|
||
boolean isAvailable();
|
||
}
|
||
```
|
||
|
||
### 支持的第三方服务商
|
||
|
||
1. **科大讯飞语音评测**
|
||
- 官网：https://www.xfyun.cn/
|
||
- 价格：中等
|
||
- 准确率：高
|
||
- 推荐指数：⭐⭐⭐⭐⭐
|
||
|
||
2. **百度语音识别**
|
||
- 官网：https://ai.baidu.com/tech/speech/asr
|
||
- 价格：较低
|
||
- 准确率：中等
|
||
- 推荐指数：⭐⭐⭐⭐
|
||
|
||
3. **腾讯云语音识别**
|
||
- 官网：https://cloud.tencent.com/product/asr
|
||
- 价格：中等
|
||
- 准确率：高
|
||
- 推荐指数：⭐⭐⭐⭐
|
||
|
||
4. **阿里云语音识别**
|
||
- 官网：https://www.aliyun.com/product/nls
|
||
- 价格：中等
|
||
- 准确率：高
|
||
- 推荐指数：⭐⭐⭐⭐
|
||
|
||
### 集成步骤
|
||
|
||
1. **选择服务商**：根据实际需求选择第三方服务商
|
||
2. **获取API密钥**：在服务商平台注册并获取API密钥
|
||
3. **实现服务类**：实现 `IVoiceEvaluationService` 接口
|
||
4. **配置服务**：在配置文件中配置API密钥等信息
|
||
5. **替换实现**：将 `VoiceEvaluationServiceImpl` 中的模拟实现替换为真实API调用
|
||
|
||
### 示例代码（科大讯飞）
|
||
|
||
```java
|
||
@Service
|
||
public class XfyunVoiceEvaluationServiceImpl implements IVoiceEvaluationService {
|
||
|
||
@Value("${voice.xfyun.appid}")
|
||
private String appId;
|
||
|
||
@Value("${voice.xfyun.apikey}")
|
||
private String apiKey;
|
||
|
||
@Value("${voice.xfyun.apisecret}")
|
||
private String apiSecret;
|
||
|
||
@Override
|
||
public Map<String, Object> evaluateVoice(String audioPath, String content, String language) {
|
||
// 1. 读取音频文件
|
||
File audioFile = new File(audioPath);
|
||
byte[] audioData = FileUtils.readFileToByteArray(audioFile);
|
||
|
||
// 2. 调用科大讯飞API
|
||
XfyunClient client = new XfyunClient(appId, apiKey, apiSecret);
|
||
EvaluationResult result = client.evaluate(audioData, content, language);
|
||
|
||
// 3. 解析返回结果
|
||
Map<String, Object> evaluationResult = new HashMap<>();
|
||
evaluationResult.put("score", result.getTotalScore());
|
||
evaluationResult.put("accuracy", result.getAccuracy());
|
||
evaluationResult.put("fluency", result.getFluency());
|
||
evaluationResult.put("completeness", result.getCompleteness());
|
||
evaluationResult.put("pronunciation", result.getPronunciation());
|
||
evaluationResult.put("resultDetail", result.getDetailJson());
|
||
|
||
return evaluationResult;
|
||
}
|
||
|
||
@Override
|
||
public boolean isAvailable() {
|
||
// 检查API密钥是否配置
|
||
return StringUtils.isNotEmpty(appId) &&
|
||
StringUtils.isNotEmpty(apiKey) &&
|
||
StringUtils.isNotEmpty(apiSecret);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 前端页面
|
||
|
||
### UniApp端
|
||
|
||
**页面路径**: `frontend-uniapp/src/pages/voice/evaluation.vue`
|
||
|
||
**功能**:
|
||
- 设置评测内容
|
||
- 语音录制（开始/停止）
|
||
- 播放录音
|
||
- 上传音频并评测
|
||
- 查看评测结果
|
||
- 查看历史记录
|
||
|
||
**使用方式**:
|
||
```javascript
|
||
// 跳转到语音评测页面
|
||
uni.navigateTo({
|
||
url: '/pages/voice/evaluation?courseId=1&courseName=语文课程&content=评测内容'
|
||
})
|
||
```
|
||
|
||
### 管理后台
|
||
|
||
**页面路径**: `ruoyi-ui/src/views/study/voiceEvaluation/index.vue`
|
||
|
||
**功能**:
|
||
- 查询语音评测列表
|
||
- 查看评测详情
|
||
- 删除评测记录
|
||
- 导出评测数据
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
### 1. 数据库初始化
|
||
|
||
执行SQL脚本创建表：
|
||
```bash
|
||
mysql -u root -p ry_study < log/Sql/voice_evaluation_table.sql
|
||
```
|
||
|
||
### 2. 配置第三方服务（可选）
|
||
|
||
如果需要使用真实的语音评测服务，需要：
|
||
|
||
1. 在 `application.yml` 中配置API密钥：
|
||
```yaml
|
||
voice:
|
||
xfyun:
|
||
appid: your_app_id
|
||
apikey: your_api_key
|
||
apisecret: your_api_secret
|
||
```
|
||
|
||
2. 实现 `IVoiceEvaluationService` 接口
|
||
3. 替换 `VoiceEvaluationServiceImpl` 中的实现
|
||
|
||
### 3. 测试
|
||
|
||
1. **UniApp端测试**：
|
||
- 打开语音评测页面
|
||
- 输入评测内容
|
||
- 录制语音
|
||
- 上传并评测
|
||
- 查看评测结果
|
||
|
||
2. **管理后台测试**：
|
||
- 登录管理后台
|
||
- 进入"学习系统" -> "语音评测"
|
||
- 查看评测列表
|
||
- 查看评测详情
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **音频格式**：支持mp3、wav等常见音频格式
|
||
2. **文件大小**：建议音频文件不超过10MB
|
||
3. **录音时长**：建议录音时长不超过60秒
|
||
4. **第三方服务**：当前使用模拟实现，实际使用时需要接入真实的第三方服务
|
||
5. **权限控制**：教师只能查看自己班级学员的评测记录（通过数据权限控制）
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
- 2025-01-XX：创建语音评测模块，实现基础功能
|
||
- 待完善：集成第三方语音评测服务
|
||
|