AI 助理
备案控制台
文档
输入文档关键字查找
首页大模型服务平台百炼开发参考更多通过临时存储空间实现模型调用中的文件传输

通过临时存储空间实现模型调用中的文件传输

更新时间：2025-02-14 09:55:51
产品详情
我的收藏

在调用百炼的多模态模型时，通常需要传入图像、音频等文件的公网URL。为了降低文件URL的获取难度，百炼提供了临时存储空间。您只需将本地文件上传至该临时存储空间，即可获得对应文件的URL，并在模型调用时传入该URL完成后续操作。

为什么使用临时存储空间

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

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

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

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

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

为了解决上述问题，百炼提供了将文件上传到临时存储空间的功能，优化了内部访问链路，使用户能够更便捷且安全地获取文件URL并在相关API中调用文件。

临时存储空间的优点

  • 用户不用再自行准备公网访问空间，也不需要为此产生潜在的额外费用。

  • 安全可控，相关文件不再有公网暴露风险；除了对应的目标调用算法，文件无法从外部访问。

  • 对模型进行调用的时候，平台算法实例可以通过内部通路访问对应模型，相比外部链接文件获取速度更快并且时延稳定。

  • 用户可以相对独立且并行地处理文件传输和模型调用，更有利于用户协调自己的网络利用和业务逻辑。

临时存储空间的限制条件

出于安全合规的要求和用户信息的保护目的，对应功能有如下限制条件：

  • 在文件上传凭证获取接口中需要指明具体调用的模型名称，不同的模型能力会有不同的文件大小限制。

  • 上传的文件是用户隔离的，用户A上传的文件仅可以被用户A在获取凭证接口中指明的模型调用使用，不能被其他用户或者其他模型调用所使用。

  • 文件上传之后的有效期是48小时，用户需要在48小时之内完成API调用，到期后文件会被清理失效。

  • 文件一旦上传，则不能再以任何方式查询、修改和下载，平台外部也没有任何途径可以访问；仅在最终用户发起模型调用时经过安全校验后被算法内部获取以完成算法逻辑。

  • 文件上传凭证获取接口的调用限流是用户在特定模型调用限流的10倍，超出对应限流的访问会因为限流失败。

如何获取文件URL

步骤1：调用文件上传凭证获取接口，获取文件上传凭证

功能描述

该接口用于获取文件上传凭证，为文件上传获取各种配置和凭证信息。

前提条件

您需要已获取API Key并配置API Key到环境变量。

提交接口调用

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

入参描述

传参方式

字段

类型

必选

描述

示例值

传参方式

字段

类型

必选

描述

示例值

Header

Content-Type

string

是

请求类型：application/json 。

application/json

Authorization

string

是

API-Key，例如：Bearer d1**2a。

Bearer d1**2a

Query

action

string

是

操作类型，当前场景为getPolicy。

getPolicy

model

string

是

指明数据准备完成后最终需要调用的模型名称。

qwen-vl-plus

出参描述

字段

类型

描述

示例值

字段

类型

描述

示例值

request_id

string

本次请求的系统唯一码。

7574ee8f-...-11c33ab46e51

data

object

-

-

data.policy

string

上传凭证。

eyJl...1ZSJ9XX0=

data.signature

string

上传凭证的签名。

g5K...d40=

data.upload_dir

string

上传文件的目录。

dashscope-instant/xxx/2024-07-18/xxxx

data.upload_host

string

上传的host地址。

https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com

data.expire_in_seconds

string

凭证有效期（单位：秒）。

超出有效期后，您需要重新调用本接口获取新的凭证。

300

data.max_file_size_mb

string

本次允许上传的最大文件的大小（单位：MB）。这个值与用户需要访问的模型相关。

100

data.capacity_limit_mb

string

同一个用户每天的上传容量限制（单位：MB）。

999999999

data.oss_access_key_id

string

用于上传的access key。

LTAxxx

data.x_oss_object_acl

string

上传文件的访问权限，private表示私有。

private

data.x_oss_forbid_overwrite

string

文件同名时是否可以覆盖，true表示不可覆盖。

true

请求示例

说明

若没有将百炼API Key配置到环境变量，请使用已经获取的API Key替换$DASHSCOPE_API_KEY，代码才能正常运行。

curl
curl --location 'https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen-vl-plus' \
--header "Authorization: Bearer $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"
    }
}

步骤2：在文件上传接口中，使用凭证信息将文件上传至临时存储空间

功能描述

使用文件上传凭证获取接口获取到对应的凭证信息之后，使用该接口上传文件。

前提条件

  • 已经使用文件上传凭证获取接口获取到文件上传凭证。

  • 文件上传凭证在有效期之内（文件上传凭证获取接口的输出参数data.expire_in_seconds为凭证有效期）。超出有效期后，您需要重新调用文件上传凭证获取接口获取新的凭证。

提交接口调用

POST {data.upload_host}
说明

请将{data.upload_host}替换为文件上传凭证获取接口输出参数的data.upload_host对应的值。

入参描述

传参方式

字段

类型

必选

描述

示例值

传参方式

字段

类型

必选

描述

示例值

Header

Content-Type

String

否

POST操作提交表单编码必须为multipart/form-data，即Header中Content-Type为multipart/form-data;boundary=xxxxxx的形式；boundary为边界字符串，是由表单随机生成的一个随机值，无需指定。如果通过SDK拼接表单，则SDK也会生成一个随机值。

multipart/form-data; boundary=9431149156168

form-data

OSSAccessKeyId

Text

是

文件上传凭证获取接口输出参数中 oss_access_key_id 的值。

LTAm5xxx

policy

Text

是

文件上传凭证获取接口输出参数中 policy 的值。

g5K...d40=

Signature

Text

是

文件上传凭证获取接口输出参数中 signature 的值。

Sm/tv7DcZuTZftFVvt5yOoSETsc=

key

Text

是

文件上传凭证获取接口输出参数中 upload_dir 的值拼接上/需要上传文件的文件名。

例如，upload_dir=dashscope-instant/xxx/2024-07-18/xxxx，需要上传的文件名为cat.png，拼接后的值为：

dashscope-instant/xxx/2024-07-18/xxxx/cat.png

x-oss-object-acl

Text

是

文件上传凭证获取接口输出参数中 x_oss_object_acl 的值。

private

x-oss-forbid-overwrite

Text

是

文件上传凭证获取接口输出参数中 x_oss_forbid_overwrite 的值。

true

success_action_status

Text

否

通常取值200，表示在文件上传结束后令接口返回HTTP code 200指示成功。

200

file

File

是

文件或文本内容。

重要

  • 一次只支持上传一个文件。

  • file必须为最后一个表单域，除file以外的其他表单域并无顺序要求。

假设待上传文件cat.png在Linux系统中的存储路径为/tmp。则此处应为file=@"/tmp/cat.png"。

出参描述

调用成功时，本接口无任何参数输出。

请求示例

curl
curl --location 'https://dashscope-file-xxx.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/cat.png"'

步骤3：获取文件URL，并使用此URL进行模型调用

前提条件

  • 上传至临时存储空间的文件仍在有效期内。

    已经上传到临时存储空间的文件的有效期是上传完成之后的48小时，超过这个时间之后，相应的文件就会被清除，同时对应的链接也将失效；如果您希望以同样的文件再次调用模型，需要重新获取文件上传凭证和重新上传文件。

  • 模型调用API的用户和上传文件的用户必须保持一致，不能使用其他用户上传的文件。

获取文件URL

将字符串oss://拼接在上传文件使用的key参数之前，就可以得到模型调用时所需的文件URL。例如key是dashscope-instant/xxx/2024-07-18/xxxx/cat.png，则实际进行模型调用的时候使用的文件URL为oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png。

模型调用示例

重要

在进行模型调用时，如果使用临时存储空间中的文件，则必须在请求的header中添加参数X-DashScope-OssResourceResolve: enable。只有在满足此条件的情况下，才能从临时存储空间中获取相应的文件以完成调用。

此处以qwen-vl-plus模型为例演示实际的调用过程。 示例图片cat.png。

image

请求示例

curl
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-OssResourceResolve: enable' \
-d '{
  "model": "qwen-vl-plus",
  "messages": [{
      "role": "user",
      "content": 
      [{"type": "text","text": "这是什么"},
       {"type": "image_url","image_url": {"url": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"}}]
    }]
}'

响应示例

{
  "choices": [
    {
      "message": {
        "content": "这是一张描绘一只白色猫咪在草地上奔跑的图片。这只猫有蓝色的眼睛，看起来非常可爱和活泼。背景是模糊化的自然景色，强调了主体——那只向前冲跑的小猫。这种摄影技巧称为浅景深（或大光圈效果），它使得前景中的小猫变得清晰而锐利，同时使背景虚化以突出主题并营造出一种梦幻般的效果。整体上这张照片给人一种轻松愉快的感觉，并且很好地捕捉到了动物的行为瞬间。",
        "role": "assistant"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 1253,
    "completion_tokens": 104,
    "total_tokens": 1357
  },
  "created": 1739349052,
  "system_fingerprint": null,
  "model": "qwen-vl-plus",
  "id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"
}

常见问题

调用文件上传接口时提示“Invalid according to Policy: Policy expired.”应该如何处理？

该报错表明文件上传凭证已超出有效期（文件上传凭证获取接口的输出参数data.expire_in_seconds为凭证有效期）。您需要重新调用文件上传凭证获取接口获取新的凭证。

上一篇：知识库SearchFilters下一篇：DashScope Java SDK 连接池配置
  • 本页导读 （1）
  • 为什么使用临时存储空间
  • 如何获取文件URL
  • 步骤1：调用文件上传凭证获取接口，获取文件上传凭证
  • 步骤2：在文件上传接口中，使用凭证信息将文件上传至临时存储空间
  • 步骤3：获取文件URL，并使用此URL进行模型调用
  • 常见问题