StreamPA 使用说明

这是冻结的 Ours-M / M_stress_scalar_gate_capacity64，默认 seed 1337。它不是旧版 v6 的 47 维 Streaming GOPT。发布的是可下载运行的多组件系统，不是 HF 网页在线推理服务，也不提供虚构的 Transformers AutoModel 接口。

原 checkpoint SHA256： 870df8dbe3c787487f094e0c4d4ade6bed8fcc5d86b578c4edc57581e81023b4。 model_manifest.json 记录发布 tensor、配置、源文件和各组件身份。 scorer 的全部原 tensor 保留为 safetensors，没有训练、微调、量化或修改值。

安装

实际验证环境是本机 Windows 的 Ubuntu WSL2，Python 3.10，CPU FP32。没有将服务器 Linux 测试写成 Windows 原生测试。Windows 原生和 CUDA 尚未验证。首次需要联网安装依赖和下载官方固定版本的 Charsiu、词典与 NLTK 资源。

python3.10 -m venv .venv-streampa
source .venv-streampa/bin/activate
python -m pip install huggingface_hub==0.36.0
python -c "from huggingface_hub import snapshot_download; snapshot_download('faeea/StreamPA', revision='streampa-v1.0.0', local_dir='./StreamPA')"
cd StreamPA
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements-lock.txt
python -m pip install --no-deps --no-build-isolation .
python scripts/setup_assets.py
python scripts/verify_bundle.py

Charsiu 权重未在本仓库重新分发，由 setup 从官方固定 revision 下载并验 hash。微调 Whisper Base 则已在包内，不能替换为通用预训练 Whisper。各组件并非同一许可证，详见 THIRD_PARTY_NOTICES.md。初始安装若需要网络代理，由用户环境设置，包内不包含作者 token、代理密码或服务器路径。

最短完整推理

输入自己的英文、单声道、16 kHz WAV，不输入参考文本、音素数、GT 边界、分数或 teacher。输出文件必须不存在，以免覆盖旧结果。

python -m streampa.infer --audio /path/to/demo.wav --bundle-dir . --device cpu --output scores.json
python -m streampa.stream --audio /path/to/demo.wav --bundle-dir . --device cpu --output prefixes.jsonl

单音频命令返回全部 prefix 和 EOF 分数；流式命令逐块读取音频，经过相同的调度和计算。最大原始音频长度为 30 秒，最大当前 PCN 槽位数为 72。超限明确拒绝，不静默截断。实际运行路径：收到的 prefix 音频 -> 微调 Whisper N-best -> G2P、Charsiu、PCN、prosody -> StreamPA。没有用预计算预测代替模型运行。

会话 API

from streampa import StreamPAPipeline
pipeline = StreamPAPipeline('./StreamPA', device='cpu', threads=2)
session = pipeline.create_session()
# block 是实际已收到的、16 kHz 单声道 float32 波形数组
for result in session.append(block):
    print(result)
print(session.current())
print(session.finish())  # 调用方 EOF，处理最后不足一个 chunk 的音频
session.reset()          # 新录音前必须重置，清空音频、提交历史和 GRU state

完整可执行逐块示例：python examples/session.py --bundle-dir . --audio demo.wav。不同 session 的 state 独立；当前包不提供多线程服务调度，建议顺序调用。

如何读输出

commit_time 每 0.64 秒推进，普通 prefix 等收到额外 0.16 秒 lookahead 才处理。 audio_end 是每个前端实际得到的波形末端；received_audio_end 可能因整块到达而更晚，但前端不能读取更晚部分。EOF 由调用方决定，不从参考标注推导。
slots 保留原始独立 phone head 与 word head 输出、当前 ASR 词归属、时间、mask。 epsilon/gap 槽位保留；valid_phone=false 时不能作为有效局部音素评分。
words 按当前 ASR word ID，平均该词可见槽位的 word head 输出用于显示。不是平均 phone accuracy，不等同论文按 reference word ID 的共同单元评价。
GRU 只消费 new_commit_mask 对应的新词。没有任何新词时 persistent state 不变，但 visible 表示仍进入句级 head，所以句级分数仍可能变化。已提交词不代表其评分永远不变。
保留冻结的 legacy commitment，包括复杂 mixed merge 下的已知限制。不声称“每一个完成词均有形式化 exactly-once 保证”，没有偷偷换成 corrected 规则。
原训练把源标签除以 5；词和句源尺度为 0--10、音素源尺度为 0--2。显示成 0--5 时，词/句网络输出乘 2.5，音素网络输出乘 12.5。不裁剪超界估计。原始网络输出同时保留。completeness 未参与训练，只在 raw 审计字段保留，不显示为可靠评分。
非 ok 状态给 scores=null，包括空音频、静音、无可用假设、对齐失败、超限等。不用零分代替失败，不静默删掉失败 prefix。ASR confidence 也不等于“读对的概率”。

离线和性能

python scripts/setup_assets.py --offline
HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 python -m streampa.infer --audio demo.wav --bundle-dir . --device cpu --output offline_scores.json
python -m pytest tests -q

离线复制时保留整个已准备好的 bundle，包括 setup 产生的 charsiu/ 与 assets/nltk_data/。依赖缺失先补 setup，不要用别的权重替换。 stages 分开记录前端与 scorer 的计算时间；不把文件读取测试声称为包含真实采集等待的端到端实时实验。CUDA 分支保留原 Whisper FP16 行为，Charsiu/scorer FP32，但尚未验证。

论文与部署边界

发布 seed 1337 不等于论文四 seed 均值。接口测试音频不证明论文 PCC。训练使用人工监督和 teacher；历史评测样本经过预处理筛选，主要来自朗读数据。部署移除了历史参考音素长度比例筛选，并使用 audio/EOF 调度；这一差异已明确记录，不声称任意 WAV 会复现历史样本集合和指标。词典只是通用词到音素的静态资源，不按当前录音读取其标准文本。未验证自发开放回答泛化，不宣称 GRU/稳定性 loss 的直接稳定性机制已获得证明。

旧 v6 历史版本保留在 faeea/StreamPA 的 legacy-v6-before-streampa revision；其权重、结构和调用方法不能与本包混用。实际已通过和未测试项目见 validation_summary.json。