xiaozhang/guoyu

Fork 0

xiao12feng8 a0fb622e7f 重新编译配置

2025-12-06 20:11:36 +08:00

11 KiB

Raw Blame History

语音评测模块接口文档

概述

语音评测模块用于语文课程的语音跟读和自动评测功能，支持学生录制语音、上传音频、自动评测并记录评测结果。

数据库表

voice_evaluation（语音评测表）

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"（中文）

请求示例:

// 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
    }
})

响应示例:

{
    "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，不传则查询所有记录

响应示例:

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

响应示例:

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

响应示例:

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

响应示例:

{
    "code": 200,
    "msg": "操作成功"
}

6. 导出语音评测列表

接口URL: /study/voiceEvaluation/export
请求方式: POST
权限要求: study:voiceEvaluation:export

请求参数: 同查询列表接口

响应: Excel文件下载

第三方语音服务集成

语音服务接口

系统提供了 IVoiceEvaluationService 接口，用于集成第三方语音评测服务。

接口定义:

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();
}

支持的第三方服务商

科大讯飞语音评测
- 官网：https://www.xfyun.cn/
- 价格：中等
- 准确率：高
- 推荐指数：⭐⭐⭐⭐⭐
百度语音识别
- 官网：https://ai.baidu.com/tech/speech/asr
- 价格：较低
- 准确率：中等
- 推荐指数：⭐⭐⭐⭐
腾讯云语音识别
- 官网：https://cloud.tencent.com/product/asr
- 价格：中等
- 准确率：高
- 推荐指数：⭐⭐⭐⭐
阿里云语音识别
- 官网：https://www.aliyun.com/product/nls
- 价格：中等
- 准确率：高
- 推荐指数：⭐⭐⭐⭐

集成步骤

选择服务商：根据实际需求选择第三方服务商
获取API密钥：在服务商平台注册并获取API密钥
实现服务类：实现 IVoiceEvaluationService 接口
配置服务：在配置文件中配置API密钥等信息
替换实现：将 VoiceEvaluationServiceImpl 中的模拟实现替换为真实API调用

示例代码（科大讯飞）

@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

功能:

设置评测内容
语音录制（开始/停止）
播放录音
上传音频并评测
查看评测结果
查看历史记录

使用方式:

// 跳转到语音评测页面
uni.navigateTo({
    url: '/pages/voice/evaluation?courseId=1&courseName=语文课程&content=评测内容'
})

管理后台

页面路径: ruoyi-ui/src/views/study/voiceEvaluation/index.vue

功能:

查询语音评测列表
查看评测详情
删除评测记录
导出评测数据

使用说明

1. 数据库初始化

执行SQL脚本创建表：

mysql -u root -p ry_study < log/Sql/voice_evaluation_table.sql

2. 配置第三方服务（可选）

如果需要使用真实的语音评测服务，需要：

在 application.yml 中配置API密钥：

voice:
  xfyun:
    appid: your_app_id
    apikey: your_api_key
    apisecret: your_api_secret

实现 IVoiceEvaluationService 接口
替换 VoiceEvaluationServiceImpl 中的实现

3. 测试

UniApp端测试：
- 打开语音评测页面
- 输入评测内容
- 录制语音
- 上传并评测
- 查看评测结果
管理后台测试：
- 登录管理后台
- 进入"学习系统" -> "语音评测"
- 查看评测列表
- 查看评测详情

注意事项

音频格式：支持mp3、wav等常见音频格式
文件大小：建议音频文件不超过10MB
录音时长：建议录音时长不超过60秒
第三方服务：当前使用模拟实现，实际使用时需要接入真实的第三方服务
权限控制：教师只能查看自己班级学员的评测记录（通过数据权限控制）

更新日志

2025-01-XX：创建语音评测模块，实现基础功能
待完善：集成第三方语音评测服务

11 KiB Raw Blame History Unescape Escape

语音评测模块接口文档

概述

数据库表

voice_evaluation（语音评测表）

后端接口

1. 上传音频并进行评测（App端）

2. 获取我的语音评测记录（App端）

3. 查询语音评测列表（管理后台）

4. 获取语音评测详情

5. 删除语音评测

6. 导出语音评测列表

第三方语音服务集成

语音服务接口

支持的第三方服务商

集成步骤

示例代码（科大讯飞）

前端页面

UniApp端

管理后台

使用说明

1. 数据库初始化

2. 配置第三方服务（可选）

3. 测试

注意事项

更新日志

11 KiB

Raw Blame History