前言¶
DeepSeek Harness (DSH) 的核心设计是“一切皆插件”。在开发需要理解语音的智能体时，输入格式的解析往往是第一道坎。QQ 和微信发送的语音文件通常带有 #!SILK_V3 头，且文件名常被错误标记为 .amr。大多数环境下的 ffmpeg 缺少 SILK 解码器，导致无法处理。
dsh-voice-transcribe 是一个本地语音/视频转写插件，由 JackZo400 维护。它通过 SILK 解码器和 SenseVoice 引擎（基于 sherpa-onnx int8 模型），将 QQ/微信语音转成文字。整个过程在本地运行，不消耗 API 费用。
核心功能¶
- SILK 音频解码：处理 QQ/微信特有的 SILK 编码格式。
- SenseVoice 本地转写：使用 int8 精度的 SenseVoice 模型进行高精度识别。
- 无需 API 费用：全流程本地推理。
- 批量处理：支持一次传入多个文件，模型加载一次复用。
- 专有名词纠错：通过配置表修正识别错误。
安装与启用¶
1. 安装插件¶
在 DSH 环境中执行以下命令安装：
dsh plugin --profile web add github:JackZo400/dsh-voice-transcribe
2. 安装 Python 依赖¶
安装 Python 依赖包（需安装在 pythonPath 指定的解释器中）：
pip install -r py/requirements.txt
注意：清华源通常没有 sherpa-onnx，安装失败请使用阿里源或官方源：
pip install -i https://mirrors.aliyun.com/pypi/simple -r py/requirements.txt
3. 系统依赖¶
系统需安装 ffmpeg，用于处理非 SILK 格式的音频/视频转码。
4. 下载模型¶
下载 SenseVoice 模型（约 163 MB 压缩包，解压后约 239 MB int8 模型）：
curl -LO https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17.tar.bz2
tar xjf sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17.tar.bz2
解压后的目录（如 sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17）即为模型目录，需在配置中指定路径。
配置¶
在 DSH 的配置文件中添加以下内容：
- insert:
- id: voice-transcribe
name: dsh-voice-transcribe
config:
pythonPath: python3 # 你的 Python 解释器路径
modelDir: /path/to/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17
maxSeconds: 120 # 仅转写前 N 秒
language: auto # auto / zh / en / ja / ko / yue
fix: '' # 专有名词纠错表
maxFiles: 4 # 一次最多转写的文件数
配置说明：
* modelDir：也可通过环境变量 AILIN_ASR_SV_DIR 设置。代码中不包含写死的路径，必须显式配置。
* fix：专有名词纠错表。格式为 错=对,错=对，从左往右替换。默认为空。
用法¶
在 DSH 中调用¶
安装后，Agent 会获得 transcribe_media 工具。可传入单个或多个文件路径：
// JavaScript 示例
const svc = ctx.get('voiceTranscribe');
const { results } = await svc.transcribe(['/tmp/voice.amr']);
// 返回包含 file, ok, text, language, duration 的结果
单独使用 Python 脚本¶
若需单独调试，可直接使用插件提供的 Python 脚本。
- SILK 解码：
python py/silk.py voice.amr --out-dir out/
输出为标准的 16k 单声道 WAV 文件。
- SenseVoice 转写：
python py/transcribe.py zh.wav --language zh --model-dir /path/to/model
输出为 JSON 格式。
性能数据（实测）¶
- 模型体积：239 MB (int8)。
- 单条耗时：约 0.1 秒（1.7 秒语音样本）。
- 加载耗时：约 0.9 秒（仅加载一次）。
已知局限¶
- 文件来源：仅支持本地文件，不支持 URL（避免 SSRF 风险）。
- 视频处理：只转音轨，不抽帧。
- 语言限制：仅支持 5 种语言（zh/en/ja/ko/yue）。
- 长音频：超过 28 秒会自动切片，切点偶尔可能打断词语。
- 幻觉风险：纯静音或纯音乐可能产生无意义的字。
- 名词纠错：SenseVoice 无词表接口，专有名词纠错需依赖
fix配置表。
结语¶
dsh-voice-transcribe 专为解决 IM 场景下的语音解析问题设计。如果你正在开发基于 DeepSeek Harness 的智能体，且需要处理 QQ 或微信语音，这是一个无需 API 调用、本地即可运行的方案。
