跳到主要内容

AI 对话

响应受支持设备发起的 AI 对话请求，接收对话内容和意图，并根据设备指定的音频通道接入用户语音。

有关 AIChatEventType 的会话事件，请参阅 AI 会话事件；执行识别出的操作前，请根据 AI 意图完成校验。

动态流程

由设备发起的 AI 对话流程

设备发起 AI 对话时，会指定由设备通过 Opus 发送语音，或由 App 通过 SCO 采集语音。整个过程中需要保持设备状态与 AI 会话状态一致。

设备 → App

接收设备请求

设备发起 AI 对话，并通过事件指定 SCO 或 Opus 语音输入。

宿主 App

准备音频输入

按设备指定的通道准备语音输入：Opus 由设备发送，SCO 由 App 侧录音。

AIBudsAISDK

启动 AI 对话

通过 AIBudsAISDK 启动 AI 对话会话。

App ↔ 设备

保存会话并反馈结果

保存返回的 session；Opus 模式下还需向设备报告启动成功或失败。

设备 → App → session

采集或转发语音

SCO 由 App 采集设备麦克风语音；Opus 由设备发送，解码后输入当前 session。

实时音频
AI 服务 → App

处理会话回调

接收对话内容、意图、语音回复、VAD 和会话事件。

流式回调
App + 音频输出

呈现 AI 回复

展示回复文本，并按配置播放 AI 语音回复。

App ↔ 设备

结束会话

处理设备终止、状态冲突、自动结束、主动停止或运行时错误。

结束回调

释放会话

处理最终报告，并清除已保存的 session。

Opus 模式启动失败时，应按设备协议报告失败。设备要求终止、发生状态冲突、会话自动结束或出现不可恢复错误时，应停止当前会话，并在结束回调后释放。

前提条件​

  • AIBudsAISDK 已初始化，当前设备信息已配置，并已选择已注册且鉴权成功的 AI 服务商。
  • AI 服务商支持 AIChatServiceAPI。
  • 设备会发送 AI 对话会话事件；使用 Opus 输入时，设备遵循 DeviceAIChatAPI。
  • 音频通道必须读取设备事件中的请求，不应由 App 独立选择。

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“实现 AIBuds AI 对话”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/implement-aibuds-ai-chat，使用该技能在当前 iOS 项目中完成“实现 AIBuds AI 对话”，并验证结果。
查看官方技能

API 参考​

框架​

AIBudsAI.xcframework

导入​

Swift
import AIBuds
import AIBudsAI
import AIBudsAIFoundation

声明​

Swift
/// Starts an AI chat session.
/// - Parameters:
///   - config: The chat session configuration.
///   - onStartSuccess: Called with the active session.
///   - onStartFailure: Called when the session cannot start.
///   - onChatData: Called when new conversational data arrives.
///   - onIntent: Called when the provider detects an intent.
///   - onVoiceData: Called when voice data is produced.
///   - onEvent: Called for session-level events.
///   - onError: Called for runtime session errors.
///   - onFinish: Called with the final session report.
public static func startAIChat(_ config: AIChatSessionConfig = .default,
                         onStartSuccess: ((_ session: AIChatSessionConvertible) -> Void)? = nil,
                         onStartFailure: ((_ error: Error) -> Void)? = nil,
                             onChatData: ((_ chatData: AIChatDataModel) -> Void)? = nil,
                               onIntent: ((_ intent: AIChatIntentModel) -> Void)? = nil,
                            onVoiceData: ((_ voiceData: AIChatVoiceDataModel) -> Void)? = nil,
                                onEvent: ((_ event: AIChatEventModel) -> Void)? = nil,
                                onError: ((_ error: NSError) -> Void)? = nil,
                               onFinish: ((_ report: AIChatSessionReportModel) -> Void)? = nil) -> Void

/// Stops the active AI chat session. This is safe when no session is active.
public static func stopAIChat()

请参阅 startAIChat 和 stopAIChat。

配置​

AIChatSessionConfig 提供 AIChatSettingsController 使用的设置：

属性默认值用途
languageForSpeechInputApp 语言语音输入语言，使用 AI 服务商支持的连字符格式标识符，例如 zh-CN。
audioChannel.opusInA2dpOut当前对话会话使用的音频传输方式，必须与启动会话的设备事件匹配。
allowUserToInterruptAIResponsetrue是否允许用户说话打断 AI 语音回复。
maxPauseDurationBeforeAIResponds0.8 秒用户停止说话后，等待 AI 开始回复的最大停顿时长。
autoEndSessionAfterNoInputDuration15.0 秒持续未检测到输入后，自动结束会话的等待时长。
enableVoicePlaybacktrue是否播放 AI 生成的语音回复。
shouldSaveVoiceForDebuggingfalse是否保存输入音频用于调试。除非策略明确允许，否则生产环境应保持禁用。
additionalOptions[:]AI 服务商专用的 Agent、音色、计划、提示词、意图或降噪选项。
autoSelectAgentIfNotSpecifiedtrue未指定 Agent 时，SDK 是否自动选择。

使用公开的 AdditionalOptionKey... 常量，不要硬编码 AI 服务商选项的键名。

配置 AI 对话​

Demo 将 AI 服务商选择与会话配置分开。更改服务商时，先完成选择，再查询其支持的语言，并在启动对话前由 App 完成鉴权。Agent ID、音色 ID、意图代码、使用计划和初始提示词取决于服务商配置，不要直接复制 Demo 中的示例值。

Swift
let vendor: AIServiceVendor = .starBurst
AIBudsAISDK.setAIServiceVendor(vendor)

let supportedLanguages = AIBudsAISDK.allSupportedLanguages(for: vendor)
let language = supportedLanguages.first?.languageCode

var options: [String: Any] = [:]
if let agentID = providerAgentID {
    options[AIChatSessionConfig.AdditionalOptionKeyStarburstAgentId] = agentID
}
if let speakerID = providerSpeakerID {
    options[AIChatSessionConfig.AdditionalOptionKeyStarburstSpeakerId] = speakerID
}

let config = AIChatSessionConfig(
    languageForSpeechInput: language,
    audioChannel: .opusInA2dpOut,
    allowUserToInterruptAIResponse: true,
    maxPauseDurationBeforeAIResponds: 0.8,
    autoEndSessionAfterNoInputDuration: 15,
    enableVoicePlayback: true,
    shouldSaveVoiceForDebugging: false,
    additionalOptions: options
)
config.autoSelectAgentIfNotSpecified = providerAgentID == nil

使用 .mltcloud 时，请使用对应的 AdditionalOptionKeyMltCloud... 常量。仅当 AI 服务商配置提供有效值时，才设置 StarBurst 使用计划或服务商专用标识符。

使用示例​

设备通过 .initiateWithSCO 或 .initiateWithOpus 发起对话。启动 AI 对话前，将设备指定的通道写入会话配置。使用 Opus 时，设备向 App 发送 Opus，App 再将解码后的 PCM 输入当前 session；使用 SCO 时，以 .sco 启动会话，由 App 通过 SCO 采集设备麦克风语音。

Swift
let config = AIChatSessionConfig.default
config.audioChannel = .opusInA2dpOut
config.languageForSpeechInput = "en-US"

AIBudsAISDK.startAIChat(
    config,
    onStartSuccess: { session in
        currentSession = session
    },
    onStartFailure: { error in
        print("Chat start failed: \(error)")
    },
    onChatData: { chatData in
        conversation.append(chatData)
    },
    onIntent: { intent in
        handle(intent)
    },
    onVoiceData: { voiceData in
        handle(voiceData)
    },
    onEvent: { event in
        handle(event)
    },
    onError: { error in
        print(error.localizedDescription)
    },
    onFinish: { report in
        currentSession = nil
        save(report)
    }
)

收到设备发送的 Opus，并从 SDK 回调取得解码后的 16 位 PCM 后，将 PCM 输入当前 session：

Swift
currentSession?.appendInt16PCM?(decodedPCMData)

停止会话​

设备请求终止时，先按设备协议通过 DeviceAIChatAPI 回报对话已停止，再调用：

Swift
AIBudsAISDK.stopAIChat()
currentSession = nil

注意事项​

  • 这是基于语音的会话 API，不提供文本 sendMessage 或消息历史 API。
  • 会话期间应保留 AIChatSessionConvertible；收到 onFinish、发生不可恢复错误或主动停止后应及时释放。
  • SCO 会话由 AIBuds AI SDK 通过 App 的 SCO 链路录制设备麦克风语音；Opus 会话由设备向 App 发送 Opus，再通过 appendInt16PCM(_:) 输入解码后的 PCM。
  • 除非隐私和保留策略明确允许，否则生产环境不要启用 shouldSaveVoiceForDebugging。