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 预训练模型文档：https://k2-fsa.github.io/sherpa/onnx/sense-voice/pretrained.html
• Hugging Face 模型页：https://huggingface.co/csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09
• Fun-ASR-Nano 备选路线：https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512
• FunASR llama.cpp runtime 备选路线：https://www.funasr.com/en/llama-cpp.html

2. 产品决议

本轮选择：

在当前 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. 功能层次

粤语语言版本（主功能）
├── 语言选择中新增“粤语”
├── 粤语默认模型自动下载
├── 粤语模型安装校验
├── 粤语模型自动激活
├── 粤语识别后处理
└── 下载/初始化失败保护

官网“粤语版”营销表达（非本轮 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 语言选项

语言选择中新增 粤语，建议顺序：

自动 / 中文 / 粤语 / English / Français / Deutsch / Español / Italiano / Português / 日本語 / 한국어

如果后续已拆出独立 语言 页签，则 粤语 作为独立语言行出现，位置紧跟 中文。

7.2 选择粤语时的下载交互

推荐交互：

用户点击“粤语”
-> UI 显示：需要下载粤语离线模型，约 226 MB
-> 用户确认下载
-> 显示下载进度
-> 下载完成并校验
-> 自动激活 SenseVoice Yue

可接受的轻量版本：

用户点击“粤语”
-> App 直接开始下载
-> 语言按钮保持选中
-> 状态显示“正在下载粤语离线模型”

选择哪种交互由实现前最终确认。若无进一步产品确认，默认采用“首次下载前提示确认”，避免用户误触发 200MB+ 下载。

7.3 模型列表展示

当当前语言为 粤语：

• 默认展示 SenseVoice Yue。
• 可展示普通 SenseVoice 作为备用，但必须明确不是粤语专项。
• 不默认展示 Qwen3-ASR，除非后续验证其对粤语有明确优势。
• 不展示 X-ASR zh-en 960ms，避免误导。

示例文案：

SenseVoice Yue
粤语专项离线模型，基于 SenseVoice 并使用粤语数据增强。

状态文案：

未安装 · 约 226 MB
正在下载 42%
已安装
当前

7.4 首启和无模型路径

如果用户首次启动时系统 locale 匹配不到粤语，不自动进入粤语。粤语应由用户手动选择。

如果未来官网“粤语版”下载入口需要默认粤语，可以通过首次启动配置或发行渠道参数实现，但不在本轮做独立包。

8. 研发约束

8.1 LanguageProfile

新增粤语语言 profile：

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：

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：

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：

model.int8.onnx
tokens.txt

8.3 Engine 配置

粤语模型加载时：

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

前端构建：

cd privatevoice.src/frontend
npm run build

后端测试：

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：

Fun-ASR-Nano 2512 GGUF / llama.cpp runtime

评估维度：

• 粤语 CER/WER。
• 粤英混输准确率。
• 长句上下文能力。
• 延迟。
• 内存占用。
• 包体大小。
• macOS 签名和分发复杂度。

只有 Fun-ASR-Nano 明显优于 SenseVoice Yue，才考虑作为“高准确率模型”或“Pro 模型”进入产品主链路。