背景介紹

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"
}