API详情_模型服务灵积(DashScope)-阿里云帮助中心

前言

ONE-PEACE是一个图文音三模态通用表征模型，在语义分割、音文检索、音频分类和视觉定位几个任务都达到了新SOTA表现，在视频分类、图像分类图文检索、以及多模态经典benchmark也都取得了比较领先的结果。另外，模型展现出来新的zeroshot能力，即实现了新的模态对齐，比如音频和图像的对齐，或者音频+文字和图像的对齐，而这类数据并没有出现在我们的预训练数据集里。

下面这张图展示了ONE-PEACE的模型架构和预训练任务。借助于扩展友好的架构和模态无关的任务，ONE-PEACE具备扩展到无限模态的潜力

作为一个4B规模的通用表征模型，ONE-PEACE在一系列视觉、语音和多模态任务上取得领先的结果。此外，ONE-PEACE还具备强大的多模态检索能力，能够完成图文音三模态之间的互相检索。如下图所示，我们通过case展示了ONE-PEACE的音搜图，音+图搜图，以及音+文搜图的能力。

模型局限：模型主要使用开源的英文数据进行训练，因此中文的表征能力可能不太理想

模型概览

模型中文名	模型英文名	数据类型	向量维度
ONE-PEACE通用表征模型	multimodal-embedding-one-peace-v1	float(32)	1536

SDK使用

前提条件

已开通服务并获得API-KEY：API-KEY的获取与配置。
已安装最新版SDK：安装DashScope SDK。

调用示例

说明

需要使用您的API-KEY替换示例中的 YOUR_DASHSCOPE_API_KEY，代码才能正常运行。

设置API-KEY

 export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

代码示例

生成图片embedding示例

单独输入1张图片

Python

from dashscope import MultiModalEmbedding


def image_embedding():
    input = [{'image': 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png'},
             ]
    result = MultiModalEmbedding.call(model=MultiModalEmbedding.Models.multimodal_embedding_one_peace_v1,
                                      input=input,
                                      auto_truncation=True)
    print(result)


if __name__ == '__main__':
    image_embedding()

Java

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.embeddings.MultiModalEmbedding;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemImage;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingParam;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;

import java.util.Arrays;


public class Main {
  public static void imageEmbedding() throws ApiException, NoApiKeyException, UploadFileException {
    MultiModalEmbedding embedding = new MultiModalEmbedding();
    MultiModalEmbeddingItemImage image =
        new MultiModalEmbeddingItemImage(
            "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png");    
    MultiModalEmbeddingParam param =
        MultiModalEmbeddingParam.builder()
            .model(MultiModalEmbedding.Models.MULTIMODAL_EMBEDDING_ONE_PEACE_V1)
            .contents(Arrays.asList(image))
            .build();
    MultiModalEmbeddingResult result = embedding.call(param);
    System.out.print(result);
  }


  public static void main(String[] args){
      try {
        imageEmbedding();
      } catch (ApiException | NoApiKeyException | UploadFileException e) {
        System.out.println(e.getMessage());
      }
      System.exit(0);
  }
}

图片&语音embedding示例

结合图片和语音，生成Embedding。

Python

from dashscope import MultiModalEmbedding


def image_audio_embedding():
    input = [{'audio': 'https://dashscope.oss-cn-beijing.aliyuncs.com/audios/cow.flac'},
             {'image': 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png'}]
    result = MultiModalEmbedding.call(model=MultiModalEmbedding.Models.multimodal_embedding_one_peace_v1,
                                      input=input,
                                      auto_truncation=True)
    print(result)


if __name__ == '__main__':
    image_audio_embedding()

Java

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.embeddings.MultiModalEmbedding;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemAudio;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemImage;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingParam;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;

import java.util.Arrays;


public class Main {
  public static void imageAndAudioEmbedding() throws ApiException, NoApiKeyException, UploadFileException {
    MultiModalEmbedding embedding = new MultiModalEmbedding();
    MultiModalEmbeddingItemImage image =
        new MultiModalEmbeddingItemImage(
            "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png");

    MultiModalEmbeddingItemAudio audio = new MultiModalEmbeddingItemAudio("https://dashscope.oss-cn-beijing.aliyuncs.com/audios/cow.flac");
    
    MultiModalEmbeddingParam param =
        MultiModalEmbeddingParam.builder()
            .model(MultiModalEmbedding.Models.MULTIMODAL_EMBEDDING_ONE_PEACE_V1)
            .contents(Arrays.asList(audio, image))
            .build();
    MultiModalEmbeddingResult result = embedding.call(param);
    System.out.print(result);
  }


  public static void main(String[] args){
      try {
        imageAndAudioEmbedding();
      } catch (ApiException | NoApiKeyException | UploadFileException e) {
        System.out.println(e.getMessage());
      }
      System.exit(0);
  }
}

多模态混合embedding示例

如果您需要混合使用多种模态的数据来产生多模态的向量表征Embedding，也可以通过配置多种模态数据，并在必要的时候配置不同的表征权重，来生成综合向量Embedding。这里示例为文本，图像和语音的混合模态示例，并且对于每个item都配置了不同的权重。值得注意的是，每条item中权重的数值均可单独配置，不填写时默认为1。

Python

from dashscope import MultiModalEmbedding


def multimodal_with_factor_embedding():
    input = [{'factor': 1, 'text': '你好'},
             {'factor': 2, 'audio': 'https://dashscope.oss-cn-beijing.aliyuncs.com/audios/cow.flac'},
             {'factor': 3, 'image': 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png'}]
    result = MultiModalEmbedding.call(model=MultiModalEmbedding.Models.multimodal_embedding_one_peace_v1,
                                      input=input,
                                      auto_truncation=True)
    print(result)


if __name__ == '__main__':
    multimodal_with_factor_embedding()

Java

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.embeddings.MultiModalEmbedding;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemAudio;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemImage;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemText;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingParam;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;

import java.util.Arrays;

public class Main {
  public static void multiModalWithFactorEmbedding() throws ApiException, NoApiKeyException, UploadFileException {
    MultiModalEmbedding embedding = new MultiModalEmbedding();
    MultiModalEmbeddingItemText text =
        MultiModalEmbeddingItemText.builder()
            .text("冬雪")
            .factor(2.0)
            .build();
    MultiModalEmbeddingItemImage image =
        new MultiModalEmbeddingItemImage(
            "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png",
            1.0);

    MultiModalEmbeddingItemAudio audio = 
    new MultiModalEmbeddingItemAudio("https://dashscope.oss-cn-beijing.aliyuncs.com/audios/cow.flac",
    1.0);
    
    MultiModalEmbeddingParam param =
        MultiModalEmbeddingParam.builder()
            .model(MultiModalEmbedding.Models.MULTIMODAL_EMBEDDING_ONE_PEACE_V1)
            .contents(Arrays.asList(audio, image, text))
            .build();
    MultiModalEmbeddingResult result = embedding.call(param);
    System.out.print(result);
  }

  public static void main(String[] args){
      try {
        multiModalWithFactorEmbedding();
      } catch (ApiException | NoApiKeyException | UploadFileException e) {
        System.out.println(e.getMessage());
      }
      System.exit(0);
  }
}

本地文件调用

您也可以通过本地文件调用接口，示例如下，您需要按照示例所示文件路径格式输入。

Python

from dashscope import MultiModalEmbedding


def call_with_local_file():
    """Sample of use local file.
       linux&mac file format: file:///home/images/test.png
       windows file format: file://D:/images/abc.png
    """
    # file path must absolute path
    input = [{'image': 'file://absolute_local_path'},
             {'image': 'file://absolute_local_path2'}]
    result = MultiModalEmbedding.call(
        model=MultiModalEmbedding.Models.
        multimodal_embedding_one_peace_v1,
        input=input,
        auto_truncation=True)
    print(result)


if __name__ == '__main__':
    call_with_local_file()

Java

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.embeddings.MultiModalEmbedding;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemImage;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemText;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingParam;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import java.util.Arrays;

public class Main {
  /*
   * sample of use local file
   * Windows file format: file:///D:/test/images/test.png
   * Linux & Mac format: file://The_absolute_local_path
   * 
   */

  public static void callWithLocalFile() throws ApiException, NoApiKeyException, UploadFileException {
    MultiModalEmbedding embedding = new MultiModalEmbedding();
    MultiModalEmbeddingItemText text = MultiModalEmbeddingItemText.builder().text("冬雪").build();
    String localFilePath = "file:///home/tests/image.png";
    String localFilePath2 = "file:///home/tests/image.png";
    MultiModalEmbeddingItemImage image = new MultiModalEmbeddingItemImage(localFilePath);
    MultiModalEmbeddingItemImage image2 = new MultiModalEmbeddingItemImage(localFilePath2);
    MultiModalEmbeddingParam param = MultiModalEmbeddingParam.builder()
        .model(MultiModalEmbedding.Models.MULTIMODAL_EMBEDDING_ONE_PEACE_V1)
        .contents(Arrays.asList(image, image2, text))
        .build();
    MultiModalEmbeddingResult result = embedding.call(param);
    System.out.print(result);
  }

  public static void main(String[] args) {
    try {
      callWithLocalFile();
    } catch (ApiException | NoApiKeyException | UploadFileException e) {
      System.out.println(e.getMessage());
    }
    System.exit(0);
  }
}

输出示例

JSON

{
    "status_code": 200,
    "request_id": "the_request_Id",
    "code": "",
    "message": "",
    "output": {
        "embedding": [
            -0.0200169887393713,
            0.041749317198991776
            ... ...
        ]
    },
    "usage": {
        "image": {
            "measure": 1,
            "weight": 1
        },
        "total_usage": 4,
        "audio": {
            "measure": 1,
            "weight": 2
        },
        "text": {
            "measure": 1,
            "weight": 1
        }
    }
}

参数详解

请求参数

参数名称	必选	示例值	描述
model	是	multimodal-embedding-one-peace-v1	取值：该值是固定值，无需更改说明：代表模型的英文名称
input	是	[{'factor': 1, 'text': '你好'}, {'factor': 2, 'audio': 'https://data-generator-idst.oss-cn-shanghai.aliyuncs.com/dashscope/image/multi_embedding/audio/cow.flac'}, {'factor': 3, 'image': 'https://data-generator-idst.oss-cn-shanghai.aliyuncs.com/dashscope/image/multi_embedding/image/256_1.png'}]	取值：为多模态输入列表，目前支持三种模态,格式为 {"模态": "输入字符串或图像音频url", "factor": "数值，该部分权重"} 模态对应[text\|image\|audio] image 图像格式目前支持：bmp, jpg, jpeg, png 和 tiff；文件大小不超过5M。 audio 当前支持最大音频时长为15s，超出该时长的音频内容在 auto-truncation 功能打开的情况下会被截断继续计算向量，auto-truncation 功能关闭的时候本次请求会报错返回；语音格式目前支持 wav, mp3 和 flac；文件大小不超过5M。 text 当前支持最大文本长度为70 字，超出该长度的文本内容在 auto-truncation 功能打开的情况下会被截断继续计算向量，auto-truncation 功能关闭的时候本次请求会报错返回；
auto_truncation	否	自动截断	取值：true\|false 是否自动截断输入种过长的文本（70字符），如果为否，则输入过长，结果会报错，否则截断字符串，返回embedding，默认为false，过长输入会报错。默认为false

响应参数

字段	类型	描述	示例值
status_code	Integer	本次结果http相应码，200对应请求成功。
code	String	请求失败，为简短错误码。
message	String	详细错误信息。
output.embedding	Array	本次请求的算法输出内容，是一个由结构组成的数组，每一个数组中包含一个对应的输入内容的算法向量表征输出内容.java sdk统一转换为Double，参考模型输出类型，进行比较的数据类型转换。	"embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ]
usage.[text\|image\|audio]	dict	对应各模态计量信息。	12
usage.weight	Integer	计量权重,计算规则,total_usage=text.measuretext.weight + audio.measureaudio.weight + image.measure*image.weight
usage.total_usage	Integer	对应总的计量信息
request_id	String	本次请求的系统唯一码	7574ee8f-38a3-4b1e-9280-11c33ab46e51

HTTP调用

说明

本模型还可通过HTTP的方式进行调用，以适用更灵活的业务开发，下面是HTTP同步调用接口的接口详情。

作业提交接口调用

POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

参数详解

请求参数

传参方式	字段	类型	必选	描述	示例值
Header	Content-Type	String	是	请求类型：application/json 或者text/event-stream（开启 SSE 响应）	application/json
Header	Authorization	String	是	API-Key，例如：Bearer d1**2a	Bearer d1**2a
Body	model	String	是	指明需要调用的模型，此处使用multimodal-embedding-one-peace-v1	multimodal-embedding-one-peace-v1
	input.contents[list]	Array	是	contents 列表中包含本次需要进行向量计算的所有内容列表，每一个列表可以分别是图像（image），文本（text）或者音频（audio）。	哪个公园距离我更近
	input.contents[x].image	String	至少包含一项，可以包含多项并重复	本次需要进行向量计算中的图像内容的 url 链接；算法内部会将每张图像缩放为256x256分辨率。图像格式目前支持：bmp, jpg, jpeg, png 和 tiff；文件大小不超过5M。	"contents": [ { "image": "http://a/a.jpg", "factor": "5.0" }, { "text": "公园", "factor": "0.5" }, { "audio": "http://b/b.wav"} ]
	input.contents[x].audio	String		本次需要进行向量计算中的音频内容的 url 链接；当前支持最大音频时长为15s，超出该时长的音频内容在 auto-truncation 功能打开的情况下会被截断继续计算向量，auto-truncation 功能关闭的时候本次请求会报错返回；语音格式目前支持 wav, mp3 和 flac；文件大小不超过5M。
	input.contents[x].text	String		本次需要进行向量计算中的文本内容；当前支持最大文本长度为70 字，超出该长度的文本内容在 auto-truncation 功能打开的情况下会被截断继续计算向量，auto-truncation 功能关闭的时候本次请求会报错返回；
	input.contents[x].factor	Float	否	本条多模态信息的权重系数，必须为大于 0 的正浮点数，如果不设置默认为1.0，整体按照加权平均计算
	parameters.auto_truncation	Bool	否	在输入的音频内容超过 15 秒或者文字内容超出 70 字的情况下，是截断输入音频或者文字继续计算向量，还是终止计算报错返回。默认为 false：过长的输入会导致请求报错。	"parameters": { "auto_truncation": true }

响应参数

字段	类型	描述	示例值
output.embedding[]	Array	本次请求的算法输出内容。	[-0.006929283495992422,-0.005336422007530928, ...]
usage.audio.measure	Integer	本次请求输入语音的计量条数。	"usage":{ "audio":{ "measure":1, "weight":2 }, "image":{ "measure":1, "weight":1 }, "text":{ "measure":1, "weight":1 }, "total_usage":4 }
usage.audio.weight	Integer	本次请求输入语音的计量权重。
usage.image.measure	Integer	本次请求输入图像的计量条数。
usage.image.weight	Integer	本次请求输入图像的计量权重。
usage.text.measure	Integer	本次请求输入文本的计量条数。
usage.text.weight	Integer	本次请求输入文本的计量权重。
usage.total_usage	Integer	本次请求语音、图像和文本加权计量后的总计消耗值。
request_id	String	本次请求的系统唯一码	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Curl示例

Shell

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "multimodal-embedding-one-peace-v1",
    "input": {
        "contents": [ 
             {
                 "image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/the_starry_night.jpg", 
                 "factor": "5" 
              },
              {
                 "text": "what is your name",
                  "factor": "0.5"
              },
              {
                 "audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/cow.flac"
              }
        ]
    },
    "parameters": {
    		"auto_truncation": true
    }
}'

响应示例

调用成功示例

{
    "output":{
        "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
    },
    "usage": {
        "audio": {
            "measure":1, #音频条数
            "weight":2   #音频权重
        },
        "image": {
            "measure":1, #图像张数
            "weight":1   #图像权重
        },
        "text": {
            "measure":1, #文本条数
            "weight":1   #文本权重
        },
        "total_usage":4  #加权消耗总数： 音频(1*2) + 图像(1*1) + 文本(1*1) = 4
      }
    }
    "request_id":"d89c06fb-46a1-47b6-acb9-bfb17f814969"
}

调用异常示例

在访问请求出错的情况下，输出的结果中会通过 code 和 message 指明出错原因。

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

状态码说明

DashScope通用状态码请查阅：返回状态码说明