配置录音开场白

更新时间

了解对话式 AI 引擎中配置录音开场白相关内容的适用场景、配置步骤、实现要点和注意事项。

通过配置录音开场白,你可以让智能体在用户加入频道后优先播放预先准备好的音频文件,而不是临时调用 TTS 合成问候语。这种方式适合固定话术的外呼、客服接待、品牌介绍等场景,有助于降低首句延迟和 TTS 成本,并提升开场听感的一致性。

适用场景

以下场景适合使用录音开场白:

  • 开场话术固定,且不依赖实时变量替换。
  • 需要统一品牌音色、情绪或真人录音效果。
  • 希望尽量减少开场白阶段的 TTS 开销。

如果你的开场白需要根据用户姓名、套餐、活动信息等动态生成,建议继续使用 greeting_message 走原有 TTS 路径。

工作原理

调用 POST 创建对话式智能体 接口时,你可以在 llm 下配置 greeting_audio_url。配置该字段时,必须同时配置 greeting_message。系统收到请求后,会优先下载该录音文件并在适当时机播报:

  1. 下载录音文件。
  2. 解码音频并转换为与 tts.params.sample_rate 一致的采样率。
  3. 按 greeting_configs.delay_ms 配置等待后推流给用户。
  4. 如果录音下载失败、解码失败、格式不支持或超时,则自动回退到 greeting_message 的 TTS 路径。

参数说明

录音开场白相关参数如下:

  • llm.greeting_audio_url:录音文件 URL。该字段仅支持 http:// 或 https:// 开头的字符串,长度不能超过 2048 字节。null 和字段缺失均视为未配置,此时系统走原有 greeting_message 实时 TTS 路径。
  • llm.greeting_message:录音对应的文本内容。配置 greeting_audio_url 时,该字段为必填,用于异常回退和可打断场景下的上下文重建。如果缺失,请求会直接返回 400 错误,reason 为 MissingRequiredField。
  • llm.greeting_configs.audio_download_timeout_ms:录音下载超时时间,单位为毫秒,仅在配置 greeting_audio_url 时生效。取值范围为 [200, 10000],默认值为 1000。null 和字段缺失均视为未配置,此时使用默认值。
  • llm.greeting_configs.audio_pcm_sample_rate:PCM 文件采样率,仅在录音格式为 PCM 时需要配置,默认值为 16000。
  • llm.greeting_configs.interruptable:录音开场白是否允许被用户打断。
  • llm.greeting_configs.uninterruptible_asr_policy:当 interruptable = false 时,定义开场白播放期间用户 ASR 文本的路由策略。可选值为:
    • merge_reply(默认):在开场白播放(含 delay_ms)期间静默接收 ASR 结果,待开场白播放完毕后,将期间收集到的多段 ASR 文本拼接成单轮 user 消息,统一送入大模型进行一次推理并回复。
    • context:在开场白播放(含 delay_ms)期间,将识别到的用户 ASR 文本写入历史对话上下文,不立即送入大模型;开场白结束后,继续等待用户新的有效语音输入。
  • llm.greeting_configs.delay_ms:录音开场白播报前的延迟时间。

支持的音频格式

当前支持以下录音格式:

  • mp3
  • wav
  • pcm

使用时请注意:

  • mp3 和 wav 文件无需额外指定采样率。
  • pcm 文件本身不包含采样率信息,因此必须根据实际文件采样率配置 greeting_configs.audio_pcm_sample_rate。
  • 系统会在播报前将导入音频统一转换为与 tts.params.sample_rate 一致的采样率。
  • 如果 greeting_audio_url 不是 http:// 或 https:// URL、为空字符串或长度超过 2048 字节,请求会返回 400 错误,reason 为 InvalidFieldValue。

配置示例

以下示例展示了一个标准录音开场白配置:

JSON
{
  "name": "outbound_voice_agent",
  "properties": {
    "channel": "outbound_call_channel_001",
    "token": "token",
    "agent_rtc_uid": "123",
    "remote_rtc_uids": ["321"],
    "llm": {
      "url": "https://api.minimax.chat/v2/text/chatcompletion_v2",
      "api_key": "xxx",
      "greeting_audio_url": "https://cdn.example.com/audio/standard-welcome.mp3",
      "greeting_message": "您好,感谢拨打声网客服热线。我们检测到您的套餐即将到期,请问需要为您办理续费吗?",
      "greeting_configs": {
        "delay_ms": 600,
        "interruptable": true,
        "audio_download_timeout_ms": 1000
      },
      "params": {
        "model": "abab6.5s-chat"
      }
    },
    "asr": {
      "language": "zh-CN"
    },
    "tts": {
      "vendor": "minimax",
      "params": {
        "group_id": "xxxx",
        "key": "xxxx",
        "model": "speech-01-turbo",
        "voice_setting": {
          "voice_id": "female-shaonv"
        },
        "audio_setting": {
          "sample_rate": 16000
        }
      }
    }
  }
}

如果你使用的是 PCM 文件,则还需要补充采样率配置:

JSON
"greeting_audio_url": "https://cdn.example.com/audio/brand-intro.pcm",
"greeting_configs": {
  "audio_pcm_sample_rate": 16000
}

异常回退机制

当录音开场白无法正常播放时,系统会自动回退到 greeting_message 的 TTS 路径,确保用户仍然能听到完整开场白。常见触发场景包括:

  • 录音 URL 不可访问。
  • 录音下载超时。
  • 音频格式不支持。
  • 解码失败或 PCM 数据损坏。

如果你配置了 greeting_audio_url 但未配置 greeting_message,请求会直接返回 400 错误,reason 为 MissingRequiredField,不会创建智能体。因此,在所有录音开场白场景中都必须同时配置 greeting_message。

打断与上下文重建

当 greeting_configs.interruptable = true 时,用户可以在录音开场白播报过程中打断智能体。

为保持对话连贯性,系统会基于录音的总时长和实际已播报时长,结合 greeting_message 估算用户已经听到的文本片段,并将该片段注入短期记忆中。这样,大模型在后续回复时能够基于真实的播报进度理解上下文。

因此,在可打断场景下,greeting_message 不仅用于异常兜底,也用于对话上下文重建。

当 greeting_configs.interruptable = false 时,用户在开场白播放期间的语音不会打断当前播报,而是按 greeting_configs.uninterruptible_asr_policy 配置处理。

不可打断场景下的 ASR 路由策略

当 greeting_configs.interruptable = false 时,你可以通过 greeting_configs.uninterruptible_asr_policy 控制开场白播放期间用户语音识别结果的处理方式。如果不配置该字段,默认使用 merge_reply。

  • merge_reply:在开场白播放(含 delay_ms)期间,引擎会在后台静默接收用户 ASR 结果,但不会立即触发中断或回复。待开场白播放完毕后,引擎会将期间收集到的多段 ASR 文本拼接为单轮 user 消息,再统一送入大模型进行一次推理和回复。
  • context:在开场白播放(含 delay_ms)期间,引擎会将识别到的用户 ASR 文本写入历史对话上下文,但不会立即送入大模型。开场白结束后,引擎会继续等待用户新的有效语音输入。这些文本仍会记录在 transcript 和 history 中,便于后续查看对话过程。

以下示例展示了不可打断场景下的配置方式:

JSON
"greeting_configs": {
  "delay_ms": 600,
  "interruptable": false,
  "uninterruptible_asr_policy": "merge_reply",
  "audio_download_timeout_ms": 1000
}

最佳实践

  • 为录音文件配置稳定、可公网访问的 URL。
  • 录音内容应与 greeting_message 保持一致,避免打断后上下文错位。
  • 对于 PCM 文件,务必确认实际采样率与 audio_pcm_sample_rate 一致。
  • 将 audio_download_timeout_ms 控制在业务可接受的等待范围内,并确保其取值位于 [200, 10000]。

错误事件说明

录音开场白下载失败、超时、格式不支持或解码失败等异常会通过服务端 110 agent error Webhook / RTM 事件对外暴露。与此同时,如果你在创建智能体时将 parameters.enable_error_message 设为 true,这类异常还会通过客户端组件的 onMessageError 回调下发到端侧,便于你做监控、告警和降级处理。

录音开场白异常触发错误事件时,常见表现如下:

  • 110 agent error 中,errors[].module 为 agent,message 会包含录音 URL 不可达、下载超时、格式不支持或解码失败等错误原因。
  • 客户端 onMessageError 回调中的 MessageError.message 通常为包含错误详情的 JSON 字符串,你可以解析其中的错误码、错误信息和关联资源,用于日志记录或提示用户。

参考信息

这个页面有帮助吗?