助手
扣子 AI 帮助与支持
你好,我是 扣子 文档问答助手 🎉 你在阅读当前文档的过程中,无论对文档概念的解释,还是文档内容方面的疑问,都可以随时向我提问,我会全力为你解答
推荐问题
如何快速了解这个空间的核心内容?
有哪些近期更新的重点文档?
我应该从哪些文档开始阅读?
文档反馈

实现语音和图片的多模态交互

更新于: 2026-06-24 15:47:07

在智能眼镜等终端场景中,用户常常需要通过语音指令触发智能体,并上传图片以实现图片理解功能。这种多模态交互方式能够显著提升用户体验,尤其是在需要快速获取信息或进行复杂任务处理时。你可以选择基于对话 OpenAPI 或音视频通话来实现这一功能。

方式一:基于对话 OpenAPI 实现

步骤一:创建并发布智能体

创建单 Agent(自主规划模式)​类型的智能体,选择豆包·视觉理解·Pro 模型或其他支持视觉理解的模型。调试后将智能体发布为 API
Image

步骤二:调用发起对话 API 实现多模态交互

实现方法

  1. 调用上传文件 API,将图片和语音文件上传到扣子编程,并获取对应的 file_id
  2. 调用发起对话 API,在 messages 中同时传入图片和语音文件的 file_id。智能体将结合语音内容和图片内容进行联合理解,并返回对图片的理解结果。

示例代码

示例代码如下,完整的示例代码请参见 audio_chat_with_vision_image 示例项目源码。

 # 将语音和图片上传到 coze
    audio_file = coze.files.upload(file=audio_path)
    image_file = coze.files.upload(file=image_path)

 # 调用 /v3/chat 发起对话, 传入语音和图片的 file id
    stream = coze.chat.stream(
        bot_id=bot_id,
        user_id=secrets.token_urlsafe(),
        additional_messages=[
            Message.build_user_question_objects(
                [
                    MessageObjectString.build_image(file_id=image_file.id),
                    MessageObjectString.build_audio(file_id=audio_file.id),
                ]
            )
        ],
    )
    print(f"对话开始 logid: {stream.response.logid}")

成功调用后,智能体将返回图片的理解结果,返回示例如下:
Image

方式二:基于语音通话 SDK

步骤一:搭建对话流

  1. 创建一个对话流,对话流的节点概览如下图所示,在对话流中添加大模型节点用于理解图片。
    Image
    对话流中各节点的配置和参数如下表所示。

    节点

    参数配置

    示例图

    开始

    开始节点添加一个类型为 image 的输入参数,参数名称可以自定义,但需与代码中一致,本文以 image 为例。

    Image

    大模型

    • 模型选择豆包·视觉理解·Pro 模型或其他支持视觉理解的模型。
    • 输入参数:输入中添加 inputimage变量,变量的值分别引用开始节点的 USER_INPUTimage
    • 系统提示词:使用以下示例 Markdown 信息,表示将用户输入的数据传入 LLM 进行处理。
      用户输入:{{input}}
      图片:{{image}}
      

    Image

    结束

    新增 output 输出参数,并在参数值区域选择引用大模型节点的 output 参数。

    Image

  2. 创建智能体并将智能体设置为单 Agent(对话流模式),在智能体中添加对话流。
    Image

  3. 将智能体发布为 API

步骤二:对话中发送音频和图片

通过 WebSocket 或 RTC 进行音视频通话时,通过上行事件中的 parameters 参数,将图片发送给对话流。本文以 WebSocket 为例介绍具体实现方法。

实现方法

  1. 建立 WebSocket 连接时,在 URL 路径的 Query 参数中设置 bot_id
  2. 建立 WebSocket 连接后,发送 chat.update 上行事件,在 data.chat_config.parameters 参数中传入 image 输入参数的值,并传递给对话流,事件的详细说明请参见 双向流式对话上行事件
  3. 通过 WebSocket 与智能体进行实时语音交互时,通过 input_audio_buffer.append 上行事件,流式上传音频数据,事件的详细说明请参见流式上传音频片段

示例代码

示例代码如下,完整的示例代码请参见 websocket_chat.py 示例项目源码。

    chat = coze.websockets.chat.create(
        bot_id=bot_id,
        on_event=WebsocketsChatEventHandler(),
    )

    # 建立 websocket 链接
    async with chat() as client:
        print("建立 websocket 链接成功")
        # 发送 chat_flow 参数
        await client.chat_update(
            ChatUpdateEvent.Data.model_validate(
                {
                    "chat_config": ChatUpdateEvent.ChatConfig.model_validate(
                        {
                            "parameters": {
                                "image": json.dumps(
                                    {
                                        "file_id": image_file.id,
                                    }
                                ),
                            }
                        }
                    )
                }
            )
        )
        # 发送语音数据
        for delta in split_bytes_by_length(audio_data, 1024):
            await client.input_audio_buffer_append(
                InputAudioBufferAppendEvent.Data.model_validate(
                    {
                        "delta": delta,
                    }
                )
            )
            await asyncio.sleep(len(delta) * 1.0 / 24000 / 2)  # 模拟真实说话间隔
        await client.input_audio_buffer_complete()
        await client.wait()

成功建立连接并发送数据后,智能体将根据语音和图片内容返回相应的对话结果,返回示例如下:
Image