--- 
name: japanese-reading-grader
display_name: 日语朗读作业批改
description: A1/A2/B1(N5/N4/N3)日语朗读音频作业批改，faster-whisper ASR+声学双通道四维AI评测；支持单人/批量批改、纠错反馈、成绩归档；AI预批改，教师人工终审，满分10分。

## 适用场景

学生提交音频文件（MP3/MP4/M4A/WAV）朗读日语文本，教师需要：下载 → 转写 → 评分 → 纠错 → 录入成绩 → 生成班级汇总。

## 作业基础信息

| 项目 | 内容 |
| :--- | :--- |
| **适用对象** | A1/A2/B1 日语学习者（操作标签参考 JLPT N5/N4/N3） |
| **作业形式** | 朗读音频 |
| **总分** | 10 分 |

---

## 工作流程概览

> Step0 标准文本准备 → Step1 音频预处理 → Step1.5 音频质量检测 → Step2 ASR+声学双通道分析 → Step2.5 ASR可靠性检测（置信度分级）→ Step3 四维 AI 评分 → Step4 教师复核 → Step5 成绩录入与反馈生成

---

## Step 0：标准文本准备

1.  **标准答案存储路径**：`./answer/{COURSE_ID}_{ASSIGNMENT_ID}_answer.txt`
2.  **文本格式要求**：
    - 每行 1 个完整句子，无多余空格与换行
    - 重点词汇标注假名
    - 不含多余标点，便于音频转写对齐
3.  **版本校验**：批改前确认标准答案与作业要求一致
4.  **标准答案假名预处理**：
    - 默认本地 `pykakasi`：离线生成假名序列用于辅助分析，确定性强、不上传任何学生数据
    - 生成对照文件：`./answer/{COURSE_ID}_{ASSIGNMENT_ID}_kana_ref.txt`，结构：`原文句子｜规范化假名序列`，用于逐假名对齐比对。**该文件是准确性判定/同音词豁免/清浊·长短音核对的必需输入。**
    - 如未安装 `pykakasi`（降级模式）：**不阻断评分，但强制将该生归入「中置信」分流教师复核**，并在批改日志记录降级原因

---

## Step 1：音频预处理

- 批量转为 wav 格式，统一采样率
- 存放路径：`./audio/{student_id}/`

---

## Step 1.5：音频质量检测

检测项：
- 有效语音比例
- 音量范围
- 背景噪声
- 是否存在多人声音

**异常处理**：音频质量不足 → 不评分 → 请求重新上传。

---

## Step 2：ASR + 声学双通道分析

### 转写工具规格（强制）

- **唯一转写工具**：`faster-whisper`
- **仅允许模型**：`large-v3 fp16` / `medium`；禁用 `small` / `base` / `tiny` 及全部其他规格
- **硬件调度**：有充足 GPU 用 `large-v3 fp16`；无 GPU 自动降级 `medium`
- **固定开启** `word_timestamps=True` 输出词级时间戳

系统同时处理两个分析通道（**双通道校验的基础**）：

| 通道 | 用途 |
| :--- | :--- |
| **A. ASR 文本识别通道** | 辅助判断朗读内容完整性、辅助定位可能存在的发音异常、生成文本对齐候选 |
| **B. 声学分析通道** | 输入原始 wav 音频，分析发音异常候选、音长变化、停顿、语速、节奏；用于发音质量评价及长音/促音/拨音/流畅度分析 |

---

## Step 2.5：ASR 可靠性检测

系统综合判断以下方面：
- 文本匹配程度
- 音频质量
- ASR 置信度
- 对齐情况

输出：**高 / 中 / 低置信度**（用于 Step 4 教师复核的投入分级）。

### 置信度分级判定标准

| 置信度 | 判定条件 |
| :--- | :--- |
| **高** | 文本匹配率 ≥90% 且 ASR 平均置信度 ≥0.8 且 音频信噪比 ≥20dB |
| **中** | 文本匹配率 ≥70% 且 <90%，ASR 平均置信度 ≥0.5 且 <0.8 |
| **低** | 文本匹配率 <70%，或 ASR 平均置信度 <0.5，或音频质量检测不通过 |

> 置信度‑AI评分衔接规则
> 1. **高、中置信度**：四维AI加权分数作为正式预评分，教师仅做异常修正；
> 2. **低置信度**：AI四维加权分数仅作为后台诊断参考，**不计入、不对外展示，最终成绩完全由教师人工给出**。

---

## Step 3：四维 AI 评分

### 评分原则

1.  不影响理解的偏差不扣分
2.  A1/A2 （N5/N4）阶段轻微发音偏差以反馈为主
3.  不确定错误不扣分

> 发音质量维度重要说明
> 发音质量权重占比15%参与AI加权运算，但**该维度输出仅为趋势预估值，不能直接等价于发音错误**；系统不会依靠该维度自动判定促音、长音、清浊错误；所有发音类错误必须经教师试听复核确认后方可扣分。
> 系统可自动化可靠指标仅为：语速、停顿时长、完整性（漏读/多读）、文本对齐。

### 评分前置过滤规则（评分前必须执行）

计算任何维度分数前，先筛除以下情况，**排除出扣分范围**：

1.  **ASR 误识别**——不进入评分计算
    - 人名、地名、汉字词、同音词差异
    - 系统标记为“ASR疑似误识别”的项
2.  **转写存疑**——不进入评分计算
    - 系统置信度 < 0.5 的识别结果
3.  **学习者自然偏差**——反馈但不扣分
    - A1/A2 阶段轻微音长偏差、拨音不到位
    - 语气词添加、促音/长音时长轻微不足

### 音频层评价指标

1.  **发音质量**：清音/浊音区别、拗音准确性、促音闭塞时间、长音持续时间、拨音鼻音实现
2.  **流畅度**：平均语速、停顿次数、非正常停顿长度、重复修正次数
3.  **节奏与韵律**：音节时长比例、长短音节比例、句末语调变化（B1以上参考，不作为 A1/A2 主要扣分依据）

### 能力层级说明（双轨分级）

| 能力层级 | 约对应 JLPT | 朗读评价重点 |
| :--- | :--- | :--- |
| **A1** | N5 | 准确朗读短句，掌握基础假名发音，长音/促音容错空间大 |
| **A2** | N4 | 连贯朗读中等文本，区分常见清浊音，减少基础发音失误 |
| **B1** | N3 | 流畅朗读长文本，发音稳定，具备自然的停顿与语调 |

### AI 自动评分模型（四维加权·主线）

| 评价维度 | 权重 | 数据来源 |
| :--- | :--- | :--- |
| **完整性 (Completeness)** | 35% | 文本 + 音频对齐 |
| **准确性 (Accuracy)** | 30% | ASR + 音频分析 |
| **流畅度 (Fluency)** | 25% | 停顿、语速、重复 |
| **发音质量 (Phoneme Quality)** | 15% | 长音、促音、清浊候选 |

**计算方式**：
> `AI评分 = 完整性×35% + 准确性×30% + 流畅度×25% + 发音质量×15%`，换算为 10 分制。

**权重调整说明**：基于实测，发音质量维度数据源（ASR 置信度 + 时长特征）可靠性有限，暂调低至 15%；差额补给完整性（音频有无语音的判断最为可靠），确保评分基础稳固。

**系统说明**：当前版本发音质量评价基于 ASR 置信度 + 音频时长特征推断，非专业音素模型分析，结果作为辅助参考；教师复核时可重点核对发音相关扣分项。

### 各维度判定规则

| 发现的问题 | 归属维度 | 扣分规则 |
| :--- | :--- | :--- |
| ASR 缺了一段，音频对应位置无语音 | **完整性** | 扣分 |
| ASR 缺了一段，但音频有语音（ASR 未识别出） | - | 不扣分，标记 ASR 误识别 |
| 语速慢 / 停顿多 | **流畅度** | 扣分 |

**促音/长音/清浊错误的边界归属原则**：
- 影响词义（如「もっと」→「もと」、「おばさん」→「おばあさん」）→ **准确性**扣分
- 不影响词义（如时长轻微不足但词义可辨）→ **发音质量**扣分
- 不确定是否影响词义 → 不扣分，仅反馈

1.  **完整性 (Completeness)**
    - **一级依据**：音频时间段是否存在有效语音、是否明显跳过文本区域
    - **二级依据**：ASR 文本对齐结果
    - **规则**：**ASR 显示缺失但音频有对应语音 → 不判定漏读；只有音频无语音 + ASR 缺失才判定漏读。**

2.  **准确性 (Accuracy)**
    - 依据：ASR 文本一致性 + 音频发音特征
    - **禁止仅依据 ASR 错误数量评分。**

3.  **发音质量 (Pronunciation Quality)**
    - 当前阶段：基于 ASR 声学置信度、音频清晰度、长音/促音候选检测，生成辅助评价
    - **注意**：**非专业音素模型分析结果不得作为唯一扣分依据。**

### 促音/长音判定校准约束

促音/长音判定以假名序列 + 双通道比对为准，不依赖声学时长自动扣分。依据内部实测校准，声学时长的参考价值有限，故仅用作候选定位；实际扣分必须经教师复核试听确认后方可计入。可自动化的可靠指标为：语速、停顿时长、完整性（漏读/多读）、文本对齐。
---

## Step 4：教师复核

### 置信度分级驱动复核投入

| AI 置信度 | 教师操作 | 耗时 | 最终成绩 |
| :--- | :--- | :--- | :--- |
| **高** | 快速浏览评分报告，确认无异常后直接录入 | ≤5 秒 | 最终成绩 = AI 评分 |
| **中** | 查看 AI 标记错误列表，播放错误片段（单条≤5s），确认或驳回 AI 判定 | ≤15 秒 | 最终成绩 = AI 评分（教师仅确认扣分项是否合理） |
| **低** | 完整重听音频，人工逐项评分 | 约 2 分钟 | 最终成绩 = 教师评分 |

> **核心原则**：教师不需要对每个学生逐项评分，仅在 AI 置信度低时进行完整人工评价；高/中置信度学生教师只需“确认”即可录入。

### 人工复核调整规则（AI 异常修正）

| 错误类型 | 调整分值 | 单类上限 | 说明 |
| :--- | :--- | :--- | :--- |
| 高置信度发音错误 | -0.5 | -1.5 | 经音频分析确认的促音、长音、清浊错误 |
| 确认漏读/多读 | -0.5 | -1.5 | 音频无对应朗读内容 |
| 明显停顿或中断 | -0.5 | -1.5 | 影响朗读完整性的停顿（超过 3 秒） |

### 调整原则

1.  人工调整仅用于修正 AI 评分异常，不替代 AI 综合评分。
2.  以下情况不得扣分：ASR 误识别、汉字词识别错误、人名/地名识别偏差、同音词转换错误。
3.  只有满足以下条件才扣分：音频证据明确、非 ASR 单独判断、对理解或朗读质量产生影响。
4.  同类错误最多调整 1.5 分。
5.  低置信度且 ASR 异常/音频质量不足 → 不评分，进入人工复核。

> **最终成绩口径**以本页上方「置信度分级驱动复核投入」表格为准：
> - 高/中置信度 → 教师仅确认、不逐项评分，最终成绩 = AI 评分；
> - 低置信度 → 教师综合判断，AI 仅提供诊断参考，最终成绩 = 教师评分。

---

## 分级纠错规则（A1/A2/B1；操作标签参考 N5/N4/N3）

### 篇幅定义

- **短篇**：≤150 字
- **长篇**：＞150 字

### 纠错上限（按水平+篇幅）

| 学生水平 | 短篇 | 长篇 |
| :--- | :--- | :--- |
| **A1** | 2 项 | 3 项 |
| **A2** | 3 项 | 4 项 |
| **B1** | 4 项 | 5 项 |

### 纠错优先级（超过上限时）

1.  影响语义的错误（清浊、长音、促音）
2.  反复出现的高频错误
3.  语调错误

### 通用纠错原则

- 优先纠正影响语义的关键错误
- 同一错误只纠正一次
- 先表扬优点，再提出改进建议
- 不使用警示符号（如 ⚠），语气鼓励为主
- 转写存疑、不确定的地方不纠错，一律不扣分
- **「一句话建议」与「总体评价」不得重复**：一句话建议使用等级表固定标准化结论；总体评价必须基于具体转写内容生成，侧重归因与鼓励，不可复述一句话建议的标准措辞。
- 练习建议数量与纠错输出项数一致，最多不超过纠错上限（如纠错 2 项，练习建议 2 条；不足上限时按实际纠错项数）。

---

## 强制校验流程（防误判）

### 双通道校验机制

系统同时检查：

- **A. 文本通道**：Whisper 转写结果 → 判断漏读/多读/内容偏差
- **B. 音频通道**：原始音频 → 判断发音质量/长音/促音/流畅度

**只有两个通道同时支持时，AI 才生成“高置信度错误”；否则标记「需要教师复核」。**

### 错误判定强制引用表

> `pykakasi` 生成的标准假名序列仅用于文本规范化和音素对齐，不作为独立发音错误判定依据。

| 错误类型 | 必须同时满足的条件 |
| :--- | :--- |
| **促音错误** | ① 标准文本存在「っ」 ② 音频分析**定位**该位置存在促音候选（仅作定位，不作自动扣分依据） ③ 影响节拍结构 ④ ASR 结果作为辅助 |
| **长音错误** | ① 标准文本存在规范长音 ② 音频分析**定位**该位置存在长音候选（仅作定位，不作自动扣分依据） ③ 节拍比例异常 |
| **清浊混淆** | ① 声学特征显示清浊差异 ② 多次稳定出现 ③ 非 ASR 单次错误 |
| **漏读/跳读** | ① ASR 文本与标准文本不一致 ② 音频能量分析确认对应时间段不存在有效语音 |

> **注**：促音/长音仅作**候选定位**，实际扣分须教师复核试听确认后计入（依据校准约束）；不采用时长阈值自动扣分。

**本系统仅为教师辅助预批改工具，不能替代人工终审；所有自动判定的发音错误，教师批量复核后再录入最终成绩。**

---

## 等级划分

| 分数区间 | 水平定位 | 一句话建议 |
| :--- | :--- | :--- |
| 9.0～10.0 | 优秀 | 朗读非常流畅，发音准确，继续保持 |
| 8.0～8.9 | 良好 | 朗读整体不错，有少量细节可优化 |
| 7.0～7.9 | 达标 | 朗读基本达标，建议针对弱项加强练习 |
| 6.0～6.9 | 练习中 | 朗读基本完成，部分发音和流畅度仍需加强 |
| 0～5.9 | 待加强 | 建议从基础发音开始巩固，每日跟读练习 5 分钟 |

初级学习者采用鼓励性反馈原则，但系统保留 0～10 分完整评分范围。

---

## Step 5：成绩录入与反馈生成

### 报告模板
> 说明：下方为AI实际输出给教师‑学生的报告正文模板；花括号`{xxx}`为变量占位符；
> 【发音可疑候选】块由AI自动填充可疑片段；教师试听确认后，将确认的错误迁移至【发音纠错】区块。

学生姓名：{name}
朗读总分：{score}/10分
一句话建议：{level_suggestion}

【总体评价】
{positive_comment}，{constructive_feedback}。{encouragement}

【发音纠错】
原句：{original}学生读法：{student_reading}标准读法：{correct_reading}（{kana}）错误类型：{error_type}
【练习建议】
{suggestion_1}
{suggestion_2}

> **字段定义**：`{kana}` 为标准读法的假名注音，如汉字词「本」标注为「ほん」；`{level}` 为水平定位（优秀/良好/达标/练习中/待加强）；`{level_suggestion}` 为等级表中对应的一句话建议。

### 输出排版规则

- 评分结果、总体评价、朗读诊断、发音纠错、练习建议等所有一级反馈大项，必须单独另起一行
- 发音纠错内部用 1、2 数字序号
- 练习建议用 1、2 数字序号
- 反馈中显示水平定位（优秀/良好/达标/练习中/待加强），不显示 CEFR 等级（A1/A2/B1）标注，也不显示纠错等级说明
- 禁用 emoji、⚠ 等特殊符号
- 评语长度 ≤ 1000 字符（适配平台限制）
- 优先展示优点，再提 1–2 条最关键改进建议
- 后台保存精确分数用于统计归档；反馈中展示总分及水平定位

### 输出文件

- 默认输出到聊天窗口。
- 如教师需要归档，再生成报告文件：`./report/{student_id}.txt`。

---

## 批量处理规则

1.  进度文件：`./progress/{course}_{task}_progress.json`
2.  支持中断后继续执行
3.  分批处理建议 ≤50 人/批
4.  失败音频记录于 `./progress/{course}_{task}_failed.json`，含学生 ID、失败原因（格式不支持/音频损坏/时长过短）、时间戳；不影响整体流程，教师可随时查看失败列表。

---

## 核心原则

1.  **综合评分**：AI 依据完整性、准确性、流畅度和发音质量生成基础评分。
2.  **教师修正**：教师根据课堂目标和特殊情况进行最终调整。
3.  **不确定时不判错**：转写存疑或判定不确定时，优先不判定为错误。
4.  **鼓励为主**：从鼓励出发，微小误差不扣分。
5.  **数据诚实**：发音质量维度数据源（ASR 置信度 + 时长特征）非专业音素模型，不确定时不判错，优先标记“待复核”交由教师确认。

---

## 注意事项

- 评分前确认作业为手动发布分数
- 成绩录入使用 `submission[posted_grade]`
- Whisper 转写仅作参考，必须执行对齐校验
- 严格按 A1/A2/B1 能力层级控制纠错数量
- 评语简洁友好，不使用特殊符号
---