xasr-official-onnx-contextgraph-ab-v1

X-ASR ONNX ContextGraph 后端交付包

版本：xasr-official-onnx-contextgraph-ab-v1
平台：Linux x86_64、macOS arm64（Apple Silicon）、Windows x86_64 三个归档、Python 3.12、CPU
默认端口：18766

0. 选择平台归档

三个归档的代码、ONNX 模型和依赖版本完全一致，只有 wheelhouse/ 不同。

当前归档为 v1.3.0（2026-08-27），在 v1.2.0（剪枝前加分 boost_mode=pre + score 默认 4）基础上修复英文热词构图缺陷并重标 score 刻度：

• 英文热词修复：此前热词入图前会被大写化，而交付 ONNX 使用真大小写词表，大写英文掉出词表后回退为逐字母 token，使按 token 累计的加分随词长线性放大并污染 beam（表现为英文热词召回改善但整体 WER 明显变差，中文不受影响）。现改为保留真实大小写、并行挂载多个大小写变体，并按单位数（汉字数 + 英文词数）归一化每个热词的总加分。中文链路的图结构与加分数值与 v1.2 严格一致。
• score 刻度重标：pre 模式上限由 8 收紧为 6，且会话级 score 与单词覆写同时受限（v1.2 仅限制覆写）。默认仍为 4；近音陷阱场景建议覆写到 6（v1.2 同场景需 8）。破坏性变更：boost_mode=pre 且 score 为 8 的请求现在会被 API 拒绝。
• boost_mode=post 保留 v1.1 行为，覆写范围仍为 1–16。

详见包内 API.md 与 VALIDATION.md（v1.3.0 章节含完整根因、刻度扫描依据与已知边界）。三个归档各有 sidecar .sha256，下载后先校验：

sha256sum -c xasr-official-onnx-contextgraph-ab-v1-<platform>-py312.tar.zst.sha256
zstd -dc xasr-official-onnx-contextgraph-ab-v1-<platform>-py312.tar.zst | tar -x

这个包就是当前生产 18766 使用的版本，包含：

• X-ASR 官方 punctuation/casing ONNX，160/480/960/1920 ms 四档；
• 与每一档严格匹配的 tokens.txt；
• punctuation SentencePiece 模型；
• 官方 OnlineFbank、segment/offset、encoder state 流式路径；
• 官方 greedy Plain decoder；
• 复用同一次 encoder 输出的 modified-beam + icefall fine-grained ContextGraph 热词 decoder；
• Web 页面、WebSocket API、健康检查、离线 Python wheelhouse 和校验清单。

注意：这里没有微调 checkpoint。热词侧沿用官方 released ONNX 权重，只扩展推理解码；X-ASR 官方仓库本身不原生支持动态热词。

后端工程师或代码代理接手前请先阅读 AGENT.md，其中固定了模型文件匹配、性能口径、生产数据治理和修改后的重打包门禁。

1. 校验交付包

python3 verify_package.py

成功时输出 package verification passed。不要混用不同 chunk 目录中的 encoder、decoder、joiner 或 tokens。

2. 直接启动

要求 Python 3.12。wheelhouse 与所选归档平台一致（Linux x86_64 或 macOS arm64）、CPython 3.12 构建。macOS 上必须使用原生 arm64 Python 3.12（如 brew install [email protected]），不要在 Rosetta x86_64 Python 下安装。

python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install --no-index --find-links wheelhouse -r requirements.txt
./start.sh

可用环境变量：

XASR_HOST=0.0.0.0 XASR_PORT=18766 ./start.sh

启动后检查：

curl --noproxy '*' http://127.0.0.1:18766/api/health

健康信息中的关键字段应为：

{
  "service_version": "xasr-official-onnx-contextgraph-ab-v1",
  "runtime": "onnxruntime + kaldi-native-fbank",
  "plain_decoder": "official greedy_search",
  "encoder_shared_between_lanes": true
}

3. Docker 启动

docker build -t xasr-hotword:v1 .
docker run --rm -p 18766:18766 xasr-hotword:v1

Docker 构建默认使用包内 wheelhouse，不从 PyPI 下载依赖。基础镜像为 python:3.12-slim。仅 Linux x86_64 归档含 Dockerfile；macOS / Windows 归档的 wheelhouse 无法在 Linux 容器内安装，请原生启动。

4. 调用方式

完整协议见 API.md。最小 WAV 客户端：

python examples/ws_wav_client.py \
  --url http://127.0.0.1:18766/ws \
  --wav /path/to/16k-mono-pcm16.wav \
  --hotword 模思智能 \
  --hotword 阶跃星辰 \
  --hotword 智谱

输入必须是 16 kHz、单声道、PCM16 little-endian。推荐每个 WebSocket binary frame 发送 512 samples（1024 bytes）。音频没有 30 秒上限。

5. 推荐参数

• latency_ms=480：默认平衡档；
• boost_mode=pre、hotwords_score=4（v1.3.0 默认）；
• max_active_paths=8；
• 建议每次 1–20 条热词。

pre 模式下加分参与 beam 剪枝竞争，量纲比 post 敏感：4 是默认甜点位，6 用于近音陷阱场景，超过 6 会被 API 拒绝（8 实测会把已匹配热词重复刷出，16 导致整句雪崩）。boost_mode=post 为 v1.1 兼容模式（建议 8，覆写上限 16，不要全局 10/12）。

需要单独加强某几条热词时，用单热词覆写："模思智能:6" 或 {"text": "模思智能", "score": 6}。热词表存在互为近音的词时，把关键热词覆写到 6 可避免被近音词抢占（验收依据见包内 VALIDATION.md）。

英文热词按你填写的形式书写即可（不必大写）；召回结果的大小写会跟随模型输出形态，指标经大小写归一不受影响。

6. 性能与已知边界

• 68.256 秒保存音频：直接运行时双路推理 13.062 秒、RTF 0.1914；正式 WebSocket/独立 wheelhouse 验收为 0.1968/0.2111；
• 21.696 秒保存音频：双路 RTF 0.2104；
• 614.304 秒（10.238 分钟）连续双路回放：推理 121.090 秒、RTF 0.1971；
• 默认 480 ms 单档模型文件约 586.1 MiB，进程常驻主存约 1.0 GiB；当前运行时固定 CPU，GPU 显存为 0；
• Plain 在已验收音频上与官方 sherpa high-level 服务逐字一致；
• 热词不是强制替换，声学证据过弱时仍可能不命中；
• 进程内通过全局锁串行推进模型 chunk。需要并发时建议多副本水平扩容，并保证同一个 WebSocket 会话始终落到同一副本；
• 非默认延迟档第一次使用会懒加载对应 ONNX，冷启动约 2 秒；
• 160 ms 延迟最低但 CPU RTF 更高，1920 ms 更快但短音频质量不保证单调提升。

完整的四档速度、Plain/双路开销、长音频、主存、CUDA 显存估算和端侧适配矩阵见 EDGE_DEPLOYMENT_BENCHMARK.md。其中 GPU 数字是移植预算估算，不是当前包实测；可直接部署的平台是 Linux x86_64 CPU、macOS arm64 CPU 与 Windows amd64 CPU。以上 RTF/内存数字在 Linux x86_64 上实测，Apple Silicon 与 Windows 请用 tools/benchmark_xasr_delivery_runtime.py 复测（Windows 上 benchmark 的内存字段返回 null，请用任务管理器观察）。

7. 文件结构

assets/base_model/deployment/models/        四档官方 ONNX 与 tokens
tools/xasr_onnx_contextgraph_ab_demo.py      正式服务
tools/benchmark_xasr_delivery_runtime.py     CPU/内存/长音频复现基准
tools/xasr_official_demo.py                  HTTP/WS 公共协议与页面
vendor/icefall/icefall/context_graph.py      fine-grained ContextGraph
vendor/X-ASR/.../bpe_punc.model              标点词表 SentencePiece
examples/ws_wav_client.py                    后端调用示例
requirements.txt / wheelhouse/               固定依赖与离线 wheels
MANIFEST.sha256 / verify_package.py           文件完整性校验
AGENT.md                                      后端维护与代理接手约束

运行中用户音频和 JSON 会写入 runs/xasr_hotword_demo/user_cases/。后端需要为该目录配置持久卷、容量限制和数据保留策略；如涉及生产隐私，请按业务规范加访问控制或关闭外部采集。