项目页的留存统计、公开与本人范围及批量读取接口见 实况取数。
中文录音转写与桌面听写工具。录音来源、AI 会话的云优先顺序及费用边界统一见 项目规则;云入口见下文。需要本地回退或交叉核对时,两路模型保留分歧并输出正文和疑点清单,争议片段可在本地回听页面复核,需要时还能输出逐句时间和匿名说话人。桌面听写用单模型,把识别结果直接输入当前文本框。
本地回退或交叉核对路线:录音 → Qwen3-ASR-1.7B 主转写、SenseVoiceSmall 对照 → 标出两路不一致、静音出字、异常重复等疑点 → 回听复核。对应入口见下文「一分钟使用」:通过本地接口提交任务、先返回任务状态,调用方不会被长时间卡住。
ChineseASR 的目标是把中文录音转成可审计、低幻觉、可复现的文本。本地引擎面向 Windows + CUDA 工作站,quick 使用 SenseVoiceSmall,strict 使用 Qwen3-ASR-1.7B + SenseVoiceSmall。可选的 FireRedASR2-LLM 是 high_quality 路线的词汇主引擎,不会自动取代本地 strict 组合。
项目同时提供录音转写和 Windows 桌面语音输入。本文是使用入口;项目执行规则见 AGENTS.md,机器状态以 PCConfig 和 Windows 现场为准。
主界面是 200×75 实际像素的白绿小胶囊:麦克风控制录音,旁边的小箭头展开设备菜单,×收起。先点输入框,再按 Win+H 或 Ctrl+Win+H:显示小窗并录音,再按则隐藏并暂停。
按显示器优先级只显示一个小窗:VDD 接入时优先 VDD,断开后回退主屏。屏幕接回或分辨率改变后自动更新位置,保留手动拖动位置。configs/dictation.yaml 的 panel_monitor_ids 用硬件型号 ID 选择目标屏,未接入的目标不显示;设为 null 则仅跟随 Windows 当前主屏。
麦克风按钮单击录音、再单击暂停,不改变窗口显示;拖动空白处可移动小窗。点小箭头或右键麦克风可选择、刷新设备或复制最近文字。DJI 是默认选择,设备和长说明不占主界面;悬停可看状态,错误以小点和提示保留。
设备菜单使用随 Windows DPI 缩放的字号,外框尺寸固定。插入新设备后点“刷新麦克风”即可列出;所选设备会在下次录音时重新枚举,不会自行切换。
× 隐藏并暂停,尾句继续完成,后台仍待命;Esc 取消尚未输入的部分,已输入文字保留。只有托盘“退出”或脚本 Stop 才退出程序并释放模型,文字不会自动按回车发送。
听写使用现有 Qwen3-ASR-1.7B,不做双模型复核或自动润色。模型登录后在受监督的独立进程中加载;录音期间按需取得 GPU,暂停或收起后把模型保留在 RAM 并释放显存及 LocalGpuBroker 租约,下一次唤出不重复冷加载。加载、预热、激活、推理和停放都有有界等待;模型进程失去响应时只清理这一进程,尚未返回到界面的片段最多重试一次。真正的 GPU 排队、模型准备和麦克风故障分别显示,不再用长期“模型准备中”掩盖不同故障。登录后不会自行打开麦克风。
绿色麦克风表示已经开始采集声音;模型首次加载可以与录音并行,声音先留在内存,模型准备好后再识别。目前在约 600 ms 的语音停顿、最长 20 秒或手动暂停时提交整段结果,尚无逐字流式输出。轻量 WebRTC VAD 过滤无有效语音的输入,保留句内音频和前后缓冲;检测未通过或识别为空时不输入文字。默认术语提示留空,避免不清晰音频触发提示词复读。
.\scripts\dictation.ps1 -Mode Install # 安装听写依赖、登录自启并立即启动
.\scripts\dictation.ps1 -Mode Status
.\scripts\dictation.ps1 -Mode Stop
.\scripts\dictation.ps1 -Mode Start
.\scripts\dictation.ps1 -Mode Uninstall # 移除登录自启,保留项目和模型运行时接管这两组快捷键,支持本机键盘及远程控制发送的按键;退出或从托盘暂停快捷键后恢复系统行为。键盘监听与界面处理分开,麦克风初始化时仍能接收按键。麦克风和技术词拼写在 configs/dictation.yaml 设置;input_device: null 表示跟随 Windows 默认麦克风。指定设备未连接时会提示连接,不切换到其他麦克风。输入位置跟随与临时无法输入的处理见 docs/quality-and-model-maintenance.md 的 Desktop dictation reliability 一节。管理员窗口可能拒绝普通权限程序输入,需手动复制。
录音和识别结果不保存为历史文件;outputs/dictation/runtime.log 只记录运行错误、耗时和字数。麦克风选择保存在本机 outputs/dictation/preferences.json,不修改 Windows 默认设备。公开短音频只能检查软件集成及速度,个人口音、麦克风与实际体验仍以本人试用为准。
更新原则:AI 可以自主更新兼容依赖;没有证据证明新模型明显更好时维持当前模型,有可靠的中文效果、速度和兼容证据后再新增或替换。不会因为“发布了新版本”就自动换模,也未设置定时下载服务。
录音转写优先解决三件事:
- 中文准确性优先:strict 模式默认以
Qwen3-ASR-1.7B为主引擎,SenseVoiceSmall为对照锚点。 - 低幻觉和可复核:双模型分歧、静音出字、模板废话、异常重复、繁体残留、超长无标点等都会进入 audit / metrics / review。
- 适合 AI Agent 调用:
scripts\asr-smart.ps1通过本地 API 提交任务,快速返回 job 状态,避免长时间卡住命令行或上层 Agent。
AI 文件转写通过 唯一云入口 的 -CloudFirst 执行 项目规则 所定顺序;它直接检查配置免费期和已有停用状态,不需要先启动本地作业。Win+H 桌面听写继续使用独立的本地单模型。
python -m zh_asr.realtime 通过标准输入/输出 JSONL 连续处理所选 WAV,不开端口、不写录音或文字日志。启动先冷加载一次、GPU 预热并回 CPU/RAM;收到 event=ready 后才接消息,回执含 coldLoad、warmup、park 耗时和实际 workerPID。逐行发送 {"action":"transcribe","path":"E:/selected.wav","request_id":"opaque","budget_seconds":10},同一 worker 按听写配置的 max_chunk_sec 连续覆盖最多 60 秒全文;源文件只读,结果绑定 SHA-256、时长、每段起止与真实耗时。结果一出就返回,连续 3 秒没有新请求才把模型放回 CPU/RAM 并释放 GPU 租约,所以连续几条语音不用来回搬模型;放回失败会清理 worker,下一条返回 not_ready。请求共享最多 10 秒预算,失败或超时不返回成功;partial/empty 不表示无语音或已完整理解。status 核验模型已准备且 child 仍活;未就绪不自动重载,只有显式 prepare 或重新启动才能准备。close 或 stdin EOF 清理 worker。此入口不接答案、热词或润色。运行需要既有环境及模型缓存;独立 worktree 应复用原项目 models 目录联接,不复制权重。
文件转写支持 --profile high_quality / -Profile high_quality,选择 FireRedASR2-LLM 主引擎和 Qwen3-ASR-1.7B 校验;baseline 保留 Qwen + SenseVoice。选择配置不改变全局默认,也不影响桌面听写。短文件、长文件和文件夹使用同一时长约束,长录音自动切分;VAD 优先寻找停顿,而不是删除未被识别为语音的区域。
新增 Qwen3-ForcedAligner-0.6B 的固定版本安装、校验和按需对齐,供时间范围定位、音频覆盖检查及有声学时间支持的重叠去重使用。对齐成功不代表提供的文字正确。争议片段可用独立补充识别和本地回听页面复核,不进行多数投票或无音频的 LLM 文字裁决。
版本比较、明确激活、回退和输出状态说明见 质量处理与长期模型维护。配置存在、文件校验通过、软件测试通过和真实推理通过分别记录;公开短样例不作为全面准确率或默认换模的证据。
personal-use v0.1 当前处于维护态,维护验收按下述关闭标准执行。
推送前在本机运行上述 unittest discover 命令。需要预先下载 Qwen 模型缓存的个别测试在缓存缺失时明确跳过,其余测试继续执行;完整本机环境仍跑全部可用测试。
软件测试和公开样例的结果只说明实际验证过的集成、恢复和故障边界,不能代表个人麦克风效果或通用中文准确率。默认模型提升仍需要同口径 holdout 证据。Skill 的调用/维护说明和 PCConfig 的机器恢复契约已同步,项目业务事实仍以本仓库配置与实现为准。
维护关闭标准继续是:
scripts\doctor.ps1能确认无代理、CUDA、模型配置和依赖状态。python -m unittest discover -s tests没有未解释的失败;可选 fixture 缺失必须显式报告为 skip,而不是伪装通过。scripts\smoke-asr-smart.ps1 -Json能完成默认 strict smart job;重要录音另用scripts\smoke-evidence-asr.ps1 -Audio <path> -Json验收 FireRed + Qwen 完整证据链。- 公开仓库只包含源码、脚本、配置、测试和文档,不包含模型权重、用户音频、生成转写、模型收据或 wheelhouse 大文件。
- 微信语音、会议录音、口述笔记、中文播客、课程录音的本地转写。
- 对“幻觉低、能复查证据”要求高于“只要快”的中文 ASR。
- 需要让 Codex、脚本或其他本地 Agent 调用 ASR,又不希望命令行长时间阻塞。
- 需要保留 raw JSON、audit、metrics、manifest,方便以后追溯模型版本和输入 hash。
- 不愿意本地安装模型权重和 Python 环境。
- 需要英文、多语种或字幕生产工具链作为主目标。
模型注册在 configs\models.yaml,实现和模型选择解耦。
| 用途 | 默认引擎 | 说明 |
|---|---|---|
strict 主引擎 |
qwen3-asr-1.7b |
准确率优先的中文主转写线,基于 Qwen3-ASR 权重和 qwen-asr runtime |
strict 对照引擎 |
sensevoice |
快速中文声学锚点,用于发现分歧和疑似幻觉 |
quick |
sensevoice |
单模型快速转写 |
| 可选证据级词汇主引擎 | fireredasr2-llm |
隔离在 WSL 中运行;仅在显式选择时作为 strict 主引擎 |
| 文件云转写与复核 | qwen-audio-3.1-asr-flash / qwen-audio-3.1-asr-flash-message |
短录音、方言、说话人分离用 Flash;热词及较长录音用 Message 分段实时流。模型与路由见 configs/models.yaml |
| 显式时间线/匿名说话人 baseline | paraformer |
固定 speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch@v2.0.4,输出逐句 sentence_info 时间和 CAM++ 匿名聚类;已知两方通话的调用方可传 --preset-spk-num 2,省略时自动聚类;不改变 quick/strict 默认 |
Paraformer 逐句时间先核实再截证据:sentence_info 的时间只用来定位。时间不可靠时(与回听、云端分段时间或另一路结果对不上,或出现只有标点的空句),截取证据前先用 ffmpeg 按候选时间截出该段(前后各留几秒),单独放进一个文件夹用 scripts\transcribe-folder.ps1(strict)重新听写,确认片段里就是要截的那几句,再按核实过的时间截取。
FunASR 1.4.14 在相邻两个中文 VAD 段之间少拼一个空格,自带的逐句文字会每过一段就往前错一个字,长录音里能差出几十秒,结尾只剩标点。本项目让 FunASR 同时返回逐字词元(raw_text),按逐字时间戳把每句文字放回它自己的时间上,结果标 sentence_info_alignment.status=aligned;词元和时间戳数不上时不给逐句时间(status=unaligned,原句移到 sentence_info_unaligned)。没有这个标记、文字和逐字时间戳对不上的旧结果,回读按 sentence_timestamps_misaligned 拒收,attribute-speakers 也会拒绝,重跑 Paraformer 即可。
strict 模式即使一路模型失败,也会保留可用输出并生成审计包。正文会标记 [疑似],strict.audit.md 会记录失败引擎、异常摘要和复核理由。两路都失败时输出 [听不清]。
只交原音路径、由项目决定云优先与本地兜底时,使用统一文件入口:
.\.venv\Scripts\python.exe -B -m zh_asr file-job --audio 'E:\selected.wav'首次调用隐藏启动一个一次性文件 worker,立即返回 JSON;随后用同一命令查询。状态为 queued、running、waiting_gpu、succeeded 或 failed,同时返回 route=cloud|local、reason、error、timestamps=available|unavailable,已有任务还带 job_id、out_dir 和结果路径。按时间或事件自行启动的后台任务携带 AGENTS_BACKGROUND_AUTOMATION=1,入口与 worker 不查资料锁,锁定、到期或未知都照常运行;Windows 脱离式 worker 只接收本次来源标记,不修改系统或共享进程环境。对话及对话派出的任务仍先检查个人资料期,锁住时返回 queued/reason=personal_access_required,下次调用再补,不自动解锁。
Windows 的一次性 worker 由固定脚本经 WMI 隐藏启动,脱离提交方计划任务的进程组;不会新建计划任务或常驻调度器。本地 API 消失时先查已完成稿件,再由下一次查询安排原入口恢复,返回 queued/reason=local_api_recovering,不会永久等待旧作业编号。旧本地作业超过一小时会取消并标记可重试失败,不挡住其他录音。
入口按实际原音 SHA-256 复用已有成功稿件;云调用复用现有 asr-professional-cloud.ps1 -CloudFirst,由它检查配置免费期和停用/暂停状态。云不适用或失败时保留 fallback_reason,本地使用现有 Paraformer 完整转写与句级时间;GPU 被同类或 Ollama 活动占用时返回 waiting_gpu,不启动本地推理,下次调用再试。fallback_reason 在本地成功、恢复和重复读取后仍保留,当前 reason 可另说明本地状态;调用方可展示云回退原因,不因此把本地成功记作失败。不会新建计划任务或常驻轮询器。
直接调用云脚本时,同原音并发仍最多等 24 小时;统一 file-job 显式传 -ConcurrentWaitSec 5,后台只短等同一云请求。需要调整直接脚本的等待时可显式指定此参数。
文件入口由 ASR 读取本机加密 Key 副本并直接发送;后台来源沿同一标记继续发送;对话来源每块前重查资料期,锁定后暂停,解锁复用同一云作业和已知成功分块,只发未发送的块。每次网络请求最长 180 秒,超过五分钟没有块进度会终止本次自有进程树并留下失败原因;整段另有按原音时长计算的上限。未知请求不重传,云端明确拒绝旧 Key 时的候选更新见下文。
云产物仍在 outputs/cloud-jobs,本地产物仍由现有 API 作业管理;单文件进度在 outputs/api/file-jobs/<原音SHA256>.json。transcript-readback 也会按 SHA 直接读取这一份已完成产物引用并复用原解析与哈希校验,API 裁剪到最近 200 个终态后仍可回读。成功须通过现有 transcript-readback 校验;只有全文、缺句级时间时仍成功并返回 timestamps=unavailable,云分块范围不冒充句级时间,不为补时间再次识别全文。云成功但产物暂时不可回读时保留失败原因,后续只重读产物。云已发送、结果未知或身份被拒绝时不会自动重传、换身份或改凭据绑定;本地失败后的再次调用可重试本地,成功稿件不重复转写。
在仓库根目录打开 PowerShell:
cd <repo-root>
.\scripts\doctor.ps1
.\scripts\asr-smart.ps1 -Audio C:\path\to\audio.wav -Mode strict -WaitSec 15 -Json推荐日常入口是 asr-smart.ps1,因为它会走本地 API/job 队列,不会把调用方长时间卡死。
常用模式:
# 严格双模型,推荐默认
.\scripts\asr-smart.ps1 -Audio C:\path\to\audio.wav -Mode strict -WaitSec 15 -Json
# 长音频,自适应引擎上限切片 + 断点续跑
.\scripts\asr-smart.ps1 -Audio C:\path\to\long.wav -Mode long-strict -WaitSec 15 -Json
# 重要录音的证据级组合;不会改变默认配置
.\scripts\asr-smart.ps1 -Audio C:\path\to\long.mp3 -Mode long-strict -PrimaryEngine fireredasr2-llm -SecondaryEngine qwen3-asr-1.7b -Important -WaitSec 15 -Json
# 明确的重要/专业录音显式复核;固定哈希的受管目标执行上传
.\scripts\asr-professional-cloud.ps1 -Audio C:\path\to\important.wav -Important -CloudUploadAuthorized -Json
# 当前选定的普通存疑本地转写可作显式质量复核;不会被标成重要录音
.\scripts\asr-professional-cloud.ps1 -Audio C:\path\to\uncertain.wav -QualityReview -CloudUploadAuthorized -Json
# 快速单模型,只在明确接受较少审计时使用
.\scripts\asr-smart.ps1 -Audio C:\path\to\audio.wav -Mode quick -WaitSec 15 -Json
# 批量转写文件夹
.\scripts\transcribe-folder.ps1 -InputDir C:\path\to\audio-folder
# 显式选择高质量配置批量转写
.\scripts\transcribe-folder.ps1 -InputDir C:\path\to\audio-folder -Profile high_quality批量输出通常沿用原目录名;仅重名冲突项使用独立结果目录,可从 summary.md 定位,移走冲突同伴后仍复用该目录续跑。
批量扫描会排除输入目录内的输出子目录;输出根与输入根相同或包含输入根时,在写入前报错。
需要让媒体检索复用已经存在的转写和时间段时,可以按原音频 SHA-256 只读回读 owner(归属方)管理的本地任务快照和已保留云结果:
.\.venv\Scripts\python.exe -B -m zh_asr transcript-readback `
--audio-sha256 <64-hex-source-sha256> `
--jobs-snapshot .\outputs\api\jobs.json该命令只读取 jobs.json 和其中明确引用的结果文件,以及 outputs\cloud-jobs 中已完成、哈希绑定的云结果;不读取原音频,不启动服务或模型,不创建数据库、缓存或新结果。
也会按原音 SHA-256 查询快照所属 outputs\batch 下的 batch-item.json,校验并返回 artifact.transcript 稿件路径、原始质量与覆盖信息(quality.review 保留复核状态和 needs_review,quality.audit 保留严格审计的 conflict 等状态);单条与批量并存时沿用现有优先规则,其他稿件位置见 lookup_scope.alternatives,只有稿件而无可回读时间段时仍返回 gap / timestamps_unavailable,不会当作没有转写。
它同时核对 job.request.audio_sha256、objective sidecar(目标结果旁路文件)的 audio.raw_sha256 与
idempotency_basis.source_audio_sha256,确认处理已完成,并按 sidecar 声明的路径、字节数和 SHA-256 核对实际解析的 raw artifact(原始结果文件)字节。
机器结果的顶层字段为 schema、status、source_audio_sha256、segments、artifact、quality、
coverage、evidence_status 和 lookup_scope。有可用时间段时,status=ok,每个 segments 项至少包含
start_ms、end_ms、text、speaker、timestamp_granularity 和 raw_path;raw 结果明确提供的细粒度
timestamp 数组只有在有效且位于该片段内时才保留。quality、coverage 和 evidence_status 只做保守投影,不把
coverage.status=complete 自动改成完整覆盖。
没有保留任务、结果完整性校验失败或匹配转写没有有效时间段时,命令返回 status=not_found 或 status=gap,
并在 gap.code 给出原因,不猜测时间。仍在处理的任务会返回其 ID,应继续该任务而非重复提交。重复源哈希按时间段可用性、证据、质量、覆盖和段数确定性取优,任务新旧
本身不被当作质量证明。Paraformer 的 sentence_info 是当前明确支持的逐句时间和匿名说话人结构,句子文字与逐字时间戳对不上的结果以 sentence_timestamps_misaligned 拒收;其他引擎只有
在 raw 结构明确提供有效时间段时才会被回读。云结果只在 schema、用途、成功状态、原音哈希和每块范围都一致时可回读;其范围的
timestamp_granularity=chunk,不是句级时间戳,quality.status=unknown,且云端成功不构成逐字准确性或说话人归属证明。
固定端到端 smoke:
.\scripts\smoke-asr-smart.ps1 -Json重要录音的完整证据链验收:
.\scripts\smoke-evidence-asr.ps1 -Audio C:\path\to\important.mp3 -Jsonscripts\asr-professional-cloud.ps1 是唯一的云上传入口。3.1 Flash 用 HTTPS Base64,按配置每段最多 120 秒;3.1 Flash-Message 用 WebSocket,把本地录音切成最多 30 秒的单声道 PCM 段逐段送入。Message 是实时接口,不能直接提交长文件。录音原件及声道来源不改动;需要说话人分离时选 Flash,返回的说话人编号只在单段内有效。Filetrans 虽能处理长录音,但要求公网可访问 URL,本项目不使用。
AI 处理当前选定的录音时直接使用下面的入口,不需要已有本地作业或本地质量结果;重要证据在命令中加 -Important,普通录音不加。-CloudFirst 沿用配置免费期与停用检查,失败或过期时保留回执,按 项目规则 本地兜底。不同内容的音频可以同时上传(原传输路线实测 6 条同时全部成功),内容相同的轮流。单声道 16 位 WAV 在程序内转采样,不启动 ffmpeg。
.\scripts\asr-professional-cloud.ps1 -Audio '<原录音绝对路径>' -CloudFirst -Json
.\scripts\asr-professional-cloud.ps1 -Audio '<重要原录音绝对路径>' -CloudFirst -Important -Json用途与上传依据分开校验:
-Important:当前录音已被明确归类为重要或专业录音。请求仍写入importance=important,回执仍为important_only=true;-CloudFirst不加-Important时是普通录音转写,purpose=transcription;不能和-QualityReview同时使用。-QualityReview仍用于当前选定的本地存疑转写复核,purpose=quality_review、important_only=false;-CloudFirst自带免费期内的自动上传依据,无需-CloudUploadAuthorized或-LocalOutDir。既有-AutomaticReview -LocalOutDir <本地结果目录>保留为本地疑难结果的补跑路线;-CloudUploadAuthorized仍表示调用方已取得本次明确上传授权;- 本机共享加密 Key 副本可读;缺失或不可读时返回具体原因,文件入口沿用本地兜底。
-Important 和 -QualityReview 不能同时使用。云入口不会自动启动 FireRed、Qwen 或其它本地双引擎;是否补本地证据链及如何回核分歧,按 项目规则 和当次证据用途决定。
ASR 使用 PCConfig 的 vendor_key_copy.py 只读本机副本,自行发送 HTTP 或 WebSocket 请求;正常发送不经密码中心取 Key 或转发。对话来源的资料期查询仍只读既有保护入口;上述自行启动的后台任务不查资料锁。
每次尝试都在被 Git 忽略的 outputs\cloud-jobs 留请求、供应商原始结果、投影结果、原音哈希、模型、时间及每段 usage;这些是作业记录,本地不预留或计算剩余额度。百炼官方的 3.1 计量是 Token,但本地不以此拦截调用。
3.1 Flash-Message 的 WebSocket result-generated.payload.usage 是该段任务截至当前事件的累计用量,task-finished.payload.usage 是最终累计用量(官方服务端事件说明)。结果投影每段优先取最后一个非空 task-finished 用量;若完成事件没有用量,取最后一个非空 result-generated 用量,不把递增快照相加。作业级 usage 只在所有音频段均有相同的数值字段时逐字段相加;任何一段缺失或字段不一致则保留 null,不把未知当作零。这里的 duration 是供应商逐段报告的累计音频秒数之和,不是去重后的源音时长,也不用于本地额度计算。
免费期截止只读 configs/models.yaml 中每个云模型的 free_until,按北京时间的带时区时刻作不含截止点的比较;日期的来历与精确性以配置登记为准,不是控制台实时核验。到期、停用、费用及续免费提醒统一按 项目规则 执行,命令不计算剩余额度。
outputs\cloud-jobs\auto-cloud-state.json 保存停用状态。python scripts/cloud-review-state.py status 回执含 enabled、free_until、各自动路由模型的 model_free_until、reason 和 failure_reason;只读状态不查询账号额度。主动停用使用 python scripts/cloud-review-state.py pause --reason "暂停原因",本人说恢复时用 python scripts/cloud-review-state.py resume;状态恢复与错误分类的规则归 项目规则。
本地转写的 quality.review.json 标 needs_review、两引擎分歧、[疑似]、provisional 或作业的 -Important 标记会触发自动复核。本地 API 服务只在 cloud.review.json 标记 pending_ai_session,并把状态放入 asr-smart.ps1 -Json 的 cloud_review 字段;服务自身不上传。asr-smart 若先返回运行中,AI 应按 next_status_command 查询终态,再读取 cloud_review。处理该录音的 AI 会话读到待补跑状态后,执行侧车给出的 asr-professional-cloud.ps1 -Audio <原音> -QualityReview(重要录音改用 -Important)-AutomaticReview -LocalOutDir <结果目录> -EvidenceStatus <本地状态> -Json。停用或所选模型免费期到期时,本地只记录原因,不安排上传。
配置、音频检查或提示写入失败时,本地作业仍为 succeeded,原有 cloud_review 字段标 failed / cloud_review_not_scheduled,写明「云复核未安排成功」及异常原因;即使 cloud.review.json 未能写入,失败仍随作业历史保存,重启后可查询。本地稿保留,修好原因后可沿下面的批量或单次入口恢复;已恢复的侧车结果优先于历史失败提示。
python scripts/cloud-review-batch.py --dry-run 列出现有疑难作业、待补跑状态以及源音失效的作业号;在 E:\Music 找到同名且 SHA-256 完全一致的源音时,预览会显示恢复的新路径。也可用 --recover-root <目录> 指定搜索位置;找不到的作业须由 AI 确认新源音路径后单独补跑。批量执行由 AI 会话运行 python scripts/cloud-review-batch.py;先用 --dry-run 查看候选。去掉 --dry-run 才上传。云结果保存在被 Git 忽略的 outputs\cloud-jobs,本地结果目录另写 cloud.review.json 并排保留文本与差异,不静默覆盖正文。云调用失败会
明确返回失败原因,不会静默冒充本地结果。Key 副本缺失时不上传;网络、
限流、超时或供应商 5xx 只影响本次,不盲目自动重发同一段音频;需要时以原音和已留结果检查后再试。其它云失败明确建议改用本地
asr-smart,并保持云结果与本地证据链分开。对于要当证据用的录音,云结果是能力优先的
专业候选,本地证据链按当次证据用途和真实分歧需要补做,不能把云转写本身当作证据认证。
asr-professional-cloud.ps1 -Json 的标准输出只给最终转写回执,直接传输结果保存在 outputs\cloud-jobs\<job>.provider.json;批量补跑会先按原音哈希、用途和声道复用已成功的云结果,修正误记的失败侧车,再决定是否上传。
显式复核可以带 -Hotwords @{'省高院'=2;'最高院'=2}、-SpeakerDiarization 或 -KeepDialect;前者使用官方即时热词权重,两个声学选项不可同时开启。重要录音用 -Important,普通存疑质量复核用 -QualityReview。官方接口与计量见语音识别模型表、Flash HTTP 参数、Message WebSocket 参数及模型价格。
先安装 CUDA 版 PyTorch 和核心依赖:
.\scripts\install-torch-cu128-direct.ps1
.\scripts\setup-core.ps1核心依赖文件 requirements-core.txt 固定 funasr==1.4.14。先完成 CUDA/PyTorch 与核心依赖安装,再按需下载模型。
pyproject.toml 有意不声明运行依赖:pip install . 只安装项目入口,不会下载 CUDA/PyTorch、模型框架或模型权重。完整本机环境按上面的安装脚本和 requirements-core.txt 配置。
下载 quick / secondary 默认需要的 SenseVoice:
.\scripts\download-models.ps1 -Engine sensevoicestrict 主线需要 Qwen ASR runtime 和权重:
.\scripts\setup-qwen.ps1
.\scripts\download-models.ps1 -Engine qwen3-asr-1.7bQwen 的固定运行时、模型 revision 及加载前校验约束统一见 架构说明“引擎策略”。下载脚本会生成并核验 MODEL_RECEIPT.json;已有固定缓存可用 -ReceiptOnly 只核验或生成收据,不下载也不加载模型。
可选的 FireRedASR2-LLM 使用独立 WSL runtime,安装顺序如下:
.\scripts\setup-firered.ps1
.\scripts\download-models.ps1 -Engine fireredasr2-llm默认 WSL 虚拟环境是 /opt/chineseasr/firered/.venv。源码和权重分别放在 Git 忽略的 models/firered/FireRedASR2S、models/firered/FireRedASR2-LLM:
- 源码固定为 commit
4e7d9aaf4482a47cec1724807026b9b151926eb5。 - 模型固定为 revision
2c5e0f415b9afb8f67cb8b00ea4c54959f70e824。 - 下载完成后生成
MODEL_RECEIPT.json,记录 14 项必要权重文件的规范顺序、路径、大小和 SHA-256。运行时逐项校验 receipt、固定 revision、源码 HEAD 和干净工作树,任一不一致都会拒绝装载。
FireRed 输入契约是 16 kHz、16-bit、mono PCM WAV;MP3 等输入由前端经 ffmpeg 生成派生 WAV。单输入硬上限为 40 秒,长音频的推荐有效切片为 35 秒。
启用 use_half: true 且使用 CUDA 时,隔离 worker 会让 Qwen 基座首次装载即使用 BF16(GPU 不支持 BF16 时使用 FP16),避免官方实现先完整物化 FP32 权重、随后才转半精度造成的内存峰值。临时装载桥在成功或异常后都会恢复官方绑定,固定源码 checkout 不会被改写;raw 结果会记录 llm_initial_load_dtype。
FireRed 的 CPU 装载峰值仍高于普通 ASR。本机 64GB Windows + RTX 5090 D 的已验证 WSL 配置是:
[wsl2]
memory=32GB
swap=8GB
[experimental]
autoMemoryReclaim=gradual修改 %UserProfile%\.wslconfig 后需在没有重要 WSL/Docker 任务时执行 wsl --shutdown 再重新启动。隔离 worker 会在大权重哈希和装载前同时检查配置容量与当前可用容量,并在无法读取 Linux CUDA 内存信息时 fail-closed。半精度装载的最低配置门槛为 28 GiB RAM、34 GiB RAM+swap,启动当下还需至少 18 GiB MemAvailable、22 GiB MemAvailable+SwapFree;不满足时会区分“配置不足”和“当前占用过高”并给出可操作错误。这里的 32GB/8GB 是本机验证值,不是对所有硬件的统一承诺。
常规模型下载与 FireRed runtime setup 会清理代理环境;FireRed 的 Hugging Face 权重下载保留调用进程当前代理设置,以适应实际联网环境。常规模型缓存位于 models\modelscope;这些模型目录都不进入 Git。
strict 模式会把最终稿和证据拆开:
| 文件 | 用途 |
|---|---|
*.strict.md |
给人看的最终转写正文,尽量保持干净 |
*.strict.audit.md |
模型文本、相似度、分歧、flags、候选文本和判断依据 |
*.strict.audit.json |
机器可读审计报告 |
*.strict.review.json |
面向机器和人工复核的结构化投影 |
*.strict.receipt.json |
绑定本次全部严格产物的路径、大小、SHA-256、语义声明与 bundle SHA |
*.qwen3-asr-1.7b.raw.json |
主模型原始输出 |
*.sensevoice.raw.json |
对照模型原始输出 |
*.fireredasr2-llm.raw.json |
显式选择 FireRed 主引擎时的原始输出 |
长音频和评测流程还会写:
| 文件 | 用途 |
|---|---|
manifest.json |
输入 hash、模型配置 hash、chunk 参数、chunk 状态 |
metrics.json |
耗时、相似度、风险标记、模型和运行时信息 |
review.md |
最值得人工复核的片段队列,按 P0/P1/P2 排序 |
benchmark.md / benchmark.json |
和 truth 文本对齐后的评测结果 |
不要把 raw JSON 当最终稿。常规读取顺序是:先看 outputs.final 或 *.strict.md,再看 audit.md、audit_json、metrics.json 和 review.md。
默认转写不是声纹识别:模型给出的 speaker 编号只是匿名分段/聚类,不能直接等同“本人”。只有真实问题需要判断一句话是谁说的时,才对已有的、带起止时间的转写 JSON做一次小投影。普通 attribute-speakers 不读原始音频、不加载模型;结果只下发逐句文本、匿名说话人、状态、角色、单句中文依据和回到原转写的 JSON pointer:
python -m zh_asr attribute-speakers C:\private\call.raw.json `
--context C:\private\call.speaker-context.json `
--out C:\private\call.speaker-attribution.json在本机私有边界内,可以显式保存唯一一个用户本人的 person:self CAM++ profile。它不是通用声纹库:没有第二数据库、服务、队列、他人 profile 或全库重跑。单参考兼容 profile 保存在 Git 忽略的 outputs\private(也可显式指定另一条私有路径),包含参考路径/哈希/片段/声道和一个可撤销向量。跨录音域 profile 只接收恰好 2–3 条不同源参考,将每条向量 L2 归一化后求质心并再次归一化;持久化文件只有一个质心、来源哈希/大小、精确片段与可回查选择绑定,不保存源路径、原音或各参考向量。
只对“本人候选”有清晰、无反证依据的有限片段建锚。每次必须写出一条 --inference-basis:profile 固定为可撤销的 inferred,不能冒充 confirmed,可以用更强或更新的参考显式替换。
python -m zh_asr speaker-enroll C:\private\known-self.wav `
--start-ms 0 --end-ms 12000 --channel mix `
--inference-basis "该片段有可回查的本人候选依据,且可由更强参考替换。" `
--profile C:\private\person-self.voice-profile.json --device cpu需要兼顾应用双声道与普通通话时,可用一个私有 manifest 指定 2–3 条来源天然明确、互不重复的有限参考;manifest 本身不进入 Git,profile 中也不保留其中的源路径。每条必须绑定现有证据 JSON 的 SHA-256 和 JSON pointer,不能只写“我觉得是本人”:
python -m zh_asr speaker-enroll `
--references C:\private\person-self.reference-set.json `
--profile C:\private\person-self.voice-profile.json --replace --device cpu之后只在需要的一个目标片段上生成证据。目标向量只在内存中计算并丢弃;输出仅留下原始目标哈希、精确片段时间、声道提取方式、模型/文件哈希、profile 哈希和相似度/阈值:
python -m zh_asr speaker-evidence C:\private\call.m4a `
--start-ms 18400 --end-ms 23100 --channel mix `
--profile C:\private\person-self.voice-profile.json `
--out C:\private\call.18400-23100.person-self-evidence.json `
--require-held-out --device cpu--require-held-out 会在目标原件曾参与当前 profile 时失败关闭,避免把 enrollment 片段回测成“验证”。模型固定阈值不会因质心或单次样本被调到刚好通过;相似度仍须与声道、联系人、对话角色和内容融合。
即使调用方没有要求 held-out,evidence 也会按源哈希标记 enrollment_source 或 held_out_source。单参考兼容 profile 与跨来源质心 profile 的同原件分数都只留作本地审计;归属投影会把它降为 unknown 声学线索,防止录音设备、声道或背景底色泄漏成身份判断。
显式替换或删除也只作用于这一份 person:self profile:
python -m zh_asr speaker-enroll C:\private\new-known-self.wav `
--start-ms 0 --end-ms 12000 `
--inference-basis "新的可回查本人候选依据;替换旧锚。" `
--profile C:\private\person-self.voice-profile.json --replace
python -m zh_asr speaker-profile-delete `
--profile C:\private\person-self.voice-profile.json --confirm-delete person:self--channel mix 会明确记录为 mixed_not_channel_evidence。left/right 只在原始输入确为双声道时由新入口精确提取;默认 quick/strict/long 的单声道准备产物不能倒推为左右声道证据。即使是小米录音,也只有同时满足已验证 cohort、原始右声道精确提取、源文件 SHA-256 和分段时间都匹配时,才有一个可撤销的“本人候选”声道线索。
把一份或多份上述证据传给投影时,context.recording_audio.sha256 必须绑定同一原始音频。CLI 会把转写 JSON、context、每份 voice evidence 的实际文件 SHA-256,以及该原始音频 SHA-256 写进顶层 input_binding;库调用没有文件时使用同一 JSON 的 canonical SHA-256:
{
"schema": "chinese-asr.speaker-attribution-context.v2",
"recording_kind": "mono_call",
"recording_audio": {
"sha256": "<原始音频 SHA-256>"
},
"segment_evidence": [
{
"index": 0,
"dialogue_role": {
"candidate_role": "self",
"reason": "该句在快递员询问后回答了本人持有物的故障。"
}
}
]
}python -m zh_asr attribute-speakers C:\private\call.raw.json `
--context C:\private\call.speaker-context.json `
--voice-evidence C:\private\call.18400-23100.person-self-evidence.json `
--out C:\private\call.speaker-attribution.jsoncontact_role、dialogue_role、semantic_role、cross_recording_role 与来源上下文都是软线索,可单独形成可撤销 inferred,也会相互融合。当前项目没有独立可信 receipt adapter,因此即使 source_identity 带有 authority_ref 也只能形成 inferred,不能由 caller 自报升为 confirmed。输出逐段只保留匿名 speaker、结论、单句中文依据和原转写 JSON pointer;不会下发声纹分数、逐项内部线索或目标 embedding。
- CAM++ 相似度、联系人、声道、对话角色、句义和跨录音相同声音都不能单独
confirmed;相似度本身只是person:self的正/负候选线索。 attribute-speakers只让与当前唯一私有person:selfprofile 哈希一致的声纹分数参与方向判断;profile 被删除或替换后,旧 evidence 自动失效并保留为unknown声纹线索,独立的声道、联系人、对话角色和句义依据不受影响。- 归因器不做固定加权、合成分数或 high/medium/low 等级。单一清晰且无反证的线索、或多项同向线索,都可以直接产生可撤销
inferred;声纹/声道只组织注意力,不是低智力终裁。 - 若声纹或声道与有具体理由的来源、联系人、对话或句义判断相反,投影会在内部保留两边证据,并在对外单句依据中说明为何后者暂时压过前者;只有上下文判断本身冲突、或只剩无法解释的相反声学线索时,才输出
unknown和speaker_attribution_gap=true。 recording_kind=mono_call且目标来自mix/mixed_not_channel_evidence时,投影使用更保守的±0.04声纹风险带;模型阈值仍固定为0.31,不会拿单通电话重调模型。风险带内的分数只记为unknown声学线索,仍可由具体联系人、对话角色或句义依据作可撤销判断。其他录音类型继续使用模型证据的±0.02常规歧义带。- 这只归属“这段语音可能是谁说的”,不证明照片、视频、微信媒体或消息由用户发送、拥有或持有;媒体来源/Owner 必须另有明确来源事实。
- Paraformer 的可选 CAM++ diarization 仍只是匿名聚类,可能过拆/合并,不能替代
person:selfenrollment,也不能把 cluster ID 解释成用户。
如果原转写没有可用时间戳,应只在真实问题需要时先补这一份录音的时间戳分句;不要批量把历史录音或每条消息转成“本人事件”。
顶层 job 的 succeeded 只表示流程产出了结果;机器消费者必须同时读取 evidence_status:
verified:要求的双引擎链完整执行,且 final、audit、review、两路 raw 已通过收据哈希和语义交叉校验;不表示转写逐字准确,仍需看status、分歧和人工复核项;provisional:至少一路引擎失败,现有文本只是带失败证据的回退结果;unavailable:证据链或必要产物不完整;pending:仍在处理;not_applicable:quick 单引擎任务不适用证据级双引擎状态。
显式使用 FireRed 时,若 FireRed 失败而对照引擎成功,流程仍会生成带 [疑似] 的回退文本,但 job、长音频 manifest 和对应 chunk 都会标为 provisional,并列出 evidence_failures。状态判定会重新验证收据覆盖的六项内容产物,核对路径、字节数、SHA-256、两路 raw 独立性、引擎身份、文本、执行状态、错误以及 final/audit/review 对 audit JSON 的投影;未同步重建收据的替换、损坏、缺失或语义错配会使 verified 降为 unavailable。该收据是自包含的一致性清单,不是数字签名或可信时间戳,不能单独证明外部真实性。证据级验收还必须确认每个 FireRed raw JSON 文本非空、error=null、运行时 dtype 正确,并且逐段审计不含 engine_failure;原始录音始终是权威来源,verified 不能替代人工核听。
每个 quick/strict 结果都会旁写一个版本化的 *.objective-result.json(long-strict 为根目录的 objective-result.json,chunk 也各有一个)。它与旧 strict 两条 engine_evidence 和 receipt 分开,机器消费者必须读取 objective_outcome,不能把空字符串、空数组、零字节或 expect_empty 当作无语音:
speech_transcribed:至少有可观察转写文本;单引擎空文本会附带quality.status=low_confidence,不能把双引擎链的verified当成准确性证明;no_speech_detected:只在完整音频覆盖下取得规范 VAD 零区间,或完整有效 PCM 的全零负证据时使用,并绑定 raw SHA-256、处理器/配置/策略/request hash、区间和非空负证据 hash;speech_detected_but_not_transcribable:检测到语音区间但文本为空,保持 deferred/unknown,可交给音频理解路线;indeterminate:没有完整 VAD/负证据,或存在预处理、模型、子进程、格式、覆盖等不确定性。
sidecar 的正式正交字段是 execution.status ∈ {completed, failed, unsupported, corrupt}、coverage.status ∈ {complete, partial, unknown} 和 quality.status ∈ {sufficient, low_confidence, unknown};旧 *_status 别名在顶层及 compatibility 中保留兼容值,新消费者读取上述正式字段。media_kind 固定为 audio。调用方若有 caller-owned 绑定,可通过 API caller_binding 原样透传;服务到 CLI 子进程只经 ZH_ASR_CALLER_BINDING_JSON 环境变量传递,不进入命令行,ChineseASR 不解释或伪造这些治理字段。long-strict 允许配置的 chunk overlap,但必须从 0 连续覆盖到原音频时长、没有 gap/exclusion、首尾闭合,且所有 child 负证据、区间、raw 引用和幂等身份都绑定时才允许聚合为 no_speech_detected。旧 Markdown 或缺 sidecar 的缓存最多是未验证的历史产物,不得据此宣称无语音。
本地 API 只绑定 127.0.0.1:
.\.venv\Scripts\python.exe -m zh_asr serve --host 127.0.0.1 --port 18666 --state-dir outputs\api--host 仅接受 127.0.0.1。HTTP 请求的 Host 必须是本机地址,带 Origin 时须与服务同源;提交转写任务须使用 application/json。本机脚本、CLI 与智能客户端仍可传入自定义模型缓存目录和既有 GPU 兼容参数。
主要端点:
GET /healthGET /jobsGET /jobs/{job_id}GET /observer/jobsGET /observer/jobs/{job_id}POST /jobs/transcribePOST /jobs/{job_id}/cancel
/observer/* 是只读安全投影,供本机统一观察台读取。它只返回任务状态、模式、逻辑模型名、时间、可用的长音频 chunk 计数与终态 RTF;ASR 不产生通用 LLM token 指标,因此 token 状态固定为 not_applicable。投影不返回音频/输出路径、PID、命令、stdout/stderr、识别正文、证据完整性状态或 GPU Broker 信息。证据消费者必须读取 /jobs 或 /jobs/{job_id} 中的 evidence_status 与 evidence_failures,不能用 observer 投影替代证据验收。
asr-smart.ps1 会在需要时启动本地 API,提交 job,并在 WaitSec 内等待结果。如果任务仍在运行,它会返回 job id 和下一步查询命令,而不是无限等待。
API 会在 outputs\api\jobs.json 中以原子替换保存任务历史:服务重启不会自动重跑任务,
重启前仍处于 queued 或 running 的 job 会保留为可查询的 service_restarted 失败终态。
持久化快照最多保留最近 200 条终态记录,同时保留活动/排队任务;裁剪历史不会删除原有转写输出文件。
若任务历史落盘失败,GET /health 会报告 persistence.status=degraded、ready=false,
后续新任务会被拒绝,直到一次后续状态写入成功恢复;命令已完成但终态历史不可持久时,
job 不报告为成功,且转写输出文件可能已经存在。
所有公开 CLI 和 smart/API 路径都必须先取得 LocalGpuBroker 租约;Broker 不可用时任务失败关闭,不会退回到仅凭 nvidia-smi 判断后继续重型推理。当前机器策略按工作族协调:ASR 与 OCR 可以并行,同一族任务串行,Ollama 重型请求/会话与 ASR、OCR 互斥。因此活动的 LocalOCR 本身不是 ChineseASR 的阻断理由,阻断状态必须以 Broker 返回的实际 owner/reason 为准。
默认 API 端口是 18666,刻意避开 LocalOCR 的 18665。旧客户端的 -AllowGpuConflicts / allow_gpu_conflicts=true 仍可被解析,但只影响没有机器级 Broker 的嵌入式外部 CUDA 进程检测,不能绕过本机 LocalGpuBroker。正式 Broker 只协调已接入它的 Ollama、LocalOCR 与 ChineseASR,不声称管理 LM Studio 等未接入进程。
ChineseASR 默认向 http://127.0.0.1:32100/_gpu_broker/* 申请 120 秒短租约,并在工作期间每 20 秒续期。启动 ASR/OCR 前会卸载受管 Ollama 驻留模型,但不会为了 ASR 主动停止 LocalOCR;跨族 ASR/OCR 租约可以同时存在。文件转写由监督进程取得租约,工作子进程携带 opaque token 验证后把租约绑定到自己的 Windows 进程创建身份,监督进程继续续租;监督进程消失时,进程句柄 watchdog 会终止对应 worker 并清理带作业标记的 WSL 子进程。确认成功结束的 worker 可能先被 Broker 按进程退出回收,这种正常竞态不会被误报为任务失败;运行中真正的续租失败仍会终止对应进程树,并以 gpu_broker_lost 失败关闭。
长音频入口:
.\scripts\asr-smart.ps1 -Audio C:\path\to\long.mp3 -Mode long-strict -WaitSec 15 -JsonChunkSec 是请求值,不是无条件采用的固定值。实际 effective_chunk_sec 会取请求值与两路引擎能力上限中的最小值;选择 FireRed 时为 35 秒,并始终低于其 40 秒单输入硬上限。每个 chunk 都跑 strict 双引擎。
MP3 等非标准输入先统一为 16 kHz、16-bit、mono PCM WAV。schema 2 的 manifest.json 记录源文件与派生文件 SHA-256、转换 provenance、模型配置 hash、固定模型/runtime 收据、运行代码身份、请求/有效切片参数、已解析引擎和 chunk 状态。内容与运行身份共同形成 fingerprint。续跑时不会只相信 manifest 的缓存状态,而会重新验证每个 chunk 的收据和全部内容;一致时才跳过,残留 running、内容篡改或身份变化都会转为重跑。
待处理 chunk 按两路引擎最小 max_request_inputs 分成有界批。FireRed 配置为每批最多 16 个输入;每个批次中,每个引擎只加载一次,再处理该批所有 chunk,避免逐片重复加载模型。
strict audit v2 保留两路引擎的原始文本、raw JSON 引用、provenance、分歧和人工复核项。选择策略固定为保留主引擎证据:不做多数投票,也不做语义改写。 新生成的 strict bundle 使用包内相对引用,并由 receipt 绑定六项内容产物;完整目录复制 到归档盘后仍可复验。旧版绝对引用在原位置继续兼容,但不会伪装成可搬迁包。
生成隐私友好的本地合成/对抗评测集:
.\scripts\eval.ps1 -Generate -GenerateOnly运行内置评测:
.\scripts\eval.ps1 -Generate -Force用自己的音频和人工 truth 文本跑 benchmark:
.\scripts\benchmark.ps1 -AudioDir C:\path\to\audio -TruthDir C:\path\to\truthbenchmark 按文件 stem 匹配音频和 truth,写 _manifest\manifest.json,不会复制你的源音频或 truth 文件。真实私人录音 benchmark 是校准手段,不需要提交到公开仓库。
当前唯一的离线备用在 E:\Projects\Tools\ChineseASR\offline\current\,属于 PCConfig 已登记的 ChineseASR 项目运行数据,不进 Git,也不由现有每日备份再复制到 G/H。它是防模型或依赖包上游撤包的本机备用;E 盘本身损坏时,这份备用也不可用。
备份从 configs/models.yaml 选择已安装、已接入适配器的引擎和支持模型:日常 quick/strict、high_quality 的 FireRed、显式 Paraformer、说话人模型和强制对齐器。另存 Windows 已安装环境及 FireRed WSL 隔离环境各自固定版本的 wheel、FireRed 固定提交的源码归档,以及源/副本 SHA-256 清单;不收下载缓存、示例、录音、转写正文或虚拟环境。两套 wheelhouse 的 Python/平台不同,不能混装。
模型或依赖升级并完成运行时验证后,在同一次升级流程里刷新备用:
.\scripts\refresh-offline.ps1该入口串起 export-lock.ps1(导出两套锁)、build-wheelhouse.ps1(下载并构轮)、模型源/副本 SHA-256 比对、verify-wheelhouse.ps1(整包封存与回读)和 install-offline.ps1(新建 E 盘 Windows 虚拟环境与 E 盘 Ubuntu 虚拟磁盘内的 WSL 环境,--no-index --find-links 安装、pip check、项目 doctor、FireRed WSL 导入检查)。全部通过后才把候选目录切为 offline\current,旧版放回收站;失败保留旧版。没有定时刷新或后台服务。只改默认路线而未升级权重时也刷新清单,使模型集合与配置一致。临时目录若因回收站容量无法回收,入口会保留并报告路径。
恢复时先运行 verify-wheelhouse.ps1 核对清单,再用 install-offline.ps1 -Venv <E盘新Windows虚拟环境> -RestoreModels -VerifyLinux -LinuxVenv /tmp/chineseasr-offline-<随机十六进制号> 安装依赖并补回缺失模型/FireRed 源码;WSL /tmp 位于本机 E 盘的 Ubuntu 虚拟磁盘内。已有但哈希不同的模型不会被覆盖。项目源码须先从可信 Git 副本恢复。若原 .venv 已不存在,给两个入口传 -HostPython <已恢复的同版本 Python 3.11 路径>;Ubuntu/WSL 的 Python 3.12 也须先可用。此验收检查依赖、配置和源码导入,不替代真实 GPU 推理、个人录音准确率或更换电脑后的完整恢复验收。
同一 adapter 内换模型,优先修改 configs/models.yaml;字段含义和已实现的适配器统一见 架构说明“引擎策略”。
临时使用其他配置:
$env:ZH_ASR_MODEL_CONFIG='C:\path\to\models.yaml'换模型后的基本验证:
.\scripts\download-models.ps1 -Engine <engine-name>
.\scripts\strict.ps1 -Audio C:\path\to\audio.wav
.\scripts\smoke-asr-smart.ps1 -Json新增不同运行时,例如新的本地语音模型或云 API,应新增 adapter,并保持 pipeline 只依赖统一的 generate(...) 输出形状。
单元测试不加载 ASR 模型:
.\.venv\Scripts\python.exe -m unittest discover -s testsParaformer 逐句时间的真实模型回归检查默认跳过;升级 FunASR 或 Paraformer 后显式运行。它把模型自带的公开示例音频重复三遍、中间隔 3 秒静音,用真实模型(默认 CPU,ZH_ASR_MODEL_TEST_DEVICE 可改)检查每句文字都落在自己的逐字时间上,并确认 FunASR 自带断句是否仍需重新对齐:
$env:ZH_ASR_RUN_MODEL_TESTS = '1'
.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_paraformer_sentence_timing_model.py"环境体检:
.\scripts\doctor.ps1端到端 smoke:
.\scripts\smoke-asr-smart.ps1 -Json公开发布前建议再跑:
git diff --check
git status --ignored=matching --short另外按公开发布流程对 README.md、docs、src、tests、scripts、configs 做 source-only 秘密模式扫描,确认没有 token、私钥、完整 .env、OAuth JSON、原始日志或私人输出内容。
仓库追踪:
src\zh_asr\scripts\configs\models.yamltests\docs\offline\manifests\
仓库不追踪:
.venv\models\outputs\eval\corpus\offline\current\、offline\staging-*\、offline\previous-*\(含各自模型与 wheelhouse)offline\wheelhouse\(旧入口遗留路径)- Python cache 和 build artifacts
这些目录可能包含模型权重、生成转写、私人音频路径、评测材料或大型 wheel 文件。
为什么 strict 比 quick 慢?
strict 会跑两路模型并写审计文件,目标是低幻觉和可复核;quick 只跑单模型。
为什么 smart 返回 blocked?
LocalGpuBroker 不可用、同族 ChineseASR 已在运行、Ollama 重型请求/会话占用协调域,或资源释放失败时都可能被阻断。LocalOCR 与 ASR 按当前策略可以并行,不应仅凭“有 OCR 在跑”判断冲突;以 Broker 返回的 owner/reason 为准。-AllowGpuConflicts 不会绕过机器级 Broker。
为什么正文里有 [疑似] 或 [听不清]?
这表示模型证据不足、两路分歧大、某一路失败或命中风险规则。正文不强装确定,细节看 strict.audit.md 和 strict.audit.json。
换更强模型要改代码吗?
通常不用。优先改 configs\models.yaml,只有新增运行时时才写 adapter。
云端 Key 的原始登记属于密码中心,共享副本由 PCConfig 的
E:\PCConfig\tools\vendor_key_copy.py 管理,保存为 E:\Data\VendorKeys\qwen.dpapi。
ASR 的正常请求只调用 load_key('qwen') 读取副本,HTTP 使用 Bearer 请求头,WebSocket
使用握手鉴权;明文不进参数、请求 JSON、正文或日志。cloud_review.py 继续准备 HTTP body
和 WebSocket 帧,切段、声道、模型、热词及业务用途判断仍归 ASR,不随传输重新登记。
只有 HTTP 401 或厂商明确报无效 Key 时,才调用共享模块
sync_key('qwen', validate=callback):只读取得候选,先在内存重试本次已知失败请求,
成功才原子替换同名副本。候选请求失败时旧文件不变,回执保留具体 cloud_key_refresh_*
或 cloud_key_sync_* 原因;每次只同步一次。网络结果未知、超时、限流或其他错误不触发刷新。
候选转写已成功但保存副本失败时保留成功稿件,key_copy_sync 记录保存结果,不重传。
手动同步与 stdin 导入由 PCConfig 的共享工具负责,未验证候选不替换副本。
对话来源的资料期仍经既有 CheckPersonalDataAccess 只读查询,自行启动的后台任务按上述来源标记免查资料锁;这项查询保留,不代表云请求仍经密码中心发送。
一次调用保留 <job_id>.intent.json、<job_id>.unclaimed.json、.provider.json 和检查点。
再次运行同样的云入口命令时,会按音频 SHA-256、用途、声道、模型及请求参数接续未完成作业,
沿用原作业 ID 和请求;也可用 -ResumeJobId <原作业 ID> 指定,参数不一致时会说明无法续作。
已经成功的 operation 由 ASR 检查点跳过,不重发,兼容原传输留下的摘要和成功记录。
previous_outcome_unknown 表示服务端是否完成尚不清楚,不自动重发或新建作业;
请求体、模型及音频摘要仍保留供核对。
成功作业的原始录音、最终正文和云回执保留,生成的 .work 切段与 Base64/PCM 中间副本会清理;
失败、未完成或原始录音已不在的作业继续保留中间文件。空文字或 ASR_RESPONSE_HAVE_NO_WORDS
在结果中标为单段“无语音”;中途停下而后续段尚未处理时,整份仍保留失败状态。
回退本次传输改动使用 Git 恢复源码和配置;副本的手动同步或停用由 PCConfig 共享工具维护, 不要求重装、重载密码中心。