使用平台提供的临时存储空间

背景介绍

平台上有不少能力是需要客户提供一个文件进行输入的，通常情况下，我们支持客户传入一个开放可访问的URL指向相应的文件作为输入参数提交API调用；这种方式的好处是简单直接，API调用输入传输数据量小速度快，但是由于一些限制条件的存在，导致这个方式也存在一些局限性，比如：

• 需要客户自己有相应的公网开放存储空间，对于某些条件受限客户不方便；

• 客户自己的存储空间文件访问速度不稳定，如果客户提供的URL因为地域和服务器流量等原因导致文件下载速度比较慢的话会影响整体请求的时效性，甚至在比较极端的情况下可能导致调用失败；

• 出于安全原因，客户可能不希望将调用数据面向公网公开开放；

• 选择阿里云的OSS服务可以保证访问的时效性和稳定性，但是可能为客户带来潜在的额外消费；

功能概要

为了更好地满足客户的要求，平台特意提供了一个临时存储空间的功能，让客户可以更安全地使用文件输入相关的API调用。

出于安全性的考虑，用户需要分两步完成具体的功能使用：

1. 首先客户调用文件上传凭证获取接口，接口会返回一次性的且在一定时间内有效的文件上传凭证信息；

2. 然后客户使用获取到的凭证信息调用阿里云OSS的文件上传接口完成文件上传工作；

3. 文件上传完成后，用户通过凭证信息中的文件地址和上传的文件名拼接出对应的OSS文件URL，最终使用此URL提交API调用。

文件上传凭证获取接口

功能描述

调用接口获取文件上传凭证，为实际的文件上传获取各种配置和凭证信息；

前提条件

已开通服务并获得API-KEY：开通DashScope并创建API-KEY。

提交接口调用

GET https://dashscope.aliyuncs.com/api/v1/uploads

请求示例

以下示例展示如何通过CURL命令来访问上传文件凭证获取接口：

curl --location 'https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen-vl-plus' \
--header 'Authorization: Bearer <your-dashscope-api-key>' \
--header 'Content-Type: application/json'

响应示例

{
    "request_id": "c0087628-5c77-90de-bf38-61ecc3a032bc",
    "data": {
        "policy": "eyJleHBpcmF0aW9 ... ... ... dHJ1ZSJ9XX0=",
        "signature": "Sm/tv7DcZuTZftFVvt5yOoSETsc=",
        "upload_dir": "dashscope-instant/123/456",
        "upload_host": "https://dashscope.oss-cn-beijing.aliyuncs.com",
        "expire_in_seconds": 300,
        "max_file_size_mb": 100,
        "capacity_limit_mb": 999999999,
        "oss_access_key_id": "LTAm5tHvsJAXf7ndvSyYzuYX",
        "x_oss_object_acl": "private",
        "x_oss_forbid_overwrite": "true"
    }
}

文件上传接口

功能描述

在使用文件上传凭证获取接口获取到对应的凭证之后，正式上传文件的接口。

前提条件

• 必须使用文件上传凭证接口提前获取对应的凭证；

• 相应的凭证信息在有效期之内；

提交接口调用

POST 文件上传凭证获取接口返回值中 {upload_host} 取值。

请求示例

curl --location 'https://dashscope.oss-cn-beijing.aliyuncs.com' \
--form 'OSSAccessKeyId="LTAm5tHvsJAXf7ndvSyYzuYX"' \
--form 'Signature="Sm/tv7DcZuTZftFVvt5yOoSETsc="' \
--form 'policy="eyJleHBpcmF0aW9 ... ... ... dHJ1ZSJ9XX0="' \
--form 'x-oss-object-acl="private"' \
--form 'x-oss-forbid-overwrite="true"' \
--form 'key="dashscope-instant/123/456/a.jpg"' \
--form 'success_action_status="200"' \
--form 'file=@"/tmp/a.jpg"'

使用已上传文件调用模型方式

功能描述

用户通过前面两个接口的调用完成文件的上传之后，就可以在接下来的模型调用中使用了；不过值得注意的是，已经上传到临时暂存空间的文件的有效期是上传完成之后的48小时，超过这个时间之后，相应的文件就会被清除，同时对应的链接也将失效；如果用户希望以同样的文件再次调用模型，需要重新进行文件上传凭证获取和文件上传的操作。

前提条件

• 上传的文件仍然在有效期内；

• 调用模型接口的用户和获取上传文件凭证接口调用的用户必须保持一致；不能使用其他用户上传的文件；

• 调用模型的时候需要添加header告知平台此次调用的URL在平台的临时存储空间上：X-DashScope-OssResourceResolve: enable，则实际需要文件的时候，平台就会知道从临时存储空间获取；

拼接上传文件调用地址

1. 调用获取文件上传凭证接口会返回一个参数 upload_dir；

2. 在实际文件上传的时候，我们会使用这个参数拼接需要上传的文件名生成参数key进行文件上传工作，key = upload_dir + '/' + <upload_filename>；比如upload_dir为dashscope-instant/aaa/bbb，需要上传的文件名为xyz.jpg，那么拼出来的key应该是dashscope-instant/aaa/bbb/xyz.jpg；

3. 然后将字符串"oss://"拼接在上传文件使用的key参数之前，我们就得到了真正进行调用的时候的文件URL；比如key是dashscope-instant/aaa/bbb/xyz.jpg，那么实际进行模型调用的时候使用的URL为oss://dashscope-instant/aaa/bbb/xyz.jpg。

最终，在完成了文件上传之后，就可以使用上面步骤拼接出临时存储空间的URL进行文件调用了。

调用实例

此处我们使用qwen-vl-plus模型举例，演示实际的调用过程。

需要通过模型处理的文件命名为hand.jpg，存储在本地的/tmp目录下。

接下来调用文件上传凭证获取接口获取到相关的凭证信息，然后通过文件上传接口完成文件的最终上传工作。根据相关信息，最终拼接得到临时存储空间的URL为：oss://dashscope-instant/0887/2024-04-15/8bd2/hand.jpg

使用该链接进行模型调用，调用请求示例如下：

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--header 'X-DashScope-OssResourceResolve: enable' \
--data '{
  "model": "qwen-vl-plus",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "image": "oss://dashscope-instant/0887/2024-04-15/8bd2/hand.jpg"
          },
          {
            "text": "请告诉我图片中手势所代表的数字"
          }
        ]
      }
    ]
  }
}'

在调用发出后，平台会根据客户设置的参数，使用对应的链接从平台临时存储空间中获取到对应的文件并完成最终的调用，调用成功后我们会收到如下返回结果：

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "text": "图中所示的手势是“2”。这个手势通常用来表示数字2，其中食指和中指伸直，而其他手指则弯曲。这是国际上广泛接受的一种手语或符号来表达数字2。"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "output_tokens": 48,
        "input_tokens": 1266,
        "image_tokens": 1230
    },
    "request_id": "d3d1871f-f0aa-xx87-af60-8aeeac322799"
}