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

在 AgentScope 2.0.0 中，1.x 版本的 ImageBlock、AudioBlock、VideoBlock 已被统一替换为 DataBlock。新的 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 版本中多模态数据块的主要对应关系：

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 ja va.nio.file.Files;
import ja va.util.Base64;
import ja va.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. 创建多模态用户消息，包含文本和图片块
    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 有两种实现：

• 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 编译时会显示警告

ImageBlock 内部实际上就是对 DataBlock.builder().mediaType("image/...") 的封装。建议新代码统一使用 DataBlock；对于旧代码，迁移的成本也很低（几乎是 1 行代码替换为 1 行代码）。

小提示：在过渡期间，可以暂时保留旧代码，但应规划逐步迁移到 DataBlock，以享受更统一和未来的 API 支持。

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）

19.9 本章小结

• 在 AgentScope 2.0 中，使用 DataBlock 统一处理图片、音频、视频和文件等多种数据类型。
• 旧的 ImageBlock、AudioBlock 和 VideoBlock 虽然仍兼容，但已被弃用，建议优先使用 DataBlock。
• 工具方法可以返回 DataBlock，LLM 会自动将其纳入上下文，简化了多模态工具结果的传递。
• DataBlock 的 mediaType 字段决定了 LLM 端点的路由（视觉、音频或视频模型），正确设置至关重要。