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

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

SDK使用

前提条件

已开通服务并获得API-KEY：开通DashScope并创建API-KEY。
安装OpenAI SDK，注意OpenAI SDK版本需大于1.0.0

重要

安装方式：pip install --upgrade 'openai>=1.0'

检查版本：python -c 'import openai; print("version =",openai.__version__)'

注：当前仅支持上传接口，其他接口待后续逐步开放。

上传文件

文件格式支持常见的文本文件(txt docx pdf epub mobi md)，单文件大小限制为150M，最大上传文件数10000，上传总量不超过100G。以下示例展示了通过OpenAI接口访问DashScope的文件上传。

from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="$your-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")

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

参数

类型

默认值

说明

file

File

待上传的文件对象，python的File object类型

purpose

string

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

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

返回值类型为File，详细参考File object，示例如下

{
    "id": "file-fe-9TIRfHksHmf5gLKZwi06o7Np",
    "object": "file",
    "bytes": 5,
    "created_at": 1715256442973,
    "filename": "test.txt",
    "purpose": "file-extract"
}

查询文件元信息

from openai import OpenAI

client = OpenAI(
    api_key="$your-dashscope-api-key",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

client.files.retrieve("file-fe-9TIRfHksHmf5gLKZwi06o7Np")

输入参数说明如下

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

返回值类型为File，详细参考File object，示例如下

{
    "id": "file-fe-9TIRfHksHmf5gLKZwi06o7Np",
    "object": "file",
    "bytes": 5,
    "created_at": 1715256442973,
    "filename": "test.txt",
    "purpose": "file-extract"
}

查询文件列表

from openai import OpenAI

client = OpenAI(
    api_key="$your-dashscope-api-key",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

client.files.list()

返回字段

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

返回示例如下

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

删除文件

from openai import OpenAI

client = OpenAI(
    api_key="$your-dashscope-api-key",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

client.files.delete("file-fe-9TIRfHksHmf5gLKZwi06o7Np")

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

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

返回字段

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

返回示例

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

File object

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

HTTP调用接口

功能描述

灵积也同时提供了 HTTP 接口，客户可以根据自己的需求选择。

前提条件

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

上传文件

POST https://dashscope.aliyuncs.com/compatible-mode/v1/files
Content-type: multipart/form-data

请求参数

字段

类型

传参方式

必选

描述

file

Body

是

待上传的文件

purpose

string

Body

是

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

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

请求示例

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

返回数据

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

返回示例

{
    "id": "file-fe-9TIRfHksHmf5gLKZwi06o7Np",
    "object": "file",
    "bytes": 5,
    "created_at": 1715256442973,
    "filename": "test.txt",
    "purpose": "file-extract"
}

查询文件信息

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

请求参数

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

请求示例

curl --location --request GET 'http://dashscope.aliyuncs.com/compatible-mode/v1/files/file-fe-ykLgOT1vct3TxMwHjPFpbcEf' \
  --header 'Authorization: Bearer <your-dashscope-api-key>'

返回数据

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

返回示例

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

查询文件列表

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

请求参数

字段	类型	传参方式	必选	描述
Authorization	String	Header	是	Apikey

请求示例

curl --location --request GET 'http://dashscope.aliyuncs.com/compatible-mode/v1/files' \
  --header 'Authorization: Bearer <your-dashscope-api-key>'

返回数据

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

返回示例

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

删除文件

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

请求参数

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

请求示例

curl --location --request DELETE 'http://dashscope.aliyuncs.com/compatible-mode/v1/files/file-fe-oLIon7bzfxELqJBTS5okwC4E' \
  --header 'Authorization: Bearer <your-dashscope-api-key>'

返回数据

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

返回示例

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