AI 助手
扣子 AI 帮助与支持
你好,我是 扣子 文档问答助手 🎉 你在阅读当前文档的过程中,无论对文档概念的解释,还是文档内容方面的疑问,都可以随时向我提问,我会全力为你解答
推荐问题
扣子 3.0 都有什么新特性?
扣子和扣子编程有什么区别?
扣子如何收费?
文档反馈

向评测集添加多模态数据

复制页面

扣子罗盘支持全链路的多模态评测,准备多模态的评测集数据后,可以基于评测集发起针对多模态 Agent 的评测实验。本文档介绍如何准备多模态的评测集。

什么是多模态数据

多模态数据,可以是图片、音频或视频,也可以是文字、图片、音频与视频的组合。
以下示例展示了混合了文字、图片、音频和视频的多模态数据。该数据的结构为 Array<Object>,其中每个 Object 的 key 指明了多模态类型,value 为对应的数据。
对于图片、音频和视频,其 value 均为 URL。在你向评测集添加数据时,扣子罗盘处理此 URL 的方式有两种:

  • 上传源文件:扣子罗盘会将文件上传至云端,并自动将生成的 URL 填入 value。
  • 使用外部链接:扣子罗盘会直接将你提供的链接填入 value。
[
  {
    "type": "text",
    "text": "What is in this image?"
  },
  {
    "type": "image_url",
    "image_url": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
    }
  },
  {
    "type": "audio_url",
    "audio_url": {
      "url": "https://example.com/audio"
    }
  },
  {
    "type": "video_url",
    "video_url": {
      "url": "https://example.com/video"
    }
  }
]

步骤一:创建多模态类型的评测集

创建多模态评测集的操作步骤如下:

  1. 登录扣子罗盘。
  2. 在左侧导航栏顶部,选择一个空间。
  3. 在左侧导航栏选择评测 > 评测集,然后单击 + 新建评测集。
    Image
  4. 在新建评测集页面,为评测集设置名称和描述。
  5. 配置评测集的列,确保评测集中存在多模态类型的字段。
    例如评测一个支持图片理解的 Agent,评测集的输入字段(input)设置为多模态,数据结构固定为 Arrary,且不可编辑。
    Image
  6. 单击创建。
  7. 步骤二:上传多模态数据

    创建评测集并定义多模态数据结构之后,即可上传多模态的测试数据。

    手动添加数据

    1. 在评测集详情页面,选择添加数据 > 手动添加来添加测试数据。
      Image
    2. 在添加数据页面,输入第一组测试数据。
      对于多模态类型的字段,单击添加数据,最多可添加 50 条。多模态字段支持以下类型:
      • 文本:文本格式的内容。
      • 图片:​图片格式的内容。
        • 源文件:本地上传图片文件。单个图片文件不能超过 20 MB。支持一次上传多张图片。
        • 外链:输入在线图片 URL。上传时扣子罗盘会校验 URL 有效性。如果上传的图片链接解析失败,可以检查 URL 是否以 http:// 或 https:// 开头、域名格式是否正确,或尝试更换其他 URL。

          说明

          为了提升多模态数据的稳定性和访问可靠性,扣子罗盘在导入外部 URL 资源(图片、视频、音频)时提供了“转存”和“不转存”两种策略。详情参阅 多模态数据的转存策略。

          Image
      • 视频:视频格式的内容。
        • 源文件:本地上传视频文件。单个视频文件不能超过 100 MB。支持一次上传多个视频。
        • 外链:输入在线视频 URL。上传时扣子罗盘会校验 URL 有效性。如果上传的视频链接解析失败,可以检查 URL 是否以 http:// 或 https:// 开头、域名格式是否正确,或尝试更换其他 URL。

          说明

          为了提升多模态数据的稳定性和访问可靠性,扣子罗盘在导入外部 URL 资源(图片、视频、音频)时提供了“转存”和“不转存”两种策略。详情参阅 多模态数据的转存策略。

          Image
      • 音频:​音频格式的内容。
        • 源文件:本地上传音频文件。单个音频文件不能超过 100 MB。支持一次上传多个音频。
        • 外链:输入在线音频 URL。上传时扣子罗盘会校验 URL 有效性。如果上传的音频链接解析失败,可以检查 URL 是否以 http:// 或 https:// 开头、域名格式是否正确,或尝试更换其他 URL。

          说明

          为了提升多模态数据的稳定性和访问可靠性,扣子罗盘在导入外部 URL 资源(图片、视频、音频)时提供了“转存”和“不转存”两种策略。详情参阅 多模态数据的转存策略。

        Image
    3. 单击 + 添加数据项 添加更多测试数据。
    4. 单击 添加 完成数据添加。

    上传本地文件

    向评测集中上传包含多模态数据的本地文件。

    格式要求

    详细说明可参考多模态文件格式要求。

    上传步骤

    1. 在评测集详情页面,选择添加数据 > 本地导入来添加测试数据。
      Image
    2. 在导入数据对话框,上传要导入的测试数据文件。
    3. 当完成数据导入后,将文件中的数据列与评测集的数据列进行映射。

      注意

      • 确保在配置列映射关系时,文件中指定列的数据格式与评测集对应格式一致。如果不一致,你需要手动设置。
      • 由于 CSV、Excel 文件不包含数据类型信息,上传时,扣子罗盘会根据文件中每行的数据内容来校验其数据格式。如果校验不通过,该行数据将不会被上传。
        例如,CSV 文件中有一列 A,包含两行数据 10 和 helloworld。在创建评测集时,你指定了列 B 的数据类型为 int。当添加数据时,将 CSV 中的列 A 映射到评测集的列 B,即将 CSV 的 A 列数据导入到评测集的 B 列。在上传校验过程中,由于 B 列的数据类型为 int,helloworld 这一行数据将无法导入。
      • CSV 模板和 EXCEL模板支持导入图片源文件和 URL;对于视频/音频,仅支持通过 URL 导入。
      • ZIP 模板支持通过 URL 或文件的相对路径导入视频/音频。
      Image
      如果你的文件列中只包含纯 URL(例如 http://.../a.png),而没有使用 <ref_*_url:...> 标签进行类型声明,系统会在此处提示你为该列指定模态类型(图片、视频或音频)。
      Image
    4. (可选)点击指定多模态列右侧的齿轮图标,为指定列统一选择多模态数据转存策略:转存到平台存储 或 保留原始 URL,不转存。详情参阅 多模态数据的转存策略。默认为 转存到平台存储。

      说明

      如果选择了 转存到平台存储,但某条数据的 URL 无法访问或下载失败,该条数据将被跳过。如果平台校验发现资源类型与声明不符(例如链接指向一个视频但声明为图片),该条数据也将被跳过。所有因格式校验或转存失败而被跳过的数据行,都会被自动汇总到一个 Excel 文件中,你可以在导入任务的详情页面下载该文件进行核对。

      Image
    5. 选择一种导入方式,追加数据或者全量覆盖已有测试数据。
      Image
    6. 单击导入。

    Trace 回流评测集

    扣子罗盘 SDK 支持将 Trace 数据回流至评测集,我们可以将多模态 Agent 线上的真实对话对应的 Trace 数据回流到评测集中,作为评测实验的评测集,用于评估多模态 Agent 的图片理解能力。
    操作步骤如下:

    1. 在左侧导航栏,选择观测 > Trace,并使用过滤器筛选出多模态 Agent 的 Trace 数据。
      筛选出带有多模态(图片)问题和回复的 Span 节点,通常是 root span 节点。
    2. 在页面右上角单击添加到评测集。
    3. 选择需要回流的 Trace 数据,并再次单击添加到评测集。
    4. 根据页面提示配置字段映射,依次将用户问题、多模态数据、Agent 回复回流至评测集的对应字段。
      需要注意的是,对于多模态字段(图片),需要为其映射评测集的多模态类型字段。关于回流 Trace 到评测集的详细操作步骤、字段映射配置可参考Trace 数据回流。

    相关信息

    多模态数据的转存策略

    为了提升多模态数据的稳定性和访问可靠性,扣子罗盘在导入外部 URL 资源(图片、视频、音频)时提供了 转存到平台存储 和 保留原始 URL,不转存 两种策略。你在通过 手动添加数据 或 上传本地文件 导入包含外部 URL 的多模态列时,可以在页面中选择对应的转存策略。
    Image
    下面对两种转存策略进行说明:

    • 转存到平台存储:平台将自动抓取你提供的外部 URL 资源,并将其下载、保存至扣子罗盘内部的对象存储服务中。数据集中最终引用的是平台内部的稳定链接。这是推荐的默认选项,尤其适用于长期评测、模型训练或生产环境。通过转存,可以避免因原始链接失效、过期或访问策略变更而导致的数据丢失或模型推理失败问题。数据持久性高,访问速度和稳定性由平台保障。
    • 保留原始 URL,不转存:平台直接记录并使用你提供的原始外部 URL,不做任何下载或存储操作。适用于临时性的数据验证,或者当你的多模态资源已托管在有高可用保障的公有云 CDN(内容分发网络)上,且链接为永久公开、无需鉴权时。你必须自行确保 URL 的长期有效性和可访问性。如果原始链接失效,将直接影响后续的模型访问,可能导致评测或训练任务失败。

      使用外部 URL 的注意事项

      当你选择“不转存”策略,直接使用原始 URL 时,请务必确认以下事项,以避免数据不可用导致的各类问题:

      • URL 公开可访问:确保 URL 指向的是公网地址,不包含任何 IP 白名单、内网限制或需要登录才能访问的内容。
      • 链接长期有效:避免使用包含临时签名或访问令牌的 URL(例如各类云存储的预签名 URL),这类链接会在短时间后失效。
      • 源站性能:确认你的资源服务器具备足够的带宽和并发处理能力,以承受模型在训练或评测时可能发起的高频、批量访问。
      • 资源稳定性:确保 URL 指向的资源在模型使用期间不会被删除、移动或替换。

      若 URL 失效,将直接导致模型推理或训练失败。为保障数据完整性和任务稳定性,强烈建议你优先选择“转存到平台存储”。

    多模态文件格式要求

    CSV

    • 首行为标题行,表示列名,也就是字段名称。
    • CSV 文件必须是 UTF-8 编码。
    • 对于多模态的内容,其格式要求如下:

      说明

      如果你的列中直接填写了无标签的纯 URL(例如 http://.../a.png),在导入时,你需要为该列手动指定模态类型(如“图片”)。同一列中的所有纯 URL 必须属于同一种模态类型。
      同一列内不建议纯 URL 和带标签的的 URL 混用。

      多模态类型

      格式要求

      图片

      使用图片 URL 来引用图片。多张图片之间通过换行符隔开。例如:

      <ref_image_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/37361.png>
      <ref_image_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/doubao_v2.png>
      

      音频

      使用音频 URL 来引用图片。多个音频之间通过换行符隔开。例如:

      <ref_audio_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/speech_01.mp3>
      <ref_audio_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/speech_02.mp3>
      

      视频

      使用视频 URL 来引用图片。多个视频之间通过换行符隔开。例如:

      <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/video_01.mp3>
      <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/video_02.mp3>
      

      文字、图片、音频、视频混排

      文字、图片、音频、视频混合排列。列内容也可以是纯文本,上传评测集时平台可正常解析。
      例如:

      这是一张图片
      <ref_image_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/37361.png>
      这是一段音频
      <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/speech_01.mp3>
      这是一段视频
      

    Excel

    • 首行为标题行,表示列名,也就是字段名称。
    • 支持 *.xlsx、*.xls 格式的 Excel 表格文件。
    • 对于多模态的内容,其格式要求如下:

      说明

      如果你的列中直接填写了无标签的纯 URL(例如 http://.../a.png),在导入时,你需要为该列手动指定模态类型(如“图片”)。同一列中的所有纯 URL 必须属于同一种模态类型。
      同一列内不建议纯 URL 和带标签的的 URL 混用。

      多模态类型

      格式要求

      单张图片

      在 Excel 格式下可导入通过 URL 引用或嵌入到单元格中的图片。url的引用格式为 <ref_image_url:{替换为有效的图片链接}>,例如:

      • 嵌入:
        Image
      • URL 引用:
        Image

      多张图片

      图片与图片之间通过换行符隔开,多图片列仅支持通过 url 引用,不支持直接嵌入图片。例如:

      <ref_image_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/37361.png>
      <ref_image_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/doubao_v2.png>
      

      单个音频

      在 Excel 格式下可导入通过 URL 引用或嵌入到单元格中的音频。
      URL 引用格式为:

      <ref_audio_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/speech_01.mp3>
      

      多个音频

      使用音频 URL 来引用图片。多个音频之间通过换行符隔开。例如:

      <ref_audio_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/speech_01.mp3>
      <ref_audio_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/speech_02.mp3>
      

      单个视频

      在 Excel 格式下可导入通过 URL 引用或嵌入到单元格中的图片。
      URL 引用格式为:

      <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/video_01.mp3>
      

      多个视频

      使用视频 URL 来引用图片。多个视频之间通过换行符隔开。例如:

      <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/video_01.mp3>
      <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/video_02.mp3>
      

      文字、图片、音频、视频混排

      文字、图片、音频、视频混合排列。其中图片、音频和视频仅支持通过 url 引用,不支持直接嵌入。
      也可以是纯文本格式。
      例如:

      这是一张图片
      <ref_image_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/37361.png>
      这是一段音频
      <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/speech_01.mp3>
      这是一段视频
      

    ZIP

    ZIP 文件通常用于多模态场景,你可以通过 ZIP 文件将多模态内容打包在一起,并以 index.csv 作为索引文件。ZIP 包的结构示例如下:

    ZIP 模板  // ZIP包
    ├── images   
    │   ├── pic1.png
    │   ├── pic2.jpeg
    │   └── pic3.webp
    │   └── pic4.jpeg
    ├── videos  
    │   ├── video_01.mp3
    │   ├── video_02.mov
    │   └── video_03.mp4
    ├── audios  
    │   ├── speech_01.mp3
    │   ├── speech_02.mp3
    │   └── speech_03.mp3
    └── index.csv  // 名称固定index.csv 
    

    对于多模态的内容,其格式要求如下:

    说明

    如果你的列中直接填写了无标签的纯 URL(例如 http://.../a.png),在导入时,你需要为该列手动指定模态类型(如“图片”)。同一列中的所有纯 URL 必须属于同一种模态类型。
    同一列内不建议纯 URL 和带标签的的 URL 混用。

    多模态类型

    格式要求

    单张图片

    在 index.csv 索引文件中引用图片,支持 URL 方式引用、嵌入图片文件,或者引用 Zip 压缩包中的文件。示例如下:

    • url 引用:url 的引用格式为 <ref_image_url:{替换为有效的图片链接}>,例如:
      Image
    • 嵌入:
      Image
    • 引用 Zip 压缩包中的图片文件:使用Zip 压缩包中的图片文件的相对路径。
      Image

    多张图片

    图片与图片之间通过换行符隔开,多图片列支持引用图片 URL 或者引用压缩包中的图片文件,不支持直接嵌入图片。例如:

    <ref_image_url:images/pic1.png>
    <ref_image_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/doubao_v2.png>
    

    音频

    引用 URL 或者引用压缩包中的文件。多个音频之间通过换行符隔开。例如:

    <ref_audio_url:https://lf9-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/speech_01.mp3>
    <ref_audio_path:audios/audio1.mp3>
    

    视频

    引用 URL 或者引用压缩包中的文件。多个视频之间通过换行符隔开。例如:

    <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/video_01.mp3>
    <ref_video_path:audios/video1.mp3>
    

    文字、图片、音频、视频混排

    文字、图片、音频、视频混合排列,其中图片、音频和视频仅支持引用 URL 或者引用压缩包中的文件,不支持直接嵌入。
    列内容也可以是纯文本,上传评测集时平台可正常解析。
    例如:

    图片:
    <ref_image_path:images/pic1.png>
    音频:
    <ref_audio_path:audios/audio1.mp3>
    视频:
    <ref_video_url:https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/MODEL_ICON/vedio2.mp3>