使用文件存储API

背景介绍

DashScope上有许多能力需要用户提供一个文件进行输入。DashScope支持用户传入一个开放可访问的URL指向相应的文件作为输入参数提交API调用。这种方式的好处是简单直接，API调用输入传输数据量小速度快，但这种方式也存在一些局限性，比如：

• 需要用户有相应的公网开放存储空间；

• 用户的存储空间文件访问速度不稳定；

• 用户可能不希望将数据面向公网公开开放；

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

功能概要

为了满足用户的要求，DashScope提供了帮助用户将文件上传到临时存储空间的功能，用户可以更安全地使用文件输入相关的API调用。

用户需要分三步完成具体的功能使用：

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

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

3. 文件上传完成后，用户需要通过凭证信息拼接出对应的OSS文件URL，并使用此URL提交API调用。

文件上传凭证获取接口

功能描述

获取文件上传凭证，为实际的文件上传获取各种配置和凭证信息。

前提条件

已开通服务并获得API-KEY：API-KEY的获取与配置。

提交接口调用

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

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": "xxx",
    "data": {
        "policy": "eyJl...1ZSJ9XX0=",
        "signature": "g5K...d40=",
        "upload_dir": "dashscope-instant/xxx/2024-07-18/xxxx",
        "upload_host": "https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com",
        "expire_in_seconds": 300,
        "max_file_size_mb": 100,
        "capacity_limit_mb": 999999999,
        "oss_access_key_id": "LTAxxx",
        "x_oss_object_acl": "private",
        "x_oss_forbid_overwrite": "true"
    }
}

文件上传接口

功能描述

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

前提条件

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

• 相应的凭证信息在有效期之内。有效期时间请参考文件上传凭证接口输出参数的data.expire_in_seconds。

提交接口调用

POST {data.upload_host}

curl --location 'https://dashscope.oss-cn-beijing.aliyuncs.com' \
--form 'OSSAccessKeyId="LTAm5xxx"' \
--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参数X-DashScope-OssResourceResolve为enable，使得平台从临时存储空间获取文件。

拼接上传文件调用地址

将字符串"oss://"拼接在上传文件使用的key参数之前，就可以得到进行调用时所需的文件URL。例如key是dashscope-instant/aaa/bbb/xyz.jpg，那么实际进行模型调用的时候使用的URL为oss://dashscope-instant/aaa/bbb/xyz.jpg。

调用实例

此处我们使用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"
}