文档

OpenAI文件接口兼容

更新时间:

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

SDK使用

前提条件

重要

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

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

上传文件

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

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

在模型调用中使用文件

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

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

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())

查询文件元信息

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 接口,客户可以根据自己的需求选择。

前提条件

上传文件

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

请求参数

字段

类型

传参方式

必选

描述

file

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": "example.txt",
            "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"
}