服务端 Go SDK

1. NewMultiModalDialog

创建交互，设置回调。

// 创建一个语音对话会话。
//
// 此方法用于初始化一个新的会话，设置必要的参数以准备开始与模型的交互。
//
// 参数:
//   - appId: 客户在管控台创建的应用ID
//   - requestParams: 请求参数集合
//   - multimodalCallback: 回调对象，用于处理来自服务器的消息
//   - workspaceId: 客户的workspace_id（可选）
//   - url: API的URL地址（可选，默认 wss://dashscope.aliyuncs.com/api-ws/v1/inference）
//   - apiKey: 应用程序接入的唯一key
//   - dialogId: 对话id，如果传入表示承接上下文继续聊（可选）
//   - model: 模型（可选）
func NewMultiModalDialog(
    requestParams *RequestParameters,
    multimodalCallback MultiModalCallback,
    appID string,
    workspaceID string,
    url string,
    apiKey string,
    dialogID string,
    model string,
) (*MultiModalDialog, error)

2. Start

启动对话服务，返回 OnStarted 回调。注意 OnStarted 会回调 dialogID。

// 初始化WebSocket连接并发送启动请求
//
// 参数:
//   - dialogID: 对话ID，用于标识特定的对话会话。新对话传空字符串即可。
func (d *MultiModalDialog) Start(dialogID string) error

3. StartSpeech

通知服务端开始上传音频，注意需要在 LISTENING 状态才可以调用。

// 开始上传语音数据
func (d *MultiModalDialog) StartSpeech() error

// 发送语音数据
//
// 参数:
//   - speechData: 语音二进制数据
func (d *MultiModalDialog) SendAudioData(speechData []byte) error

// 停止上传语音数据
func (d *MultiModalDialog) StopSpeech() error

// 请求服务端开始说话（打断）
func (d *MultiModalDialog) Interrupt() error

// 本地TTS播放开始
func (d *MultiModalDialog) LocalRespondingStarted() error

// 本地TTS播放结束
func (d *MultiModalDialog) LocalRespondingEnded() error

// 停止对话
func (d *MultiModalDialog) Stop() error

// 获取对话状态
//
// 返回:
//   - DialogState: 当前对话状态（Idle / Listening / Thinking / Responding）
func (d *MultiModalDialog) GetDialogState() DialogState

11. RequestToRespond

请求服务端直接文本合成语音，或者发送指令给服务端。

// 请求服务端直接文本合成语音
//
// 参数:
//   - requestType: 请求类型（"prompt" 或 "transcript"）
//   - text: 请求文本
//   - parameters: 附加参数（可选，如图片等）
//   - interruptible: 是否可打断
func (d *MultiModalDialog) RequestToRespond(
    requestType string,
    text string,
    parameters *RequestToRespondParameters,
    interruptible bool,
) error

请求参数

// 配置上行参数
upstream := &dashscope.Upstream{
    Type:        "AudioOnly",
    Mode:        "push2talk",
    AudioFormat: "pcm",
}

// 配置下行参数
downstream := &dashscope.Downstream{
    Voice:            "longanhuan",
    SampleRate:       16000,
    IntermediateText: "transcript,dialog",
    AudioFormat:      "pcm",
}

// 配置客户端信息
clientInfo := &dashscope.ClientInfo{
    UserID: "user123",
    Device: &dashscope.Device{
        UUID: "1234567890",
    },
}

requestParams := &dashscope.RequestParameters{
    Upstream:   upstream,
    Downstream: downstream,
    ClientInfo: clientInfo,
}

type MultiModalCallback interface {
    // OnStarted 通知对话开始
    //   - dialogID: 回调对话ID
    OnStarted(dialogID string)

    // OnStopped 通知对话停止
    OnStopped()

    // OnStateChanged 对话状态改变
    //   - state: 新的对话状态
    //   - inputType: 触发状态变更的输入来源
    OnStateChanged(state DialogState, inputType InputType)

    // OnSpeechAudioData 合成音频数据回调
    //   - data: 音频二进制数据
    OnSpeechAudioData(data []byte)

    // OnError 发生错误时调用此方法
    //   - err: 错误信息
    OnError(err error)

    // OnConnected 成功连接到服务器后调用此方法
    OnConnected()

    // OnRespondingStarted 回复开始回调
    OnRespondingStarted()

    // OnRespondingEnded 回复结束
    //   - payload: 回复结束时的附加信息
    OnRespondingEnded(payload map[string]interface{})

    // OnSpeechStarted 检测到语音输入开始
    OnSpeechStarted()

    // OnSpeechEnded 检测到语音输入结束
    OnSpeechEnded()

    // OnSpeechContent 语音识别文本
    //   - payload: 包含识别文本的数据
    OnSpeechContent(payload map[string]interface{})

    // OnRespondingContent 大模型回复文本
    //   - payload: 包含回复文本的数据
    OnRespondingContent(payload map[string]interface{})

    // OnRequestAccepted 打断请求被接受
    OnRequestAccepted()

    // OnClose 连接关闭时调用此方法
    //   - closeStatusCode: 关闭状态码
    //   - closeMsg: 关闭消息
    OnClose(closeStatusCode int, closeMsg string)
}

VQA（图片问答）交互

VQA 是在对话过程中通过发送图片实现图片+语音的多模交互的功能。

核心过程是通过输入类似"看一下xxx"意图的语音，或者直接输入请求文本的方式触发 VQA，返回基于图片内容的问答结果。

• 通过语音请求的流程为：

  1. 语音说："看一下前面有什么"。

  2. 通过回调函数 OnRespondingContent 返回拍照意图 "visual_qa"。

  3. 客户端收到上述意图后，调用 RequestToRespond 接口提交图片内容触发问答回复。

• // callback 中处理 visual_qa 意图
    func (c *MyCallback) OnRespondingContent(payload map[string]interface{}) {
        if output, ok := payload["output"].(map[string]interface{}); ok {
            if extraInfo, ok := output["extra_info"].(map[string]interface{}); ok {
                if commands, ok := extraInfo["commands"].(string); ok {
                    if strings.Contains(commands, "visual_qa") {
                        // 触发 VQA
                        sendImageVQA(dialog)
                    }
                }
            }
        }
    }
  
    // 发送 VQA 请求
    func sendImageVQA(dialog *dashscope.MultiModalDialog) {
        image := map[string]interface{}{
            "type":  "base64",
            "value": imageBase64Data,
        }
        // 或者使用 URL 方式
        // image := map[string]interface{}{
        //     "type":  "url",
        //     "value": imageURL,
        // }
  
        imagesParams := &dashscope.RequestToRespondParameters{
            Images: []interface{}{image},
        }
  
        // 使用语音调用 VQA，text 传空字符串即可
        dialog.RequestToRespond("prompt", "", imagesParams, false)
    }

• 直接通过文本请求流程为：

  1. 客户端直接调用request_to_respond接口提交图片内容和请求文本，触发问答回复。

  image := map[string]interface{}{
        "type":  "base64",
        "value": imageBase64Data,
    }
    // 或者使用 URL 方式
    // image := map[string]interface{}{
    //     "type":  "url",
    //     "value": imageURL,
    // }
  
    imagesParams := &dashscope.RequestToRespondParameters{
        Images: []interface{}{image},
    }
  
    // 使用文本直接请求图片回复，text 填入文本请求
    dialog.RequestToRespond("prompt", "这张图片里面有什么", imagesParams, false)

注意：VQA 支持发送图片链接或者base64数据（支持小于180KB的图片）。

通过Websocket请求LiveAI（视频通话）

LiveAI（视频通话）是百炼多模交互提供的官方 Agent。通过 Go SDK 发送图片序列的方式，可以实现视频通话的功能。我们推荐您的服务端和客户端（网页或者 APP）通过 RTC 传输视频和音频，然后将服务端采集到的视频帧以 500ms/张 的速度发送给 SDK，同时保持实时的音频输入。

注意：LiveAI 发送图片只支持 base64 编码，每张图片的大小在 180K 以下。

• LiveAI调用时序

• 关键代码示例

// 1. 设置请求模式为 AudioAndVideo
upstream := &dashscope.Upstream{
    Type:        "AudioAndVideo",
    Mode:        "duplex",
    AudioFormat: "pcm",
}

// 2. 发送连接到视频对话 Agent 请求
func sendConnectVideoCommand(dialog *dashscope.MultiModalDialog) {
    videoConnectCommand := []interface{}{
        map[string]interface{}{
            "action": "connect",
            "type":   "voicechat_video_channel",
        },
    }

    params := &dashscope.RequestToRespondParameters{
        BizParams: &dashscope.BizParams{
            Videos: videoConnectCommand,
        },
    }

    dialog.RequestToRespond("prompt", "", params, false)
}

// 3. 间隔 500ms 发送一张 180KB 以下的视频帧图片
func sendVideoFrameLoop(dialog *dashscope.MultiModalDialog, stopChan chan bool) {
    ticker := time.NewTicker(500 * time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-stopChan:
            return
        case <-ticker.C:
            image := map[string]interface{}{
                "type":  "base64",
                "value": getVideoFrameBase64(),
            }
            params := &dashscope.RequestToRespondParameters{
                Images: []interface{}{image},
            }
            dialog.RequestToRespond("prompt", "", params, false)
        }
    }
}

文本合成TTS

SDK支持通过文本直接请求服务端合成音频。

您需要在客户端处于Listening状态下发送RequestToRespond请求。

若当前状态非Listening，需要先调用Interrupt 接口打断当前播报。

dialog.RequestToRespond("transcript", "今天天气不错", nil, false)

使用文本请求对话结果

SDK支持通过文本直接请求返回 LLM 结果和语音合成数据。

您需要在客户端处于Listening状态下发送RequestToRespond请求。

dialog.RequestToRespond("prompt", "今天天气不错", nil, false)

1. 资源管理

使用完毕后请调用 Cleanup() 方法释放所有资源：

defer dialog.Cleanup()

2. 心跳保活

建议定期发送心跳以保持链接：

ticker := time.NewTicker(45 * time.Second)
go func() {
    for range ticker.C {
        dialog.SendHeartBeat()
    }
}()

3. 状态监控

通过实现 MultiModalCallback 接口监控对话状态变化：

func (c *MyCallback) OnStateChanged(state dashscope.DialogState, inputType dashscope.InputType) {
    switch state {
    case dashscope.DialogStateListening:
        // 系统进入监听状态，可以开始发送音频
    case dashscope.DialogStateThinking:
        // AI 正在思考
    case dashscope.DialogStateResponding:
        // AI 正在回复，准备接收音频数据
    }
}