# Round 6 需求开发文档：粤语语言版本 状态：v0.1 决议稿 所属子项目：`02-P-NBL` Round：Round 6 日期：2026-07-02 决策来源：2026-07-02 架构讨论 目标交付版本：`2.2.0` ## 1. 背景 PrivateVoice 已从最初的中文 / English 双语言模型路线，扩展到多语种语言 profile 和模型 profile 架构。当前产品不再以 Mac App Store 为主要发布渠道，后续将以独立站下载和销售为主。 在粤语能力上，公开资料显示 `sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09` 是基于 2024 SenseVoice 多语种模型、使用 21.8k 小时粤语数据 fine-tune 的新版模型，支持中文、粤语、英文、日文、韩文。该模型仍使用 sherpa-onnx / ONNX 路线，适合优先接入现有 PrivateVoice 主版本。 资料依据： - sherpa-onnx SenseVoice 预训练模型文档： - Hugging Face 模型页： - Fun-ASR-Nano 备选路线： - FunASR llama.cpp runtime 备选路线： ## 2. 产品决议 本轮选择： ```text 在当前 PrivateVoice 主版本中新增“粤语”语言选项。 用户选择粤语后，自动下载并激活 SenseVoice Yue 2025-09-09。 不先拆独立 App 包。 开发完成并通过验收后的 App 版本号记录为 2.2.0。 ``` 产品表达： - App 内：新增 `粤语` 语言版本。 - 官网营销：可以建立“PrivateVoice 粤语版”落地页或下载入口。 - 技术交付：仍使用同一个 App、同一个代码主干、同一套模型下载和更新链路。 ## 3. 本轮目标 Round 6 完成后： | 场景 | 期望结果 | |---|---| | 用户打开语言设置 | 可以看到 `粤语` 选项，位置靠近 `中文` | | 用户选择粤语，模型未安装 | App 提示或引导下载粤语离线模型 | | 用户确认下载 | 下载 `SenseVoice Yue 2025-09-09`，显示进度 | | 下载和校验成功 | 自动切换并激活粤语识别 | | 用户再次启动 App | 仍保持粤语语言和粤语模型，除非用户切换 | | 用户切回中文 | 恢复中文默认模型，不删除粤语模型 | | 下载失败 | 不破坏原语言、原模型和用户数据 | | 初始化失败 | 原可用模型继续可用，并给出失败提示 | 核心目标： - 新增粤语语言 profile。 - 新增 SenseVoice Yue 2025-09-09 模型 profile。 - 粤语语言选择触发默认模型下载和激活。 - 粤语识别固定使用 `yue` 语言参数，不默认使用 `auto`。 - 模型列表和 UI 文案避免误导用户以为 Qwen3-ASR / X-ASR 是粤语专项模型。 ## 4. 本轮非目标 明确不做： - 不新建独立 App 包、独立 bundle id 或独立更新通道。 - 不把粤语做成中文下的一个普通模型选项。 - 不把 Qwen3-ASR 作为粤语默认模型。 - 不在粤语页面默认展示 X-ASR。 - 不接入 Fun-ASR-Nano GGUF 作为本轮默认模型。 - 不做多模型准确率正式 benchmark，除非 QA 发现 SenseVoice Yue 不达标。 - 不内置模型到 DMG，默认仍采用按需下载。 - 不承诺本轮完成完整粤语营销页、支付页或授权体系。 ## 5. 功能层次 ```text 粤语语言版本（主功能） ├── 语言选择中新增“粤语” ├── 粤语默认模型自动下载 ├── 粤语模型安装校验 ├── 粤语模型自动激活 ├── 粤语识别后处理 └── 下载/初始化失败保护 官网“粤语版”营销表达（非本轮 App 功能） └── 同一个 App 的独立落地页或下载入口 Fun-ASR-Nano 高准确率模型（后续评估） └── 仅当 SenseVoice Yue 真实 QA 不达标时进入 spike ``` ## 6. 用户故事 ### 6.1 粤语用户首次选择粤语 作为粤语用户，我想在语言设置里直接选择 `粤语`，以便 App 使用适合粤语的离线识别模型，而不是让我在模型列表里猜哪个模型支持粤语。 前置： - App 已安装。 - 用户当前使用中文或其他语言。 - SenseVoice Yue 尚未安装。 流程： 1. 用户进入 `输入` 或 `语言` 设置页。 2. 用户点击 `粤语`。 3. App 显示粤语离线模型下载提示或 inline 下载状态。 4. 用户确认下载，或 App 按产品设定自动下载。 5. 下载进度可见。 6. 下载完成后自动校验。 7. 校验通过后自动激活粤语识别。 期望： - 当前语言变为 `粤语`。 - 当前模型变为 `SenseVoice Yue`。 - Engine ready。 - 用户可以立即用粤语听写。 ### 6.2 粤语用户重启后继续使用粤语 作为已选择粤语的用户，我希望重启 App 后仍然是粤语输入，以便不用每次重新选择。 期望： - 语言选择持久化。 - 模型选择或默认模型解析稳定。 - 若模型文件仍完整，App 直接加载粤语模型。 - 若模型缺失或损坏，显示可恢复的重新下载状态。 ### 6.3 用户从粤语切回中文 作为中粤双语用户，我想从粤语切回中文，以便使用普通中文识别模型。 期望： - 切回中文后默认模型恢复为中文默认模型。 - 粤语模型文件保留。 - 后续再切回粤语时不重复下载。 ### 6.4 下载失败保护 作为用户，我希望粤语模型下载失败时，原来可用的输入能力不被破坏。 期望： - 原语言和原模型继续可用。 - App 不写入损坏模型状态。 - UI 明确显示失败原因或重试入口。 ## 7. 页面和交互要求 ### 7.1 语言选项 语言选择中新增 `粤语`，建议顺序： ```text 自动 / 中文 / 粤语 / English / Français / Deutsch / Español / Italiano / Português / 日本語 / 한국어 ``` 如果后续已拆出独立 `语言` 页签，则 `粤语` 作为独立语言行出现，位置紧跟 `中文`。 ### 7.2 选择粤语时的下载交互 推荐交互： ```text 用户点击“粤语” -> UI 显示：需要下载粤语离线模型，约 226 MB -> 用户确认下载 -> 显示下载进度 -> 下载完成并校验 -> 自动激活 SenseVoice Yue ``` 可接受的轻量版本： ```text 用户点击“粤语” -> App 直接开始下载 -> 语言按钮保持选中 -> 状态显示“正在下载粤语离线模型” ``` 选择哪种交互由实现前最终确认。若无进一步产品确认，默认采用“首次下载前提示确认”，避免用户误触发 200MB+ 下载。 ### 7.3 模型列表展示 当当前语言为 `粤语`： - 默认展示 `SenseVoice Yue`。 - 可展示普通 `SenseVoice` 作为备用，但必须明确不是粤语专项。 - 不默认展示 `Qwen3-ASR`，除非后续验证其对粤语有明确优势。 - 不展示 `X-ASR zh-en 960ms`，避免误导。 示例文案： ```text SenseVoice Yue 粤语专项离线模型，基于 SenseVoice 并使用粤语数据增强。 ``` 状态文案： ```text 未安装 · 约 226 MB 正在下载 42% 已安装 当前 ``` ### 7.4 首启和无模型路径 如果用户首次启动时系统 locale 匹配不到粤语，不自动进入粤语。粤语应由用户手动选择。 如果未来官网“粤语版”下载入口需要默认粤语，可以通过首次启动配置或发行渠道参数实现，但不在本轮做独立包。 ## 8. 研发约束 ### 8.1 LanguageProfile 新增粤语语言 profile： ```text LanguageID: yue-HK 或 yue DisplayName: Cantonese NativeName: 粤语 UILocale: zh DefaultModelID: sensevoice-yue-2025-09-09 SystemMatchers: yue, yue-HK, zh-HK 可考虑但不默认强行匹配 ``` 建议： - 内部 ID 优先使用 `yue-HK`，产品显示为 `粤语`。 - `zh-HK` 是否自动映射到粤语需谨慎。香港用户不一定都希望默认粤语；本轮可先不自动将 `zh-HK` 归为粤语，避免误判。 ### 8.2 ModelProfile 新增模型 profile： ```text ModelID: sensevoice-yue-2025-09-09 DisplayName: SenseVoice Yue BackendKind: sensevoice Tier: default SupportedLanguageIDs: yue-HK RecommendedFor: yue-HK LanguageParam: yue Description: 粤语专项离线模型，基于 SenseVoice 并使用粤语数据增强。 ApproxSize: 约 226 MB 模型文件；下载包大小以实际 HTTP HEAD 为准 InstallDirName: sensevoice-yue-2025-09-09 ``` 下载 URL： ```text https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09.tar.bz2 ``` Required files： ```text model.int8.onnx tokens.txt ``` ### 8.3 Engine 配置 粤语模型加载时： ```text sense_voice.model = model.int8.onnx sense_voice.language = yue sense_voice.use_itn = 按现有 SenseVoice 路线决定 tokens = tokens.txt ``` 关键要求： - 粤语语言 profile 的默认模型必须解析到 SenseVoice Yue。 - 用户选择粤语后，不应继续使用普通中文 SenseVoice。 - 下载成功后应触发 engine reload。 - 初始化失败时，保留原模型可用性。 ### 8.4 后处理 由于 2025-09-09 模型文档明确不支持 punctuation，本轮需要保守后处理： - 中文 / 粤语句末标点补全。 - 常见英文混输空格保护。 - 常见粤语助词不做激进改写。 - 不做同音字大规模纠错。 - 不做繁简强制转换，除非后续有明确产品决策。 ### 8.5 配置和回退 切换粤语时： - 如果下载未完成，不应把不可用模型写成最终可用状态。 - 如果下载成功但初始化失败，应保留原语言/模型，或明确提示用户当前粤语模型不可用。 - 如果用户已经手动选择其他模型，切换语言时应按现有“语言默认模型优先”规则处理，并记录 fallback reason。 ## 9. QA 测试计划 ### 9.1 自动化测试 后端单元测试： - `NormalizeLanguageID("yue-HK")` - `GetLanguageProfile("yue-HK")` - 粤语语言默认模型为 `sensevoice-yue-2025-09-09` - `GetModelProfile("sensevoice-yue-2025-09-09")` - required files 完整时校验通过 - 缺少 `model.int8.onnx` 时校验失败 - 缺少 `tokens.txt` 时校验失败 - 当前语言切换到粤语后，模型 resolver 返回 SenseVoice Yue - 手动模型不支持粤语时，回退到粤语默认模型并保留 fallback reason 前端构建： ```bash cd privatevoice.src/frontend npm run build ``` 后端测试： ```bash cd privatevoice.src go test ./... -count=1 ``` ### 9.2 手工 QA | ID | 场景 | 前置条件 | 期望结果 | |---|---|---|---| | R6-QA-001 | 语言列表显示 | 打开输入/语言设置 | `粤语` 出现在 `中文` 后 | | R6-QA-002 | 选择粤语未安装 | 模型未安装 | 显示下载提示或开始下载 | | R6-QA-003 | 下载进度 | 联网下载 | 进度可见，不能重复触发 | | R6-QA-004 | 下载完成 | 下载成功 | 模型校验通过并自动激活 | | R6-QA-005 | 粤语短句识别 | SenseVoice Yue ready | 粤语短句可识别 | | R6-QA-006 | 粤英混输 | SenseVoice Yue ready | 英文产品名/技术词不被明显破坏 | | R6-QA-007 | 普通话混入 | SenseVoice Yue ready | 普通话片段不导致崩溃或空结果 | | R6-QA-008 | 切回中文 | 两模型均安装 | 中文默认模型可用 | | R6-QA-009 | 再切回粤语 | 粤语模型已安装 | 不重复下载，直接加载 | | R6-QA-010 | 下载失败 | 断网/中断下载 | 原模型可继续使用 | | R6-QA-011 | 坏包/缺文件 | 删除 required file | App 显示未安装或需修复 | | R6-QA-012 | 重启持久化 | 已选择粤语 | 重启后仍为粤语 | | R6-QA-013 | 旧用户配置 | 旧配置无 yue | 正常回退，不崩溃 | | R6-QA-014 | English 回归 | 切到 English | Moonshine/Parakeet 不受影响 | | R6-QA-015 | 中文回归 | 切到中文 | SenseVoice/Qwen3-ASR 不受影响 | ### 9.3 真实语料 QA 每类至少 10 条，优先使用真实香港粤语用户录音： - 日常短句。 - 长句口述。 - 粤英混输。 - 人名、地名、品牌名。 - 常见粤语助词。 - 安静环境。 - 轻噪声环境。 - 普通话混入。 - 静音和无语音。 - 连续切换语言后识别。 ## 10. 验收标准 Round 6 通过条件： - 语言列表新增 `粤语`，位置和文案符合要求。 - 选择粤语后，默认模型解析到 `SenseVoice Yue`。 - 未安装时可下载，下载进度可见。 - 下载完成后 required files 校验通过。 - 模型自动激活，engine ready。 - 粤语短句和粤英混输真实 QA 通过最低可用标准。 - 下载失败、初始化失败不破坏原语言、原模型、词库、历史。 - 中文和 English 现有流程回归通过。 - 不把 Qwen3-ASR / X-ASR 误作为粤语默认模型。 - QA 报告记录版本、build、模型文件、测试设备、测试语料摘要和失败样本。 - 开发完成、QA 通过并进入交付时，App 版本号、`CHANGELOG.md`、release manifest 和安装包命名均记录为 `2.2.0`，build 编号继续使用 `YYYYMMDD.HHMM`。 ## 11. 风险和待确认 | 风险 | 说明 | 处理 | |---|---|---| | 模型许可 | 需要确认模型权重商业使用、归属和 attribution 要求 | 发布前做 license 审核 | | 标点能力 | 2025-09-09 文档写明不支持 punctuation | 做保守后处理，不承诺复杂标点 | | 自动匹配 zh-HK | `zh-HK` 用户不一定都想用粤语 | 本轮先手动选择，不强制自动映射 | | 下载体验 | 200MB+ 模型在弱网下可能失败 | 使用现有断点/重试能力，QA 覆盖弱网 | | 准确率 | 粤语真实口音、噪声、领域词可能不足 | 建立真实语料 QA 和失败样本池 | | 独立营销名 | “粤语版”可能被用户理解为独立 App | 官网文案说明为同一 App 的粤语语言版本 | ## 12. 后续路线 如果 SenseVoice Yue 真实 QA 不达标，再进入技术 spike： ```text Fun-ASR-Nano 2512 GGUF / llama.cpp runtime ``` 评估维度： - 粤语 CER/WER。 - 粤英混输准确率。 - 长句上下文能力。 - 延迟。 - 内存占用。 - 包体大小。 - macOS 签名和分发复杂度。 只有 Fun-ASR-Nano 明显优于 SenseVoice Yue，才考虑作为“高准确率模型”或“Pro 模型”进入产品主链路。