发送图片消息

更新时间不可用

了解对话式 AI 引擎中发送图片消息相关内容的适用场景、配置步骤、实现要点和注意事项。

与智能体互动期间,你可能需要在端侧上传图片或发送图片消息来辅助智能体理解用户意图。本文介绍如何使用对话式 AI 引擎客户端组件的能力在 App 中发送图片消息给大模型,并在后续与智能体对话时自动引用图片内容,让大模型根据图片内容生成更符合用户需求的回复。

技术原理

声网提供一套灵活可扩展、标准化的对话式 AI 引擎客户端组件(以下简称组件)。该组件支持 iOS、Android、Web 平台,封装了多个场景化 API,你只需要调用这些 API 即可结合声网实时互动 (RTC) SDK 和实时消息 (RTM) SDK 的能力实现以下功能:

调用组件的 chat 接口发送图片消息,并监听 onMessageReceiptUpdated 回调接收图片消息回执信息。

前提条件

开始前,请确保完成以下准备工作:

  • 已集成 RTC SDK v4.5.1 及以上版本,且已在 App 中实现基本的实时音视频功能并获取相关设备权限。请参考实现音视频互动。
  • 已在控制台为项目启用 RTM 服务,并在 App 中实现基本的实时消息功能。请参考实现收发消息。
  • 已参考实现对话式智能体实现与智能体对话的基本逻辑。
  • 确保 RTC 可用、RTM 已登录,且 RTC 和 RTM 实例的生命周期大于组件的生命周期。组件内部不负责维护 RTC,RTM 的初始化、生命周期以及鉴权/登录状态的逻辑。

注意

  • 发送图片消息功能目前处于 Beta 阶段,限时免费。
  • 图片处理能力依赖于 LLM 供应商提供的能力,你需要确保你接入对话式 AI 引擎的 LLM 供应商支持图片处理。

实现方法

集成组件

Maven (Maven)

在 Android 项目的 build.gradle 文件中添加如下依赖:

groovy
implementation 'io.agora.agents:agora-agent-client-toolkit:2.10.0'

源码集成 (源码集成)

将 convoaiApi 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。

CocoaPods (CocoaPods)

在 Podfile 中添加如下依赖:

Ruby
pod 'agent-client-toolkit-swift', '2.10.0'

Swift Package Manager (Swift Package Manager)

在 Xcode 中添加如下 Package URL,并将版本指定为 tag 2.10.0:

Text
https://github.com/AgoraIO/agent-client-toolkit-swift.git

源码集成 (源码集成)

将 ConversationalAIAPI 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。

Package Manager (Package Manager)

根据你的项目类型安装组件依赖。

  • Vanilla JS / TypeScript:

    Shell
    pnpm add agora-agent-client-toolkit@2.10.0
  • React:

    Shell
    pnpm add agora-agent-client-toolkit@2.10.0 agora-agent-client-toolkit-react@2.10.0

源码集成 (源码集成)

将 conversational-ai-api 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。

信息

如果在 Android 或 iOS 项目中同时集成多个声网 SDK 时出现库冲突,请参考多 SDK 库冲突处理。

初始化组件

为 RTC 和 RTM 实例创建配置对象,之后创建组件实例:

Kotlin
val config = ConversationalAIAPIConfig(
    rtcEngine = rtcEngine,
    rtmClient = rtmClient,
    renderMode = TranscriptRenderMode.Word,
    enableLog = true,
    enableRenderModeFallback = true
)

val api = ConversationalAIAPIImpl(config)

注册回调

调用 addHandler 方法注册回调:

Kotlin
api.addHandler(covEventHandler)

调用 addHandler 方法注册回调:

Swift
convoAIAPI.addHandler(handler: self)
TypeScript
// 监听消息回执更新
conversationalAIAPI.on(EConversationalAIAPIEvents.MESSAGE_RECEIPT_UPDATED, handleMessageReceiptUpdated)
// 监听智能体错误事件
conversationalAIAPI.on(EConversationalAIAPIEvents.MESSAGE_ERROR, onMessageError)

订阅频道消息

智能体的相关事件通过 RTM 频道消息传递,你需要在开始智能体会话前调用 subscribeMessage 订阅频道消息,以接收智能体相关事件。

Kotlin
api.subscribeMessage("channelName") { error ->
    if (error != null) {
        // 处理错误
    }
}

智能体加入频道

调用 POST 创建对话式智能体接口,并完成以下参数设置:

  • advanced_features.enable_rtm: true —— (必选)启动 RTM 服务
  • parameters.data_channel: "rtm" —— (必选)开启 RTM 数据传输通道
  • parameters.enable_metrics: true —— (按需开启)接收智能体性能数据
  • parameters.enable_error_message: true —— (按需开启)接收智能体错误事件

调用成功后,智能体会加入指定 RTC 频道,用户可以开始与智能体互动。

发送图片消息

调用 chat 方法,发送图片消息。以下为发送 URL 图片的示例:

注意

chat 接口的 completion 回调仅表示发送请求是否成功,不代表消息实际处理状态。

Kotlin
val uuid = "unique-image-id-123" // 生成唯一的图片标识符
val imageUrl = "https://example.com/image.jpg" // 图片的 HTTP/HTTPS URL

api.chat("agentUserId", ImageMessage(uuid = uuid, imageUrl = imageUrl)) { error ->
    if (error != null) {
        Log.e("Chat", "Failed to send image: ${error.errorMessage}")
    } else {
        Log.d("Chat", "Image send request successful")
    }
}

处理图片发送状态

图片消息发送的成功和失败分别通过图片消息回执 onMessageReceiptUpdated 和图片消息出错回调 onMessageError 确认,你需要根据图片的 uuid 来区分不同的图片消息。

图片发送成功

当收到 onMessageReceiptUpdated 回调时,需要解析回调中的 JSON 消息,获取图片的 uuid 以确认图片发送成功:

Kotlin
override fun onMessageReceiptUpdated(agentUserId: String, receipt: MessageReceipt) {
    if (receipt.chatMessageType == ChatMessageType.Image) {
        try {
            val json = JSONObject(receipt.message)
            // 检查是否包含 uuid 字段
            if (json.has("uuid")) {
                val receivedUuid = json.getString("uuid")

                // 如果 uuid 匹配,说明此图片发送成功
                if (receivedUuid == "your-sent-uuid") {
                    Log.d("ImageSend", "Image sent successfully: $receivedUuid")
                    // 更新 UI 显示发送成功状态
                }
            }
        } catch (e: Exception) {
            Log.e("ImageSend", "Failed to parse message receipt: ${e.message}")
        }
    }
}

图片发送失败

当收到 onMessageError 回调时,需要解析回调中的 JSON 消息,获取图片的 uuid 以确认图片发送失败:

Kotlin
override fun onMessageError(agentUserId: String, error: MessageError) {
    if (error.chatMessageType == ChatMessageType.Image) {
        try {
            val json = JSONObject(error.message)
            // 检查是否包含 uuid 字段
            if (json.has("uuid")) {
                val failedUuid = json.getString("uuid")

                // 如果 uuid 匹配,说明此图片发送失败
                if (failedUuid == "your-sent-uuid") {
                    Log.e("ImageSend", "Image send failed: $failedUuid")
                    // 更新 UI 显示发送失败状态
                }
            }
        } catch (e: Exception) {
            Log.e("ImageSend", "Failed to parse error message: ${e.message}")
        }
    }
}

取消订阅频道消息

每次智能体会话结束后,你需要取消订阅频道消息,以释放回调事件相关资源。

Kotlin
api.unsubscribeMessage("channelName") { error ->
    if (error != null) {
        // 处理错误
    }
}

销毁组件实例

结束 AI 对话场景后或关闭 App 前,你需要销毁组件实例,以释放组件的所有资源。

Kotlin
api.destroy()

参考信息

示例项目

声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。

API 参考