# 第十九章 多模态：图像、音频、视频——ImageBlock 统一替换为 DataBlock


>1.x 的 `ImageBlock` / `AudioBlock` / `VideoBlock` 在 2.0.0中**被统一替换为 `DataBlock`**，通过 `mediaType` 字段区分类型。
旧代码里 `new ImageBlock(...)` / `new AudioBlock(...)` 在 2.0 中**仍然兼容**（标 `@Deprecated`），但新代码请统一用 `DataBlock`。
本章先给旧 API 对照，再讲 `DataBlock` 的统一用法。


>**依赖**：多模态模型需通过 OpenAI 兼容端点调用，依赖 `agentscope-extensions-model-openai`。
DashScope 专有协议暂不支持多模态——示例使用 `OpenAIChatModel` + DashScope 兼容地址
`https://dashscope.aliyuncs.com/compatible-mode/v1`。


## 19.1 1.x 与 2.0 对照


|1.x|2.0|
|:-:|:-:|
|`ImageBlock`|`DataBlock.builder().mediaType("image/png")`|
|`AudioBlock`|`DataBlock.builder().mediaType("audio/mp3")`|
|`VideoBlock`|`DataBlock.builder().mediaType("video/mp4")`|
|`Base64Source`|`Base64Source`（保留，但走 `DataBlock.source(...)`）|
|`URLSource`|`URLSource`（保留，走 `DataBlock.source(...)`）|

## 19.2 第一个多模态消息


**这个例子在演示什么？**

>用 `DataBlock` 把一张本地图片（PNG 文件）编码为 Base64，和文本拼成一条多模态消息发给 Agent。Agent 收到的不再是纯文本，而是"文字 + 图片"——它能看到图片内容并给出描述。


```
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.Base64Source;
import io.agentscope.core.message.DataBlock;
import io.agentscope.core.message.TextBlock;
import io.agentscope.core.message.UserMessage;
import io.agentscope.extensions.model.openai.OpenAIChatModel;
import io.agentscope.harness.HarnessAgent;

import java.nio.file.Files;
import java.util.Base64;
import java.util.List;

public class Chapter19_Multimodal {

    public static void main(String[] args) throws Exception {
        // 1. 读图片并编码 base64
        byte[] bytes = Files.readAllBytes(Path.of("./cat.png"));
        String b64 = Base64.getEncoder().encodeToString(bytes);

        // 2. 构造 DataBlock
        DataBlock imageBlock = DataBlock.builder()
                .source(Base64Source.builder()
                        .data(b64)
                        .mediaType("image/png")
                        .build())
                .build();

        // 3. 多模态 user 消息
        UserMessage msg = new UserMessage(
                "user",
                TextBlock.builder().text("这张图片里有什么？").build(),
                imageBlock);

        // 4. agent 调用
        HarnessAgent agent = HarnessAgent.builder()
                .name("vision_bot")
                .sysPrompt("你是一个视觉助理，详细描述图片。")
                .model(OpenAIChatModel.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .modelName("qwen3-omni-flash")
                        .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                        .stream(true)
                        .formatter(new OpenAIChatFormatter())
                        .build())
                .workspace(Path.of("./workspace"))
                .build();

        System.out.println(agent.call(List.of(msg), RuntimeContext.empty()).block().getTextContent());
    }
}
```
## 19.3 `DataBlock` 字段


`DataBlock`（`io.agentscope.core.message`）核心字段：


|字段|类型|说明|
|:-:|:-:|:-:|
|`source`|`Source`|数据来源，必填|
|`mediaType`|`String`|MIME 类型（`image/png` / `audio/mp3` / `video/mp4` / `application/pdf`）|
|`name`|`String`|可选文件名|
|`metadata`|`Map`|业务方附加元信息|

`Source` 有两种：


- **`Base64Source`** —— 内联 base64 编码数据

- **`URLSource`** —— 远程 URL，agent 自动下载


## 19.4 音频 / 视频


视频和音频的 `DataBlock` 构造和图片一模一样，换个 `mediaType` 就行。但同样的代码，图片能跑、音频和视频跑不了。

限制不在 DashScope 本身，在 AgentScope 的内置 ChatModel。`OpenAIChatModel` 也好、`DashScopeChatModel` 也好，底层全部走 REST HTTP 协议。HTTP 请求体的多模态字段只支持 `image_url` 这一种格式，`input_audio` 和视频帧都塞不进去。

DashScope 自己是能处理音频的，只是需要走不同的协议通道：


- **WebSocket 实时流**。Qwen-Omni 实时对话、语音识别都是 WebSocket 长连接，双向推流。AgentScope 没有内置 WebSocket 客户端。

- **DashScope 原生 HTTP 多模态格式**。ONE-PEACE、Qwen-VL 这些模型支持 HTTP 传入音频 URL，但走的是 DashScope 自有协议，不是 OpenAI 兼容格式。


两条路都能通，但都不在 AgentScope 的 ChatModel 覆盖范围内。想用的话，学第 20 章 TTS 的做法：自己用 `@Tool` 包装 DashScope SDK，AgentScope 只负责调工具、不在框架层处理音频字节。

本章示例聚焦图片。图片是 REST 端点唯一稳定支持的多模态输入，也是绝大多数业务最常用的多模态场景。

## 19.5 与 Tool 的协作


业务方工具可以**返回** `DataBlock` —— 适合 OCR / 截图 / 渲染结果：

```
@Tool(name = "screenshot_page", description = "截图某个 URL")
public DataBlock screenshot(
        @ToolParam(name = "url") String url) throws Exception {

    // 调 puppeteer / playwright 拿 png
    byte[] png = playwright.screenshot(url);
    String b64 = Base64.getEncoder().encodeToString(png);

    return DataBlock.builder()
            .source(Base64Source.builder()
                    .data(b64)
                    .mediaType("image/png")
                    .build())
            .name("screenshot.png")    // name 挂在 DataBlock 上，不是 Base64Source
            .build();
}
```
LLM 看到工具返回 `DataBlock` 会自动把它纳入上下文——框架内部会把 `DataBlock` 包装成 `ToolResultBlock` 再发给 LLM，无需手动构造。

## 19.6 1.x 旧代码的兼容路径


`ImageBlock` / `AudioBlock` / `VideoBlock` 在 2.0 仍存在（标 `@Deprecated`）：

```
// 1.x 老代码仍能跑
import io.agentscope.core.message.ImageBlock;

ImageBlock oldStyle = new ImageBlock(b64, "image/png");   // 2.0 编译会出 warning
```
`ImageBlock` 内部就是 `DataBlock.builder().mediaType("image/...")`。建议**新代码统一用 `DataBlock`**；老代码改起来很便宜（1 行换 1 行）。

## 19.7 完整可运行示例


**这个例子在演示什么？**

>一条消息里同时拼了两种来源的图片：本地文件走 `Base64Source`（内联编码）、远程 URL 走 `URLSource`（引用地址）。Agent 一次性拿到两张图，可以对比分析。这就是多模态的本质——不限制 Block 数量，需要几个拼几个。


```
public class Chapter19_FullMultimodal {

    public static void main(String[] args) throws Exception {
        // 方式一：本地文件 Base64 内联
        DataBlock fromFile = DataBlock.builder()
                .source(Base64Source.builder()
                        .data(Base64.getEncoder().encodeToString(
                                Files.readAllBytes(Path.of("./cat.png"))))
                        .mediaType("image/png")
                        .build())
                .build();

        // 方式二：远程 URL 引用
        DataBlock fromUrl = DataBlock.builder()
                .source(URLSource.builder()
                        .url("https://example.com/dog.jpg")
                        .mimeType("image/jpeg")
                        .build())
                .build();

        UserMessage msg = new UserMessage(
                "user",
                TextBlock.builder().text("对比这两张图片有什么不同。").build(),
                fromFile,
                fromUrl);

        HarnessAgent agent = HarnessAgent.builder()
                .name("multimodal_bot")
                .sysPrompt("你是多模态助理，可以理解图片内容。")
                .model(OpenAIChatModel.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .modelName("qwen3-omni-flash")
                        .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                        .stream(true)
                        .formatter(new OpenAIChatFormatter())
                        .build())
                .workspace(Path.of("./workspace"))
                .build();

        System.out.println(agent.call(List.of(msg), RuntimeContext.empty()).block().getTextContent());
    }
}
```
>音频/视频的 `DataBlock` 构造方式和图片完全一样，只需改 `mediaType`。是否能被模型理解取决于模型端点的协议支持——大部分 REST HTTP 端点仅支持图片多模态，音频/视频输入需要 WebSocket 实时协议。


## 19.8 最小迁移清单（1.x ImageBlock → 2.0 DataBlock）


|1.x用法|2.0等价|
|:-:|:-:|
|`new ImageBlock(b64, "image/png")`|`DataBlock.builder().source(Base64Source.builder().data(b64).mediaType("image/png").build()).build()`|
|`new AudioBlock(b64, "audio/mp3")`|`DataBlock.builder().mediaType("audio/mp3")`|
|`new VideoBlock(url, "video/mp4")`|`DataBlock.builder().source(URLSource.builder().url(url).mimeType("video/mp4").build())`|
|`msg.getContentBlocks(ImageBlock.class)`|`msg.getContentBlocks(DataBlock.class)` 后按 `mediaType` 区分|

## 19.9 本章小结


- 2.0 用 `DataBlock` 统一图片 / 音频 / 视频 / 文件。

- 旧 `ImageBlock` / `AudioBlock` / `VideoBlock` 仍兼容但被弃用。

- 工具可返回 `DataBlock` —— LLM 自动纳入上下文。

- `mediaType` 字段决定 LLM 端路由（视觉 / 音频 / 视频模型）。

1.x 的 ImageBlock  AudioBlock  VideoBlock 在 2.0.0中被统一替换为 DataBlock，通过 mediaType 字段区分类型。旧代码里 new ImageBlock(...) / new AudioBlock(...) 在 2.0 中仍然兼容（标 @Deprecated），但新代码请统一用 DataBlock。本章先给旧 API 对照，再讲 DataBlock 的统一用法。

【AgentScope Java新手村系列】（19）多模态-图像音频视频

多模态 — 废弃 ImageBlock/AudioBlock/VideoBlock，统一用 DataBlock + Base64Source 内联或 URLSource 远程引用图片。一条消息可拼多个 Block，REST 端点仅稳定支持图片。

编程语言

开发工具

人工智能

AgentScope 2.0将ImageBlock、AudioBlock、VideoBlock统一为DataBlock，通过mediaType字段区分类型。支持Base64和URL两种数据源，兼容旧API但推荐使用新标准。多模态消息可组合文本与图片/音频/视频，需通过OpenAI兼容端点调用。

语音识别

代码解释

WebSocket

路由

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【AgentScope Java新手村系列】（19）多模态-图像音频视频-腾讯云开发者社区-腾讯云

【AgentScope Java新手村系列】（19）多模态-图像音频视频

【AgentScope Java新手村系列】（19）多模态-图像音频视频

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐