astrbot_plugin_volcengine_asr

AstrBot 火山引擎语音转文字插件

“让文字不再是文字，让语言不只是语言”

把 QQ 语音变成 AstrBot 可以理解、记忆、推理并继续回复的用户输入。

_{小鞠在 README 门口值班：提醒维护者讲清主线能力，别让 bugfix 淹没文档。}

当前正式版：2.2.2

2.2.2 是 2.2.0 正式版上的小版本 bugfix。它不改变 2.0.0 建立的主线能力：QQ / NapCat 语音进入 AstrBot 后，仍然会被转写成干净文本，再进入 LLM、上下文、LivingMemory 与后续插件流程。

这版主要更新：

验证记录：

一句话概括：2.2.2 是“2.2.0 正式主线 + on_llm_request 参数兼容修复”的稳定小版本。

项目定位

astrbot_plugin_volcengine_asr 是一个面向 AstrBot 的 QQ 语音输入适配插件。它监听 OneBot v11 / NapCat 传入的 Record 语音段，读取、下载或转码音频，然后调用火山引擎豆包语音“大模型录音文件极速版识别”接口，把语音转写成文本。

但它的目标不是“收到语音后机械回复一条转写结果”。它真正要做的是：

让 QQ 语音像普通文字消息一样进入 AstrBot 的 LLM、上下文、记忆、TTS 与后续插件流程。

这意味着插件必须同时处理四件事：

所以，本插件更像一个“语音输入适配层”，不是一次性的 ASR 小工具。理想链路是：

用户发送 QQ 语音
  -> 插件识别语音内容
  -> 插件把转写文本注入为干净用户输入
  -> AstrBot 像处理文字消息一样继续调用 LLM
  -> 记忆、上下文、TTS 和其它插件继续按原流程工作

一个典型 OneBot / NapCat 语音段看起来像这样：

Record(file="32c1124cf292f19c30728a54db34992e.amr")

这个 file 很多时候不是 AstrBot 容器内真实存在的文件路径，而是 OneBot / NapCat 的语音资源标识。如果它被 AstrBot 官方预处理或后续 agent 当作本地文件读取，就可能出现：

not a valid file: xxx.amr

因此，插件的主要价值不只是调用一次火山 ASR API，而是把语音安全地转换成后续组件能消费的文本输入，并尽量让旧媒体对象不要继续污染 LLM 请求、ProviderRequest、agent cache 或 run context。

核心能力

快速开始

方式一：上传 Release zip

这是最推荐的安装方式，尤其适合 Docker、VPS、宝塔面板和不方便手动安装 ffmpeg 的环境。

1. 打开 GitHub Releases。
2. 下载附件 astrbot_plugin_volcengine_asr.zip。
3. 进入 AstrBot WebUI 的插件页面。
4. 选择从文件安装。
5. 上传这个 zip。
6. 重载插件或重启 AstrBot。
7. 打开插件配置页，填写火山引擎鉴权信息。

重要提醒：

Release zip 固定为单顶层目录结构：

astrbot_plugin_volcengine_asr/
├── metadata.yaml
├── main.py
├── _conf_schema.json
├── requirements.txt
├── README.md
├── CHANGELOG.md
├── assets/
├── bin/linux-x86_64/ffmpeg
└── third_party_licenses/

方式二：从仓库安装

在 AstrBot WebUI 中使用仓库地址：

https://github.com/Ayleovelle/astrbot_plugin_volcengine_asr

如果 WebUI 需要 .git 后缀，也可以使用：

https://github.com/Ayleovelle/astrbot_plugin_volcengine_asr.git

仓库安装会读取仓库根目录的 metadata.yaml、main.py、_conf_schema.json 和 requirements.txt。但仓库安装不等同于 Release zip 安装：仓库根目录不一定带 Release 包内置的 bin/linux-x86_64/ffmpeg，因此会依赖 imageio-ffmpeg 或系统 PATH 中的 ffmpeg。

最小配置

火山引擎侧需要先开通豆包语音识别能力。新版控制台通常只需要 api_key；旧版控制台可以使用 app_key + access_key。

推荐最小配置：

api_key = 你的火山引擎 API Key
resource_id = volc.bigasr.auc_turbo
submit_mode = base64
enable_transcode = true
prefer_bundled_ffmpeg = true
inject_as_user_input = true
reply_transcription = false
enable_emotion_analysis = false

安装后在聊天中发送：

/volc_asr_status

重点确认：

调试模式

如果只想确认 ASR 是否通，可以临时打开：

reply_transcription = true

这样插件会直接回复转写结果，方便排查火山鉴权、音频读取和 ffmpeg。确认主链路可用后，建议改回：

reply_transcription = false
inject_as_user_input = true

语音工作流

下面是当前主链路。它不是单纯“收到 Record -> 调 API -> 回文字”，而是多阶段地把语音变成可被 AstrBot 后续流程安全消费的输入。

五个核心对象

为什么要多次清理

真实部署里，旧语音对象可能藏在很多地方：

event.message
event.message_chain
event.raw_message
event.extras
event.message_obj.extras
provider_request.messages
provider_request.extra_user_content_parts
run_context.stage_data
run_context.cache
其它插件写入的临时上下文

插件会在消息处理成功后清理一次，并在 on_agent_begin 再兜底清理一次。这样做的目标是减少后续 agent_sub_stages 再次扫到旧 Record(file="xxx.amr") 的概率。

2.0.0 情绪层

v2.0.0 是这个插件的核心能力版本。它引入的不是心理诊断，也不是让另一个模型替用户下结论，而是一个可选的、结构化的、受权重约束的“语气参考层”。

默认关闭：

enable_emotion_analysis = false

开启后，每条成功识别的语音会额外调用一次 LLM。该 LLM 只负责输出结构化 JSON，主 LLM 只按 respect_weight 有限参考它，不把它当作事实。

工作流

情绪算法并非凭空捏造

这里是本文档最贴近论文的部分。我个人在审核的过程中直接看力竭了；这部分选择不看、跳过，也不影响插件的使用。

插件的情绪算法不是凭空捏造。它把三个相对稳定的思想工程化地组合起来：

离散标签方便 LLM 写提示词；valence/arousal 让结果不只停留在标签名；熵和证据项用于防止“模型说得很像真的”就获得过高影响力。

JSON 输出

情绪判断 LLM 的目标输出：

{
  "label": "anxious",
  "emotion_weights": {
    "anxious": 0.72,
    "neutral": 0.28
  },
  "confidence": 0.68,
  "valence": -0.35,
  "arousal": 0.62,
  "voice_text_support": 0.80,
  "context_support": 0.30,
  "reason": "语气显得担心"
}

字段约束：

respect_weight 公式

下面的公式使用 GitHub 支持的 math 代码块渲染。若在不支持 GitHub 数学表达式的 Markdown 查看器中阅读，可以直接看后面的纯文本 fallback。

令：

• $t$：转写文本字符数。
• $c$：情绪 LLM 输出的 confidence。
• $p_i$：归一化后的第 $i$ 个情绪权重。
• $n$：有效情绪标签数。
• $s_v$：voice_text_support。
• $s_c$：context_support。
• $r_{\max}$：emotion_max_respect_weight_percent / 100。

情绪分布的 Shannon 熵为：

H(\mathbf{p}) = -\sum_{i=1}^{n} p_i \log(p_i)

归一化确定性为：

C(\mathbf{p}) =
\begin{cases}
1, & n \le 1 \\
1 - \dfrac{H(\mathbf{p})}{\log n}, & n > 1
\end{cases}

文本长度因子为：

L(t) = \min \left(1,\frac{\log(1+\max(0,t))}{\log 81}\right)

证据强度为：

E = L(t)\left(0.7s_v + 0.3s_c\right)

经过置信度与证据门控后的确定性为：

C'(\mathbf{p}) = C(\mathbf{p})\max(c,E)

最终参考权重为：

r = r_{\max}\left(0.5c + 0.3C'(\mathbf{p}) + 0.2E\right)

短文本保护规则：

r_{\text{short}} =
\begin{cases}
\min(r,0.25), & t < 12 \\
r, & t \ge 12
\end{cases}

最终输出：

\mathrm{respect\_weight}
= \mathrm{round}\left(\mathrm{clip}(r_{\text{short}},0,r_{\max}),3\right)

非 GitHub 渲染器的纯文本 fallback：

certainty = 1 - entropy(weights) / log(label_count)
length_factor = min(1, log(1 + transcript_chars) / log(81))
evidence = length_factor * (0.7 * voice_text_support + 0.3 * context_support)
certainty = certainty * max(confidence, evidence)
respect_weight = max_respect_weight * (0.5 * confidence + 0.3 * certainty + 0.2 * evidence)
if transcript_chars < 12:
    respect_weight = min(respect_weight, 0.25)
respect_weight = round(clamp(respect_weight, 0, max_respect_weight), 3)

为什么这样设计

这套公式的目标不是“算准用户真实情绪”，而是控制主 LLM 的参考强度：证据充分、分布集中、置信度高时多参考；证据弱、文本短、分布散时少参考。

情绪公式接口

从 v2.1.8 开始，情绪权重公式被抽成接口：

class EmotionWeightingPolicy(Protocol):
    def compute_respect_weight(self, data: EmotionWeightingInput) -> float:
        ...

默认实现是 DefaultEmotionWeightingPolicy。后续分支如果要改公式，只需要提供新的 policy：

class MyEmotionWeightingPolicy:
    def compute_respect_weight(self, data: EmotionWeightingInput) -> float:
        return 0.0

plugin.emotion_weighting_policy = MyEmotionWeightingPolicy()

这样可以避免把实验公式直接写进主 ASR 流程，降低后续维护风险。

Token 与延迟风险

情绪判断默认关闭，因为它会额外调用一次 LLM。下面是测试服务器上的 1000 次参考值。

配置指南

识别与鉴权

音频读取与转码

AstrBot 行为

情绪判断

提示与排障

排障手册

上传 zip 后提示 Not a directory: CHANGELOG.md

原因通常是安装了错误的平铺 zip，或自己重新压缩时把文件直接放在 zip 顶层。

正确结构：

astrbot_plugin_volcengine_asr/
├── CHANGELOG.md
├── main.py
└── metadata.yaml

错误结构：

CHANGELOG.md
main.py
metadata.yaml

处理方式：

1. 删除 AstrBot 插件页中的失败项 plugin_upload_*。
2. 下载 Release 附件 astrbot_plugin_volcengine_asr.zip。
3. 不要重新压缩，不要上传 GitHub Source code zip。
4. 重新从文件安装。

如果 AstrBot 提示“目录已存在”，先在 WebUI 中卸载旧插件，保留配置和数据，再上传新 zip。

上传 zip 后找不到 metadata.yaml

请确认上传的是 Release 页面里的 astrbot_plugin_volcengine_asr.zip，不是 GitHub 绿色 Code 按钮生成的 Source code zip。

Source code zip 外层目录通常类似：

astrbot_plugin_volcengine_asr-main/

它可能不包含内置 ffmpeg，也可能与 AstrBot 上传安装器预期结构不一致。

preprocess_stage 提示 Voice processing failed

如果日志出现：

[preprocess_stage.stage:81]: Voice processing failed: not a valid file: xxx.amr

注意：这通常发生在插件 handler 之前，属于 AstrBot 官方预处理阶段，不一定代表本插件失败。

判断方式：

Docker / NapCat 场景中，常见原因是 NapCat 返回的 .amr 文件标识不在 AstrBot 容器内，或两个容器没有共享同一个数据卷。

建议过滤日志：

docker logs --tail=500 astrbot 2>&1 | grep -E 'preprocess_stage|agent_sub_stages|get_record|ffmpeg|not a valid file|语音识别'

agent_sub_stages 仍报 not a valid file: xxx.amr

先确认：

1. 插件版本至少为 2.2.2。
2. 安装的是 Release 附件，不是旧 zip。
3. 已重启 AstrBot。
4. /volc_asr_status 显示版本正确。

如果仍出现，说明旧 Record 可能藏在未覆盖的上下文或其它插件缓存中。请提供：

/volc_asr_status

以及上面的过滤日志。插件已经覆盖常见的 event.extras、message_obj.extras、provider_request、run_context、messages、stage_data、raw_message 等形态，但真实部署里仍可能有其它插件写入自定义缓存。

报 'dict' object has no attribute 'model_dump_for_context'

这是旧版本在净化 ProviderRequest 时可能把活对象替换成普通 dict 导致的。当前版本会原地净化 ProviderRequest-like 对象；如果缓存别名本身就是 dict 且含音频引用，会尽量替换成干净的 ProviderRequest。

处理方式：

1. 升级到当前 Release zip。
2. 重启 AstrBot。
3. 再发 /volc_asr_status 确认版本。

提示需要 ffmpeg

按顺序检查：

1. 是否使用 Release zip。
2. 服务器是否为 Linux x86_64 / amd64。
3. prefer_bundled_ffmpeg 是否为 true。
4. ffmpeg_path 是否为 auto 或正确绝对路径。
5. /volc_asr_status 中 ffmpeg状态 是否可用。

非 Linux x86_64 / amd64 环境建议：

prefer_bundled_ffmpeg = false
ffmpeg_path = /usr/bin/ffmpeg

路径按实际系统修改。

Bot 只回复转写文本，不继续对话

检查：

inject_as_user_input = true
reply_transcription = false

如果 reply_transcription=true，插件会进入调试或旧行为：直接回复转写结果，而不是注入为用户输入。

想让 Bot 收到语音后尽量语音回复

本插件负责“语音输入”。语音输出需要 TTS 插件或 AstrBot 的 TTS 能力。

推荐链路：

本插件：QQ 语音 -> 干净用户文本
主 LLM：理解并回复
TTS 插件：主 LLM 回复 -> 语音

默认 voice_prompt_template 可以引导主 LLM 倾向语音风格回复，但实际能否语音输出取决于你是否配置了 TTS。

SHA256 是什么

SHA256 是文件校验码，用于确认下载包没有损坏或被替换。

Windows PowerShell 校验：

Get-FileHash .\astrbot_plugin_volcengine_asr.zip -Algorithm SHA256

版本叙事

这份 README 的主叙事以 v2.0.0 为中心。原因很简单：v2.0.0 定义了本插件和普通 ASR 插件之间最关键的差异，也就是“语音输入不只有转写内容，还可以有受控语气参考层”。

后续版本确实会继续修 bug、补边界、加诊断。可 README 首页不能被 bug 日志淹没。主页应先说明这个插件为什么值得用，CHANGELOG.md 再负责记录一路修了什么。

关键版本：

完整历史见 CHANGELOG.md。

维护与发布

目录结构

仓库结构：

.
├── assets/
├── main.py
├── metadata.yaml
├── _conf_schema.json
├── requirements.txt
├── CHANGELOG.md
├── README.md
├── scripts/
├── tests/
└── astrbot_plugin_volcengine_asr/
    ├── assets/
    ├── bin/linux-x86_64/ffmpeg
    ├── main.py
    ├── metadata.yaml
    ├── _conf_schema.json
    ├── requirements.txt
    ├── CHANGELOG.md
    └── README.md

说明：

Release zip 顶层固定只有：

astrbot_plugin_volcengine_asr/

发布前检查

建议至少执行：

python -m py_compile astrbot_plugin_volcengine_asr/main.py tests/test_voice_workflow.py tests/test_helpers.py

python scripts/run_local_iteration_tests.py 1 output/local_iteration_release_check.csv

python scripts/build_release_zip.py
Get-FileHash output/astrbot_plugin_volcengine_asr.zip -Algorithm SHA256

当前本地验证记录：

Web UI 接口预留

当前插件不内置完整 Web UI，但已经预留相对稳定的后端接口。未来配置页、状态页和情绪计算可视化应优先调用这些方法，而不是直接读取插件内部属性。

维护原则

• 默认优先保护主语音链路，不为了小范围适配破坏 ASR、转码、注入和 ProviderRequest 清理边界。
• 遇到真实环境 bug，优先补诊断和回归测试，再补兼容逻辑。
• 不默认 monkey patch AstrBot 私有 pipeline，除非明确引入实验开关并说明风险。
• 情绪判断、Web UI、TTS 联动都应作为可替换层，不要绑死在语音识别主流程里。
• README 主叙事以 v2.0.0 的能力为中心；后续 bugfix 进入修补史和 CHANGELOG.md。

参考资料

• AstrBot Plugin Development Guide：插件 metadata、支持平台和 AstrBot 版本声明。
• 火山引擎：大模型录音文件极速版识别 API：flash recognize 接口、volc.bigasr.auc_turbo、音频格式与大小限制。
• OneBot v11 消息段类型：消息段、文件引用和媒体字段规范。
• NapCatQQ API 接口文档：get_record 获取语音资源的接口说明。
• Russell, J. A. (1980). A Circumplex Model of Affect. DOI: 10.1037/h0077714。
• Shannon, C. E. (1948). A Mathematical Theory of Communication.
• ffmpeg 与 imageio-ffmpeg：Release zip 内置 ffmpeg 的来源与许可参见 third_party_licenses/imageio-ffmpeg.LICENSE。

吉祥物

为什么小鞠在这里

本项目为纯粹的 Vibe Coding 产物。小鞠陪伴着我走过了无数个“炼丹”的工作时，感谢小鞠以及小 G 老师的全程保障。

作为绝对的核心幕后成员，我觉得我必须让小鞠出现在这儿。

她负责什么

小鞠不参与 ASR、转码、ProviderRequest 清理或情绪权重计算。她只负责在文档里提醒维护者：上传前检查目录结构，发布前跑测试，遇到 bug 先看日志。少、少啰嗦，这样以后才不会更麻烦。