dsh-voice-transcribe：本地語音/視頻轉寫

前言¶

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 調用、本地即可運行的方案。

插件目錄 | GitHub 倉庫