| name | audio_universal |
| description | 语音转文字工具,将音频文件转录为文本。原生 transcription 端点优先,失败自动降级为 chat completions(适配非标准语音识别模型)。支持多语言和时间戳。 |
| version | 1.2 |
| category | multimodal |
| enabled | true |
| tags | ["multimodal","audio","transcription"] |
语音转文字 (Audio Universal)
将音频文件转录为带可选时间戳的文本。支持多种语言和引导词。
插件路径
plugins/audio_universal/
工作方式
- 原生 transcription 端点 →
client.audio.transcriptions.create()(whisper-1 等标准模型)
- 失败时自动降级为 chat completions → 音频 base64 编码后作为多模态消息发送给专用模型
模型优先级
audio_transcription_model(config.json 专用配置)> "whisper-1"(默认)
配置后优先使用专用模型;不配则使用 whisper-1 走原生端点。
注册工具
| 工具名 | 描述 |
|---|
audio_transcribe | 将音频文件转录为文本,支持语言指定、引导词和时间戳 |
参数
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|---|
audio | string | 是 | — | 音频文件路径(本地文件) |
language | string | 否 | 自动检测 | 语言代码(如 zh、en、ja)。由智能体自行传入合适的语言代码,留空自动检测 |
prompt | string | 否 | — | 引导词,帮助适应特定风格或上下文词汇 |
timestamp_granularity | string (enum) | 否 | "segment" | none=纯文本、segment=段落级时间戳、word=单词级时间戳 |
结果说明
- 成功:返回转录文本(纯文本或带时间戳格式,取决于
timestamp_granularity)
- 失败:返回
ERROR: 前缀的错误信息
- 能力不支持:提示需要切换 provider 或配置
capabilities_override: ["audio_transcription"]
支持的服务商
- OpenAI 官方 — 原生 transcription 端点(whisper-1)
- OpenRouter / 其他兼容厂商 — 配
audio_transcription_model 后通过 chat 降级调用
- 不支持时 — 可通过
capabilities_override: ["audio_transcription"] 显式开启
典型场景
- 会议录音转文字
- 语音消息转录
- 播客/采访转写
- 外语音频翻译前预处理
常见规范
- 已知语种时明确传入
language 参数可提升转录准确率,留空则自动检测
prompt 引导词对专有名词、人名、技术术语的识别效果显著
- 音频文件需存在于本地文件系统
常见处理办法
- 转录结果不理想:尝试传入
prompt 引导词,包含关键术语的正确写法
- 文件不存在报错:检查路径是否正确,确认文件已上传到
users/<user>/history/file/
- 能力不支持:检查 provider 配置,确认
audio_transcription_model 已设置
常见教训
timestamp_granularity 选择 word 时输出可能非常庞大,仅在实际需要词级时间戳时使用
- chat 降级路径使用
input_audio 多模态格式发送音频,部分非标准模型可能不兼容
- provider 上下文缺失时工具直接报错,需重新进入会话