用途与实际影响
这项功能怎样使用
为什么需要它
源码、运行依赖与模型文件是三种东西；只保留其中一份，换机或断网时可能到最后才发现根本跑不起来。先查缺的层，再恢复。
举个实际例子
比如我问“新电脑暂时没网，怎样把 ChineseASR 恢复到能跑严格转写？”系统会先核对预存的依赖锁、离线轮包与校验清单，重建 Windows 虚拟环境；再单独确认 Qwen 模型缓存与回执。若还需要 FireRed，就继续检查 WSL（Windows 的 Linux 子系统） 中的源码、运行时、模型回执和存储容量。最后必须跑默认 strict 冒烟；重要证据路线还要另跑 FireRed + Qwen 冒烟并人工核听。
最后我会得到什么
交回这台机器哪些识别路线真的能运行、缺哪些依赖或模型文件、恢复后是否通过小段真实声音检查。想换默认模型时还会交回同材料比较与可回退的配置决定；只下载完成不能算可用。
正常时
运行依赖、对应模型文件和一次实际试跑都通过后，才把这条路线标为可用；重要录音的质量仍需单独回听。
发现问题时
只修好一部分时保留已经核对的结果，指出缺的层；修额外路线不会顺手改掉日常路线。
入口不可用或证据不足时
离线安装材料、模型文件或必要系统环境缺失时，只停受影响路线，不猜版本或找相似模型顶替。
从哪里开始
安装、升级、换机或模型加载失败时，要求核对依赖和固定模型。
需要准备什么
- 遇到的安装或加载故障
- 这次要使用的识别用途
从开始到拿到结果
- 1
系统核对并处理
分清 Python、显卡、固定权重及特殊环境缺哪层，只恢复当前路线所需部分并核对真实装载。
- 2
交付与接续
用小样本确认运行与回退点；下载完成或目录存在不等于模型可用。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
固定模型、候选比较及配置切换/回退已实现；本轮确认对齐权重目录存在，完整离线包仍缺失关键规则与设计选择
桌面听写用 scripts/dictation.ps1 -Mode Install 安装额外依赖、创建 ChineseASR Dictation 登录自启并立即启动；Status/Stop/Start 读回与停启，Uninstall 移除登录自启、保留项目和模型。
requirements-core.txt 固定 FunASR 1.4.14 与 NumPy 1.26.4，满足 NumPy <2；requirements-dictation.txt 增加 sounddevice 0.5.6、pystray 0.19.5、Pillow >=10。Qwen ASR（自动语音识别） 0.0.6、Torch 2.11.0+cu128、Transformers 4.57.6 维持。
新机在线安装与断网恢复使用同一模型 Registry（登记清单），但依赖获取方式不同。
项目要求 Python >=3.11；Windows 当前环境是 3.11.9，FireRed WSL（Windows 的 Linux 子系统） 当前环境是 3.12.3。
Windows PyTorch/TorchAudio 从 CUDA 12.8 index 安装；在线脚本不固定精确 torch 版本，离线可复现性由健康环境导出的 lock 和 wheelhouse 承担。
requirements-core 固定 FunASR 1.4.14 与 NumPy 1.26.4，Qwen runtime（运行环境） 固定 qwen-asr 0.0.6；FireRed 在 WSL（Windows 的 Linux 子系统） 中使用自己的一组精确依赖和 PyTorch/TorchAudio 2.10.0+cu128。
Qwen 和 FireRed 只接受固定 repository/revision 与规范 MODEL_RECEIPT，文件缺失、大小或 SHA-256 漂移都在模型加载前失败关闭。
wheelhouse 只保存 Windows Python wheel，不包含模型权重、私人录音、输出、FireRed WSL（Windows 的 Linux 子系统） venv 或源码 checkout（本地检出目录）。
setup、download、Doctor、unit test、runtime（运行环境） smoke 与真实录音 E2E（端到端验证） 是不同证据层，不能互相代替。
模型候选先用独立配置跑同语料 baseline/high_quality 评测，比较通过且输入/代码/配置仍匹配后才明确 activate-profile；旧权重和运行依赖独立保留，回退不覆盖后来修改的默认引擎。
本模块用到的名词
- dependency lock（依赖锁）
- 从一套健康环境冻结的精确 Python 包版本；online requirements 中的下限不能替代它。
- wheelhouse（离线轮包仓库）
- 为 lock 预下载的 Python wheel 集合；它让 pip 在断网时安装，但不含模型权重。
- checksum manifest（校验清单）
- wheelhouse.sha256 逐文件验哈希，wheelhouse.json 另记录 lock 哈希、文件大小和 SHA-256。
- MODEL_RECEIPT（模型回执）
- 绑定模型仓库、固定 revision、规范文件列表、字节数和 SHA-256；它验证已有工件，不负责备份工件。
- pinned revision（固定修订）
- 精确锁定模型或源码版本，防止同一名称在恢复后实际变成另一份内容。
- runtime smoke（运行冒烟）
- 实际加载模型并从入口生成最终制品；比安装、Doctor 和单元测试更接近可用性。
专业定义
把新机安装、断网重建与模型抢修拆成三组可核对工件：依赖包、固定模型缓存与回执、FireRed WSL（Windows Linux 子系统）运行时；下载完还得跑真实冒烟。
解决什么
解决代码都在但环境跑不起来、断网后才发现依赖或模型没预存、模型目录部分损坏却仍被加载、FireRed WSL（Windows 的 Linux 子系统） 因版本或存储容量漂移在重载时失败，以及换模型只改配置却没有重新验收真实转写的问题。
当前怎样实现
- pyproject.toml 要求 Python >=3.11；install-torch-cu128-direct.ps1 创建项目 .venv，从 CUDA 12.8 index 安装 PyTorch/TorchAudio 并现场打印 CUDA 可用性和设备。
- setup-core.ps1 安装 requirements-core.txt、editable（可编辑）项目，依次运行 pip check 和 zh_asr doctor；镜像不能满足时回退官方 PyPI。
- setup-qwen.ps1 在同一 Windows .venv 安装 qwen-asr==0.0.6；download-models.ps1 从 ModelScope 获取 Qwen/Qwen3-ASR-1.7B 固定 revision a04930dbe5419bfee073f7cade734f572689a3a8。
- qwen_identity.py 定义 13 个规范必要文件及其固定字节数/SHA-256；MODEL_RECEIPT 还绑定 schema（数据结构）、repository 和 revision，adapter（执行适配器） 在 Qwen3ASRModel.from_pretrained 前验证 runtime（运行环境）、回执与实际文件。
- setup-firered.ps1 在 Ubuntu WSL（Windows 的 Linux 子系统） 的 /opt/chineseasr/firered/.venv 建隔离环境，固定 FireRedASR2S commit 4e7d9aaf4482a47cec1724807026b9b151926eb5，验证 imports 与 CUDA 并回读 BF16 支持；Windows 默认模型配置不被改写。
- FireRed WSL（Windows 的 Linux 子系统） 依赖由 requirements-firered.txt 精确约束，含 Transformers 5.1.0、NumPy 2.4.2 等；Torch/TorchAudio 固定 2.10.0+cu128 并单独安装。
- download-models.ps1 从 Hugging Face 获取 FireRedTeam/FireRedASR2-LLM 固定 revision 2c5e0f415b9afb8f67cb8b00ea4c54959f70e824，并为 14 个必要文件原子生成带路径、大小和 SHA-256 的 MODEL_RECEIPT。
- export-lock.ps1 从已通过 pip check 的 Windows .venv 运行 pip freeze --exclude-editable，输出 requirements-lock.txt 与 python-version.txt。
- build-wheelhouse.ps1 把 torch 系依赖送到 CUDA 12.8 index，其余包送到 PyPI，写出 wheelhouse.sha256 和 wheelhouse.json；后者记录 lock SHA-256、每个文件大小与 SHA-256。
- verify-wheelhouse.ps1 对 checksum 清单逐项检查文件存在与 SHA-256；install-offline.ps1 默认先验证，再用 --no-index --find-links 安装精确 lock，安装本地源码并运行 pip check 与 Doctor。
- runtime（运行环境）/firered_worker.py 在哈希大权重和加载前同时验证固定源码 HEAD/干净工作树、模型回执、WSL（Windows 的 Linux 子系统） 配置容量和当前可用容量；半精度与 FP32 使用不同门槛。
- model_lifecycle 的 compare 验相同音频/真值/指标、独立样本规模、无重复或无效数据；纯合成、跳过案例或未改善拒绝提升。activate-profile 用当前代码/配置身份只切 strict 两个默认引擎并保存switch.json；rollback拒绝覆盖后来改变的默认值，保留无关设置。权重、运行依赖和驻留进程仍需各自恢复。
执行流程
- 1
联网健康环境先用 install-torch-cu128-direct.ps1、setup-core.ps1 建立 Windows 基线；需要 strict 时再 setup-qwen.ps1，需要 FireRed 时另建 WSL（Windows 的 Linux 子系统） 隔离环境。
- 2
按显式 engine 下载固定模型；Qwen 和 FireRed 生成/验证 MODEL_RECEIPT，SenseVoice、Paraformer 等常规模型进入 Git 忽略的 ModelScope 缓存。
- 3
在环境已通过 pip check/Doctor 后运行 export-lock.ps1，冻结精确包版本与 Python 版本。
- 4
运行 build-wheelhouse.ps1 下载全部 wheel，生成 checksum 与 JSON manifest（清单）；verify-wheelhouse.ps1 立即做一次独立校验。
- 5
把 wheelhouse、manifests、项目源码和模型/FireRed 工件作为不同恢复对象保存；Git 仓库只保存源码、脚本和小型 manifest（清单），不保存大文件。
- 6
断网时先验证 checksum，再由 install-offline.ps1 创建新的 venv、无索引安装、安装本地源码并运行 pip check/Doctor；正常验收不使用 SkipVerify。
- 7
恢复 Qwen 时核对固定 revision、13 项必要文件和回执；恢复 FireRed 时再核对 14 项权重、固定源码 commit、干净工作树、WSL（Windows 的 Linux 子系统） Python/CUDA 与内存门槛。
- 8
同一 adapter（执行适配器） 替换模型时先更新 Registry（登记清单） 与身份合同，再下载工件；新增不同 runtime（运行环境） 时新增 adapter（执行适配器），不在旧 profile 下伪装。
- 9
最后运行默认 strict 与 smoke-asr-smart；FireRed + Qwen 还运行 smoke-evidence-asr 并核对每段 verified、非空 raw、dtype、无 engine_failure，关键语句人工回听。
边界
- offline/wheelhouse、models、输出与私人音频都被 Git 忽略；公开仓库不是灾备载体。
- 当前离线脚本只重建 Windows Python 环境；它不离线创建 FireRed WSL（Windows 的 Linux 子系统） venv、克隆固定源码或恢复任何模型权重。
- MODEL_RECEIPT 不是模型文件、备份、数字签名或真实推理证明；只有工件仍在时才能逐项校验。
- verify-wheelhouse 校验清单内文件的存在与 SHA-256，不证明 Python ABI、GPU 驱动或新机器硬件兼容；必须实际 install smoke。
- FireRed 半精度至少要求 28 GiB RAM、34 GiB RAM+swap，启动时至少 18 GiB MemAvailable、22 GiB MemAvailable+SwapFree；FP32 对应 40/48 GiB 与 36/44 GiB。
- 当前 32 GiB WSL（Windows 的 Linux 子系统） RAM + 8 GiB swap 是这台机器的验证配置，不是所有硬件的统一承诺。
- 模型下载、环境体检和源码测试都不能替代真实音频 E2E（端到端验证）；重要录音还必须人工核听。
- 模型目录缺失或损坏时先验真再修复，wheelhouse不包含大型模型权重；源码、安装包和现有样本通过不能声称完整断网恢复已经验收。原权重与运行依赖仍需按模型清单分别准备和核对。
失败与恢复
- 断网时没有 requirements-lock 或 wheelhouse
- 明确判定无法离线重建 Python 环境；回到有网络且已验证的健康环境制备工件，不从未知缓存猜版本。
- wheel 文件缺失或 SHA-256 不一致
- verify-wheelhouse 失败并阻断安装；从可信源重新构建或恢复完整 wheelhouse，不使用 SkipVerify 绕过正常验收。
- offline pip install、pip check 或 Doctor 失败
- 保留失败包与错误，丢弃这次未通过的 venv，使用已验证 lock/wheelhouse 重建；不改变模型默认路由。
- Qwen receipt（执行回执）、runtime（运行环境） 版本或 13 项必要文件漂移
- 在模型 loader 前失败关闭；从固定 revision 重取或从可信备份恢复，并重新生成/核验规范回执。
- FireRed 模型回执、固定源码 HEAD 或干净工作树不符
- 拒绝加载；恢复固定 14 项权重与 pinned checkout（本地检出目录），不在被修改源码上继续证据路线。
- FireRed WSL（Windows 的 Linux 子系统） 配置总量不足
- 先调整 .wslconfig；在没有重要 WSL（Windows 的 Linux 子系统）/Docker 任务时执行 wsl（Windows 的 Linux 子系统） --shutdown 后重新启动，再复核容量。
- FireRed 配置足够但当前可用内存不足
- 关闭或等待占用进程后重试，不把临时争用误报为模型损坏，也不让 OOM 后反复装载。
- 模型更换后 Doctor 通过但 smoke 失败
- 该 profile 仍为 unavailable/provisional；回到固定工件、adapter（执行适配器） 与实际输出排查，不能把下载成功写成 ASR（自动语音识别） 场景可用。
真实入口
E:\Projects\Tools\ChineseASR\pyproject.tomlPython >=3.11 与项目安装入口
E:\Projects\Tools\ChineseASR\requirements-core.txtWindows 核心依赖、FunASR 1.4.14 与 NumPy 1.26.4
E:\Projects\Tools\ChineseASR\requirements-qwen.txtQwen ASR（自动语音识别） runtime（运行环境） 0.0.6
E:\Projects\Tools\ChineseASR\requirements-firered.txtFireRed WSL（Windows 的 Linux 子系统） 精确 Python 依赖
E:\Projects\Tools\ChineseASR\configs\models.yaml六引擎 Registry（登记清单）、固定 revision 与运行门
E:\Projects\Tools\ChineseASR\scripts\install-torch-cu128-direct.ps1Windows CUDA 12.8 PyTorch/TorchAudio 安装
E:\Projects\Tools\ChineseASR\scripts\setup-core.ps1Windows 核心 venv、pip check 与 Doctor
E:\Projects\Tools\ChineseASR\scripts\setup-qwen.ps1固定 Qwen runtime（运行环境） 安装
E:\Projects\Tools\ChineseASR\scripts\setup-firered.ps1FireRed WSL（Windows 的 Linux 子系统） 隔离环境与固定源码
E:\Projects\Tools\ChineseASR\scripts\download-models.ps1固定模型下载与 MODEL_RECEIPT 生成
E:\Projects\Tools\ChineseASR\scripts\export-lock.ps1依赖锁与 Python 版本导出
E:\Projects\Tools\ChineseASR\scripts\build-wheelhouse.ps1离线 wheel 下载与 checksum/JSON manifest（清单）
E:\Projects\Tools\ChineseASR\scripts\verify-wheelhouse.ps1离线工件逐文件 SHA-256 校验
E:\Projects\Tools\ChineseASR\scripts\install-offline.ps1无索引安装、pip check 与 Doctor
E:\Projects\Tools\ChineseASR\src\zh_asr\qwen_identity.pyQwen 13 项模型工件和 runtime（运行环境） 身份失败关闭
E:\Projects\Tools\ChineseASR\runtime\firered_worker.pyFireRed 14 项工件、源码、容量与装载验证
E:\Projects\Tools\ChineseASR\tests\test_scripts.pysetup、下载、wheelhouse、offline install 与 smoke 脚本回归
E:\Projects\Tools\ChineseASR\docs\architecture.md模型身份、WSL（Windows 的 Linux 子系统） 容量、数据流与替换验收边界
如何验证
- 2026-08-31 安装恢复基线：PUBLIC（公开） main=70e3255326ad8ba7b0e335fdf6b4a19caf0d8029，README、architecture、Registry（登记清单）、requirements 与完整安装/下载/离线脚本已逐项核对。
- Unit tests：2026-08-31 本轮 .venv\Scripts\python.exe -m unittest -v tests.test_scripts 运行 18 项并全部通过；它验证脚本合同，不下载 wheel、不装模型也不跑音频。
- 2026-08-31 Full regression 历史观察：同一轮 .venv\Scripts\python.exe -m unittest discover -s tests -q 运行 345 项，用时 83.524 秒并全部通过；仍不等于真实模型 E2E（端到端验证）。
- 2026-08-31 Runtime（运行环境） Doctor 历史观察：Windows 当时为 Python 3.11.9、PyTorch/TorchAudio 2.11.0+cu128、FunASR 1.4.5、Qwen ASR（自动语音识别） 0.0.6、ModelScope 1.38.1；RTX 5090 D 驱动 616.56、32607 MiB，六个引擎可枚举。
- Model artifacts：Qwen receipt（执行回执） 为 1763 B / SHA-256 0c43de9dd883adefb65cfa1477ad7156f749868105a554e647b47de73c841ef9，13 项声明合计 4703115105 B；FireRed receipt（执行回执） 为 2124 B / SHA-256 c4effd6931c0e09d8b2caaf7f8b9f58bed370fa4a174edfc64b668dd0b48dd01，14 项声明合计 18870501538 B。2026-08-31 确认所有声明路径存在、文件大小一致；本轮不重验模型工件。
- FireRed runtime（运行环境）：WSL（Windows 的 Linux 子系统） Python 3.12.3、PyTorch 2.10.0+cu128、Transformers 5.1.0、NumPy 2.4.2，CUDA/BF16 可用；固定源码 HEAD=4e7d9aaf4482a47cec1724807026b9b151926eb5 且工作树干净，当前内存高于半精度门槛。
- Unverified：本轮未逐字节重算两组全部权重 SHA-256、未加载模型、未运行 strict/evidence smoke，也未用私人录音做 E2E（端到端验证）；MODEL_RECEIPT 当前只到回执自身哈希、路径存在和大小回读。
- 2026-09-18 本轮只读确认 requirements-lock.txt、python-version.txt、wheelhouse.sha256、wheelhouse.json 和 offline/wheelhouse 均不存在；没有运行离线安装，也不能把模型工件目录当成可携带离线包。
与其他模块的关系
本模块承接模型与模式模块的精确 profile，把依赖、权重和 FireRed WSL（Windows 的 Linux 子系统） 恢复成可执行候选；只有再通过入口模块的真实 smoke、长音频执行与审计证据，候选环境才成为可用 ASR（自动语音识别） 路线。