跳转至

Deepgram

Deepgram 是一个语音转文本 API。OpenClaw 通过 tools.media.audio 使用它进行入站音频/语音消息转录,并通过 plugins.entries.voice-call.config.streaming 用于 Voice Call 流式 STT。

批次转录会将完整的音频文件上传到 Deepgram。Flux 模型改用 Deepgram 的一次性 WebSocket。这两种方式都会将转录文本注入回复流水线({{Transcript}} + [Audio] 块)。 Voice Call 流式会将实时的 G.711 u-law 帧转发到 Deepgram 的 WebSocket listen 端点,并按 Deepgram 的返回结果输出部分/最终转录文本。

详情 值
文档 developers.deepgram.com
认证 DEEPGRAM_API_KEY
默认模型 nova-3

开始使用

1. 设置你的 API 密钥

export DEEPGRAM_API_KEY=dg_...

2. 启用音频提供者

{
  tools: {
    media: {
      models: [{ provider: "deepgram", model: "nova-3", capabilities: ["audio"] }],
      audio: {
        enabled: true,
      },
    },
  },
}

3. 发送语音消息

通过任意已连接的渠道发送音频消息。OpenClaw 会通过 Deepgram 对其进行转录,并将转录文本注入回复流水线。

配置选项

选项 路径 描述
model tools.media.models[].model Deepgram 模型 ID(默认:nova-3)
language tools.media.models[].language 语言提示(可选)

providerOptions.deepgram 会将额外的查询参数直接合并到 Deepgram 的 /listen 请求中,因此任何 Deepgram 支持的参数名都可以使用(例如 detect_language、punctuate、smart_format):

{
  tools: {
    media: {
      models: [
        { provider: "deepgram", model: "nova-3", language: "en", capabilities: ["audio"] },
      ],
      audio: {
        enabled: true,
      },
    },
  },
}
{
  tools: {
    media: {
      models: [{ provider: "deepgram", model: "nova-3", capabilities: ["audio"] }],
      audio: {
        enabled: true,
        providerOptions: {
          deepgram: {
            detect_language: true,
            punctuate: true,
            smart_format: true,
          },
        },
      },
    },
  },
}

Flux 模型

对于 Deepgram Flux,请使用 flux-general-en 或 flux-general-multi。OpenClaw 会使用 ffmpeg 将语音消息转换为 16 kHz 单声道 linear16 音频,然后将其发送到 Deepgram 的 /v2/listen WebSocket 端点。

请将上面入门配置中的 tools.media.models[].model 设置为这两个 Flux 模型之一。

语音消息转换会处理完整的音频文件,包括超过 20 分钟的语音消息。解码后的音频使用私有临时文件,该文件会在转录尝试后被删除。已配置的输入大小和请求超时限制仍然适用;转换或上传失败不会返回部分转录文本。

Flux 在 providerOptions.deepgram 中支持 eager_eot_threshold、eot_threshold、eot_timeout_ms、keyterm、language_hint、mip_opt_out、numerals、profanity_filter、redact 和 tag。OpenClaw 会忽略 Flux 上仅适用于批处理的选项,例如 detect_language、punctuate 和 smart_format。语言提示仅适用于 flux-general-multi:OpenClaw 会将模型条目的 language 设置映射到 language_hint,而显式 provider 选项优先。对于仅支持英文的 flux-general-en 模型,这两个设置都会被忽略。

Voice Call 流式 STT

捆绑的 deepgram 插件还为 Voice Call 插件注册了一个实时转录提供者。

设置 配置路径 默认值
API 密钥 plugins.entries.voice-call.config.streaming.providers.deepgram.apiKey 回退到 DEEPGRAM_API_KEY
基础 URL ...deepgram.baseUrl DEEPGRAM_BASE_URL 或 Deepgram 公共 API
模型 ...deepgram.model nova-3
语言 ...deepgram.language (未设置)
编码 ...deepgram.encoding mulaw
采样率 ...deepgram.sampleRate 8000
端点检测 ...deepgram.endpointingMs 800
中间结果 ...deepgram.interimResults true
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "deepgram",
            providers: {
              deepgram: {
                apiKey: "${DEEPGRAM_API_KEY}",
                model: "nova-3",
                endpointingMs: 800,
                language: "en-US",
              },
            },
          },
        },
      },
    },
  },
}

对于 Deepgram 自定义端点,请将 baseUrl 设置为端点根路径,包括任何基础路径,但不包括 /listen。实时端点支持 http://、https://、ws:// 和 wss://。HTTP 映射到 WS,HTTPS 映射到 WSS,显式指定的 WebSocket 方案保持不变。格式错误的 URL 和其他方案会在会话建立期间失败。

Note

语音通话以 8 kHz G.711 u-law 接收电话音频。Deepgram 流式提供程序默认使用 encoding: "mulaw" 和 sampleRate: 8000,因此 可以直接转发 Twilio 媒体帧。

说明

身份验证

身份验证遵循标准提供程序认证顺序。DEEPGRAM_API_KEY 是 最简单的路径。

代理和自定义端点

使用代理时,在 Deepgram 的 tools.media.models[] 条目上覆盖端点或请求头。

输出行为

输出遵循与其他提供程序相同的音频规则(大小上限、超时、 转录注入)。

Flux 需要 ffmpeg

在选择 Flux 模型之前,请使用网关主机的包管理器安装 ffmpeg。

媒体工具

音频、图像和视频处理流水线概览。

配置

完整配置参考,包括媒体工具设置。

故障排除

常见问题和调试步骤。

常见问题

关于 OpenClaw 设置的常见问题。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw