AI 助理
备案控制台
文档
产品文档
输入文档关键字查找
首页 模型服务灵积 开发参考 OpenAI接口兼容 File

OpenAI文件接口兼容

更新时间：
一键部署
产品详情
我的收藏

为支持熟悉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等模型的文档理解。

返回示例

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

file

Body

是

待上传的文件

purpose

string

Body

是

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

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

返回示例

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

查询的数据列表

删除文件

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

是

Apikey

file-id

String

Path

是

需要删除的文件的id

返回示例

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

返回参数

字段

类型

描述

object

String

固定值为 “file”

deleted

Bool

是否删除成功

id

String

成功删除的文件的id

上一篇：Chat下一篇：模型列表
文档推荐