OpenAI 文件接口_模型服务灵积(DashScope)-阿里云帮助中心

为支持熟悉OpenAI的开发者使用OpenAI接口来访问DashScope中与文件相关的API服务，DashScope提供了与OpenAI兼容的接口。用户只需要配置DashScope的API key以及服务base_url，即可通过OpenAI API以及SDK来访问DashScope的文件服务。

前提条件

请开通灵积服务并获得API-KEY：API-KEY的获取与配置。
如果您通过OpenAI Python SDK使用，请通过以下命令安装最新版OpenAI SDK。
```
pip3 install -U openai
```
我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄露风险，配置方法可参考通过环境变量配置API-KEY。

功能描述

上传文件

文件格式支持常见的文本文件(txt docx pdf epub mobi md)，单文件大小限制为150M，最大上传文件数10000，上传总量不超过100G。

OpenAI Python SDK

示例代码

from pathlib import Path
from openai import OpenAI
import os


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# test.txt 是一个示例文件
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())

输入参数配置

输入参数与OpenAI的接口参数对齐，参数说明和可选值如下。

参数

类型

默认值

说明

file

File

待上传的文件对象，Python的File Object类型

purpose

string

上传文件的用途，当前可选值如下：

file-extract: 用于Qwen-Long等模型的文档理解。

batch: 用于batch任务。

返回示例

{
  "id": "file-fe-Yagxxx",
  "bytes": 27,
  "created_at": 1722480376,
  "filename": "test.txt",
  "object": "file",
  "purpose": "file-extract",
  "status": "processed",
  "status_details": null
}

返回参数

字段	类型	描述	示例值
id	string	文件标识符，可在各个API中引用	"file-fe-123"
bytes	integer	文件大小，单位为字节	123456
created_at	integer	文件创建时的 Unix 时间戳（秒）	1617981067
filename	string	文件名	"mydata.jsonl"
object	string	对象类型，始终为 file	"file"

HTTP

需要配置的endpoint

POST https://dashscope.aliyuncs.com/compatible-mode/v1/files

请求示例

curl --location --request POST 'https://dashscope.aliyuncs.com/compatible-mode/v1/files' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --form 'file=@"test.txt"' \
  --form 'purpose="file-extract"'

输入参数配置

字段

类型

传参方式

必选

描述

file

Body

是

待上传的文件

purpose

string

Body

是

上传文件的用途，当前可选值如下：

file-extract: 用于Qwen-Long等模型的文档理解。

batch: 用于batch任务。

返回示例

{
  "id": "file-fe-AiKxgWxPXytoR7tnV2ZFwadq",
  "object": "file",
  "bytes": 27,
  "created_at": 1722480471,
  "filename": "test.txt",
  "purpose": "file-extract",
  "status": "processed"
}

返回参数

字段	类型	描述
id	string	文件标识符，可在各个API中引用。
object	string	对象类型，始终为 file。
bytes	integer	文件大小，单位为字节。
created_at	integer	文件创建时的 Unix 时间戳（秒）。
filename	string	文件名。
purpose	string	上传文件的用途。

在模型调用中使用文件

您可以在模型调用时，在System message中传入文件的id，让大模型读取文件信息。

from pathlib import Path
from openai import OpenAI
import os


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# data.pdf 是一个示例文件
file_object = client.files.create(file=Path("data.pdf"), purpose="file-extract")

completion = client.chat.completions.create(
    model="qwen-long",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "system", "content": f"fileid://{file_object.id}"},
        {"role": "user", "content": "请帮忙概括文件讲述了什么"},
    ],
)

print(completion.model_dump_json())

返回示例

{
  "id": "chatcmpl-8576954d-6de2-9e13-b982-32ebdb0ec731",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "文件 \"test.txt\" 主要内容是：“你好啊，我是云小宝”。这看起来像是一条简单的问候信息，可能来自于一个名为“云小宝”的虚拟助手或者软件程序。",
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1722480551,
  "model": "qwen-long",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 42,
    "prompt_tokens": 20,
    "total_tokens": 62
  }
}

查询文件信息

OpenAI Python SDK

示例代码

from openai import OpenAI
import os


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

file = client.files.retrieve(file_id="file-fe-xxx")

print(file.model_dump_json())

输入参数配置

参数	类型	默认值	必选	说明
file_id	string	-	是	待查询的文件id

返回示例

{
  "id": "file-fe-nXkYPd5DSIbO194EqSmni2LT",
  "bytes": 27,
  "created_at": 1722480306,
  "filename": "test.txt",
  "object": "file",
  "purpose": "file-extract",
  "status": "processed",
  "status_details": null
}

返回参数

字段	类型	描述	示例值
id	string	文件标识符，可在各个API中引用	"file-fe-123"
bytes	integer	文件大小，单位为字节	123456
created_at	integer	文件创建时的 Unix 时间戳（秒）	1617981067
filename	string	文件名	"mydata.jsonl"
object	string	对象类型，始终为 file	"file"

HTTP

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file-id}

请求示例

curl --location --request GET 'https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-fe-ykLgOT1vct3TxMwHjPFpbcEf' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数配置

字段	类型	传参方式	必选	描述
Authorization	String	Header	是	Api-Key
file-id	String	Path	是	需要查询的文件id

返回示例

{
    "id": "file-fe-ykLgOT1vct3TxMwHjPFpbcEf",
    "object": "file",
    "bytes": 499719,
    "created_at": 1715935833,
    "filename": "Less is more.pdf",
    "purpose": "file-extract",
    "status": "processed"
}

返回参数

字段	类型	描述
object	String	固定值为 “file”

查询文件列表

OpenAI Python SDK

示例代码

from openai import OpenAI
import os


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

file_stk = client.files.list()
print(file_stk.model_dump_json())

返回示例

{
  "data": [
    {
      "id": "file-fe-xxx",
      "bytes": 27,
      "created_at": 1722480543,
      "filename": "test.txt",
      "object": "file",
      "purpose": "file-extract",
      "status": "processed",
      "status_details": null
    },
    {
      "id": "file-fe-yyy",
      "bytes": 431986,
      "created_at": 1718089390,
      "filename": "test.pdf",
      "object": "file",
      "purpose": "file-extract",
      "status": "processed",
      "status_details": null
    }
  ],
  "object": "list",
  "has_more": false
}

返回参数

字段	类型	描述
object	String	固定值为 “list”
data	list	FileObject的列表

HTTP

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/files

请求示例

curl --location --request GET 'https://dashscope.aliyuncs.com/compatible-mode/v1/files' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY"

返回示例

{
    "object": "list",
    "has_more": true,
    "data": [
        {
            "id": "ad543fdc-9de1-4976-bff8-0132694aba18",
            "object": "file",
            "bytes": 84889,
            "created_at": 1715569225,
            "filename": "example.txt",
            "purpose": "file-extract",
            "status": "processed"
        },
        {
            "id": "file-fe-SgxzqQzp42tOEnagCxrXdZjO",
            "object": "file",
            "bytes": 722355,
            "created_at": 1715413868,
            "filename": "Agent_survey.pdf",
            "purpose": "file-extract",
            "status": "processed"
        }
    ]
}

返回参数

字段	类型	描述
object	String	固定值为 “list”
has_more	Bool	是否还有下一页数据
data	List	查询的数据列表

下载文件

下载文件支持的purpose（非以下purpose的文件不支持下载）

purpose	描述
batch_output	batch任务生成的结果文件

OpenAI Python SDK

示例代码

from openai import OpenAI
import os


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
content = client.files.content("file-abc123")

输入参数配置

参数	类型	默认值	必选	说明
file_id	string	-	是	待下载的文件id

文件内容

HTTP

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file-id}/content

请求示例

curl --location --request GET 'https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-abc23/content' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" > file.jsonl

输入参数

字段	类型	传参方式	必选	描述
Authorization	String	Header	是	Apikey
file-id	String	Path	是	需要下载的文件的id

文件内容

删除文件

OpenAI Python SDK

示例代码

from openai import OpenAI
import os


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

file_object = client.files.delete("file-fe-AJ62IvDWUa9vELKmxUctIzvX")
print(file_object.model_dump_json())

输入参数配置

参数	类型	默认值	必选	说明
file_id	string	-	是	待删除文件id

返回示例

{
  "object": "file",
  "deleted": true,
  "id": "file-fe-oLIon7bzfxELqJBTS5okwC4E"
}

返回参数

字段	类型	描述
object	String	固定值为 “file”
deleted	Bool	是否删除成功
id	String	成功删除的文件的ID

HTTP

需要配置的endpoint

DELETE https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file-id}

请求示例

curl --location --request DELETE 'https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-fe-oLIon7bzfxELqJBTS5okwC4E' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数

字段	类型	传参方式	必选	描述
Authorization	String	Header	是	API Key
file-id	String	Path	是	需要删除的文件的ID

返回示例

{
  "object": "file",
  "deleted": true,
  "id": "file-fe-oLIon7bzfxELqJBTS5okwC4E"
}

返回参数

字段	类型	描述
object	String	固定值为 “file”
deleted	Bool	是否删除成功
id	String	成功删除的文件的id