Skip to main content
C

dsh-asr-openai

caiccc-a11y/dsh-asr-openai

可以直接本地调用DSH内置语转文模型的插件,支持openai标准格式。

Install

dsh plugin --profile web add github:caiccc-a11y/dsh-asr-openai

README

DSH 语转文插件(OpenAI 兼容接口)

让 AstrBot / Open WebUI / LangChain / 官方 openai SDK 等任何 OpenAI 兼容客户端, 直接调用 DSH 内置的本地 SenseVoice 语音转文字模型。

DSH 自带的语转文只提供给浏览器(ctx.speechToText + /api 的 Remote 通道,音频走 base64), 没有 OpenAI 的 /v1/audio/transcriptions。本插件在 DSH 的 Web 服务器上补出这一层。

接口

方法路径说明
POST/v1/audio/transcriptionsmultipart:file(音频)、model、language、response_format
POST/v1/audio/translations同上(不翻译,等价于转写)
GET/v1/models识别器清单(OpenAI 列表格式)
GET/v1/models/{id}单个识别器
GET/v1/health存活 + 各识别器准备状态
  • 鉴权:Authorization: Bearer sk-local(也接受 x-api-key),常量时间比较。
  • response_format:json(默认,{"text":"..."})、text、srt、vtt、verbose_json。
  • 音频格式不限(mp3 / wav / m4a / ogg / webm / flac ...),内部用 ffmpeg 统一转 16 kHz 单声道 PCM16。
  • 超长音频自动按 segmentSeconds(默认 60 秒)切片,逐段识别后拼接文本。
  • model 写 sensevoice-local 最准确;写别的名字(例如 whisper-1)会退回该 profile 的默认识别器,方便照抄 OpenAI 客户端配置。
  • 语言:auto / zh / en / yue / ja / ko,也接受 zh-CN、en-US 一类写法,自动映射。

安装

仓库:https://github.com/Caiccc-a11y/dsh-asr-openai

方式一:从 GitHub 拉取(推荐)

git clone https://github.com/Caiccc-a11y/dsh-asr-openai.git ~/dsh-asr-openai
bash ~/dsh-asr-openai/install.sh          # 默认接入 web profile
bash ~/dsh-asr-openai/install.sh myprofile  # 或指定 profile

install.sh 会把它以 link: 形式加进 ~/.dsh/profiles/<profile>/package.json 的 dependencies, 并追加到 dsh.profile.bundles(原文件备份为 package.json.bak)。

方式二:手动接入(与脚本等价)

  1. 插件目录:本仓库根目录(例如 ~/dsh-asr-openai)。
  2. 在 ~/.dsh/profiles/web/package.json 里:
    • dependencies 增加 "@local/dsh-asr-openai": "link:/绝对路径/dsh-asr-openai"
    • dsh.profile.bundles 增加 "@local/dsh-asr-openai"
  3. 重启 DSH 生效(插件层只在启动时组合):
    systemctl --user restart dsh-web.service
    # 或在 DSH 里执行 /dsh-restart
    
  4. 自检:
    curl -s -H 'Authorization: Bearer sk-local' http://127.0.0.1:3080/v1/models
    curl -s -H 'Authorization: Bearer sk-local' http://127.0.0.1:3080/v1/health
    curl -s -H 'Authorization: Bearer sk-local' \
         -F 'file=@/path/to/audio.wav' -F 'model=sensevoice-local' \
         http://127.0.0.1:3080/v1/audio/transcriptions
    

AstrBot 配置

AstrBot 自带的 OpenAI Whisper API(openai_whisper_api)就够用,不必装额外插件。 在 AstrBot 面板 → 服务提供商 → 新增 → 类型选「语音转文字 / OpenAI Whisper API」,填:

字段值
API Keysk-local
API Base URLhttp://127.0.0.1:3080/v1
模型sensevoice-local

AstrBot 与 DSH 在同一台机器时用 127.0.0.1;AstrBot 在容器/另一台机器时, 换成 DSH 的局域网地址,例如 http://192.168.1.43:3080/v1。

对应到 AstrBot 的 provider 配置,等价于:

{
  "type": "openai_whisper_api",
  "api_key": "sk-local",
  "api_base": "http://127.0.0.1:3080/v1",
  "model": "sensevoice-local",
  "enable": true
}

配置好后,在 AstrBot 的「语音转文字」设置里选中该 provider;QQ/微信语音消息会被自动转成文字。

配置项(profile 的 cordis.patch.yml)

- id: asr-openai
  config:
    apiKey: sk-local        # 共享密钥;改这里同时改 AstrBot 的 API Key
    requireApiKey: true     # false 则不校验(仅建议在纯本机回环时)
    maxUploadBytes: 33554432
    segmentSeconds: 60
    ffmpegPath: ffmpeg      # 可写绝对路径,避免 systemd 下 PATH 差异
    ffmpegTimeoutMs: 120000
    transcriptionTimeoutMs: 300000

排错

现象原因 / 处理
401 invalid_api_keyAstrBot 里的 API Key 与插件 apiKey 不一致
503 ... registry is not mounted该 profile 没启用 @deepseek-ai/dsh-experimental-voice-input-bundle
503 No speech provider is registeredSenseVoice 插件没激活;检查 /v1/health 的 providers
Invalid speech WAV旧版本问题,已修复(改为自行构造规范 WAV 头)
第一次转写很慢模型冷启动(约 1 亿参数 INT8),之后 worker 常驻,idleTimeoutMs 默认 5 分钟
模型目录/home/cai/.dsh/speech-to-text/sensevoice/models/sensevoice-onnx(229 MB)

设计要点

  • 只用 ctx.webServer.register({ kind: 'prefix', path: '/v1' }),handler 独占响应生命周期。
  • 鉴权独立于 DSH 的浏览器 token 体系:服务端调用方没有 DSH 会话 cookie。
  • multipart 解析用平台自带的 Response.formData(),音频解码用系统 ffmpeg,零依赖。
  • ffmpeg 只做解码(-f s16le pipe:1),WAV 头由插件按 SpeechProvider 的严格校验逐字节构造, 避免封装器写入额外 chunk 导致 Invalid speech WAV。
  • 失败一律返回 OpenAI 形状的错误体 {"error":{"message","type","code","param"}}, 客户端 SDK 能给出可读信息而不是解析异常。

在插件管理器里的显示

包内 locale/zh.json、locale/en.json 提供卡片标题与说明,icon.svg 提供图标:

{ "meta": { "title": "DSH 语转文接口", "description": "把 DSH 内置 SenseVoice 语音识别暴露成 OpenAI 兼容接口,AstrBot 等第三方客户端可直接调用。" } }

package.json 需同时导出这三个资源,DSH 才能在不执行插件代码的前提下读取它们:

"exports": {
  ".": "./index.js",
  "./locale/*.json": "./locale/*.json",
  "./icon": "./icon.svg"
}

注意:Node 的 ESM 解析器会缓存包的 package.json。若这些导出是在 DSH 进程启动之后才加上的, 插件管理页要等 DSH 重启后才会显示标题与图标(接口本身不需要重启也能用)。

Related plugins