转写

转写会在助理轮次运行前，把收到的 audio 或 voice 附件转换成文本。它属于 media understanding，不是通用的模型可见聊天工具。

转写成功时，Anyy 会把 [Audio transcript] 块追加到用户文本，并在 turn metadata 中标记 text_source: audio_transcription。

配置

在 media_understanding.audio 下配置音频理解：

media_understanding:
  enabled: true
  audio:
    enabled: true
    provider: openai
    mode: auto
    on_failure: annotate
    timeout_ms: 60000
    max_bytes: 25000000
    max_chars: 12000
    language: ""
    prompt: ""
    providers:
      openai:
        type: openai
        model: gpt-4o-mini-transcribe
        base_url: https://api.openai.com/v1
        api_key_ref: env:OPENAI_API_KEY

当 media_understanding.enabled 为 false、audio.enabled 为 false、audio.mode 为 disabled 或 audio.provider 为空时，转写会被禁用。

Command 转写

自定义 command provider 会运行本地命令：

providers:
  local-whisper:
    type: command
    command: /usr/local/bin/transcribe
    args: ["--json"]
    cwd: /tmp
    env:
      MODEL_PATH: /models/whisper
    max_chars: 12000

环境变量值可以使用 secret refs。Anyy 会在启动命令前解析它们。

Provider 转写

OpenAI-compatible providers 使用：

字段	含义
type	openai 或 openai-compatible。
model	Provider transcription model。默认值可以来自 audio block。
base_url	API base URL。
credential_ref / api_key_ref	认证用 secret reference。
timeout_ms	Provider call timeout。
max_bytes	输入 artifact 最大大小。
max_chars	返回给当前轮的 transcript 字符上限。

内置默认 OpenAI model 常量是 gpt-4o-mini-transcribe。

收到的音频

Anyy 只会尝试转写 kind 为 voice 或 audio 的附件。

运行时通过 artifact path broker 解析附件，检查大小限制，运行 transcriber，并追加 transcript 文本：

[Audio transcript]
...

多个音频附件会在标签里包含序号：

[Audio transcript #2]
...

如果 inbound metadata 已经表明这是 Weixin voice item text source，Anyy 不会再次转写同一段音频。

失败策略

media_understanding.audio.on_failure 控制转写失败后的行为：

值	行为
annotate	追加 [Audio attachment could not be transcribed.] 并继续。默认。
ignore	保留失败附件，不追加 transcript text。
fail	以 audio transcription failed 失败当前轮。

附件 metadata 会在成功时记录 transcription_status、provider/model/language，并在失败时记录 transcription_error: transcription_failed。

故障排查

症状	检查
没有 transcript	确认 media understanding 和 audio transcription 已启用，并且附件 kind 是 audio 或 voice。
当前轮失败	检查 on_failure；fail 会把 provider 问题变成 turn error。
Provider 不可用	确认 provider id 存在且凭据可解析。
大音频被拒绝	降低文件大小，或谨慎提高配置的 max_bytes。
Transcript 被截断	提高 audio block 或 provider 的 max_chars。