通义千问VL API详情

系统

SDK

传入的文件路径

示例

Linux或macOS系统

Python SDK

file://{文件的绝对路径}

file:///home/images/test.png

Java SDK

Windows系统

Python SDK

file://{文件的绝对路径}

file://D:/images/test.png

Java SDK

file:///{文件的绝对路径}

file:///D:images/test.png

参数

类型

默认值

说明

model

string

-

用户使用的模型名称。

messages

array

-

用户与模型的对话历史。array中的每个元素形式为{"role":角色, "content": 内容}。角色当前可选值：system、user、assistant，其中，仅messages[0]中支持role为system，一般情况下，user和assistant需要交替出现，且messages中最后一个元素的role必须为user。

top_p（可选）

float

-

生成过程中的核采样方法概率阈值，例如，取值为0.8时，仅保留概率加起来大于等于0.8的最可能token的最小集合作为候选集。取值范围为（0,1.0]，取值越大，生成的随机性越高；取值越小，生成的确定性越高。

max_tokens（可选）

integer

-

指定模型可生成的最大token个数。

temperature（可选）

float

-

用于控制模型回复的随机性和多样性。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。

取值范围： [0, 2)，不建议取值为0，无意义。

presence_penalty

（可选）

float

-

用户控制模型生成时整个序列中的重复度。提高presence_penalty时可以降低模型生成的重复度，取值范围[-2.0, 2.0]。

seed（可选）

integer

-

生成时使用的随机数种子，用于控制模型生成内容的随机性。seed支持无符号64位整数。

stream（可选）

boolean

False

用于控制是否使用流式输出。当以stream模式输出结果时，接口返回结果为generator，需要通过迭代获取结果，每次输出为当前生成的增量序列。

stop（可选）

string or array

None

stop参数用于实现内容生成过程的精确控制，在模型生成的内容即将包含指定的字符串或token_id时自动停止。stop可以为string类型或array类型。

• string类型

  当模型将要生成指定的stop词语时停止。

  例如将stop指定为"你好"，则模型将要生成“你好”时停止。

• array类型

  array中的元素可以为token_id或者字符串，或者元素为token_id的array。当模型将要生成的token或其对应的token_id在stop中时，模型生成将会停止。以下为stop为array时的示例（tokenizer对应模型为qwen-turbo）：

  1.元素为token_id：

  token_id为108386和104307分别对应token为“你好”和“天气”，设定stop为[108386,104307]，则模型将要生成“你好”或者“天气”时停止。

  2.元素为字符串：

  设定stop为["你好","天气"]，则模型将要生成“你好”或者“天气”时停止。

  3.元素为array：

  token_id为108386和103924分别对应token为“你好”和“啊”，token_id为35946和101243分别对应token为“我”和“很好”。设定stop为[[108386, 103924],[35946, 101243]]，则模型将要生成“你好啊”或者“我很好”时停止。

  说明

  stop为array类型时，不可以将token_id和字符串同时作为元素输入，比如不可以指定stop为["你好",104307]。qwen-vl相关模型目前不支持该参数。

stream_options（可选）

object

None

该参数用于配置在流式输出时是否展示使用的token数目。只有当stream为True的时候该参数才会激活生效。若您需要统计流式输出模式下的token数目，可将该参数配置为stream_options={"include_usage":True}。

返回参数

数据类型

说明

备注

id

string

系统生成的标识本次调用的id。

无

model

string

本次调用的模型名。

无

system_fingerprint

string

模型运行时使用的配置版本，当前暂时不支持，返回为空字符串“”。

无

choices

array

模型生成内容的详情。

无

choices[i].finish_reason

string

有三种情况：

• 正在生成时为null；

• 因触发输入参数中的stop条件而结束为stop；

• 因生成长度过长而结束为length。

choices[i].message

object

模型输出的消息。

choices[i].message.role

string

模型的角色，固定为assistant。

choices[i].message.content

string

模型生成的文本。

choices[i].index

integer

生成的结果序列编号，默认为0。

created

integer

当前生成结果的时间戳（s）。

无

usage

object

计量信息，表示本次请求所消耗的token数据。

无

usage.prompt_tokens

integer

用户输入文本转换成token后的长度。

您可以参考本地tokenizer统计token数据进行token的估计。

usage.completion_tokens

integer

模型生成回复转换为token后的长度。

无

usage.total_tokens

integer

usage.prompt_tokens与usage.completion_tokens的总和。

无

参数

类型

默认值

说明

model

string

-

指定用于对话的通义千问模型名，如：qwen-vl-plus。

messages

array

-

用户输入的历史对话信息和指令组成的完整输入信息。

参考示例，目前对于图片，支持图片url和本地路径

本地路径格式。

top_p (可选)

float

0.1

生成过程中核采样方法概率阈值，例如，取值为0.1时，仅保留概率加起来大于等于0.1的最可能token的最小集合作为候选集。取值范围为(0,1.0]，取值越大，生成的随机性越高；取值越低，生成的确定性越高。

max_tokens（可选）

integer

-

指定模型可生成的最大token个数。

temperature（可选）

float

-

用于控制模型回复的随机性和多样性。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。

取值范围： [0, 2)，不建议取值为0，无意义。

stream（可选）

boolean

False

是否使用流式输出。当以stream模式输出结果时，接口返回结果为generator，需要通过迭代获取结果，每个输出为当前生成的整个序列，最后一次输出为最终全部生成结果。

stop（可选）

string or array

None

stop参数用于实现内容生成过程的精确控制，在模型生成的内容即将包含指定的字符串或token_id时自动停止。stop可以为string类型或array类型。

• string类型

  当模型将要生成指定的stop词语时停止。

  例如将stop指定为"你好"，则模型将要生成“你好”时停止。

• array类型

  array中的元素可以为token_id或者字符串，或者元素为token_id的array。当模型将要生成的token或其对应的token_id在stop中时，模型生成将会停止。以下为stop为array时的示例（tokenizer对应模型为qwen-turbo）：

  1.元素为token_id：

  token_id为108386和104307分别对应token为“你好”和“天气”，设定stop为[108386,104307]，则模型将要生成“你好”或者“天气”时停止。

  2.元素为字符串：

  设定stop为["你好","天气"]，则模型将要生成“你好”或者“天气”时停止。

  3.元素为array：

  token_id为108386和103924分别对应token为“你好”和“啊”，token_id为35946和101243分别对应token为“我”和“很好”。设定stop为[[108386, 103924],[35946, 101243]]，则模型将要生成“你好啊”或者“我很好”时停止。

  说明

  stop为array类型时，不可以将token_id和字符串同时作为元素输入，比如不可以指定stop为["你好",104307]。

top_k（可选）

integer

100

生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。注意：如果top_k的值大于100，top_k将采用默认值100。

seed（可选）

integer

1234

生成时，随机数的种子，用于控制模型生成的随机性。如果使用相同的种子，每次运行生成的结果都将相同；当需要复现模型的生成结果时，可以使用相同的种子。seed参数支持无符号64位整数类型。默认值 1234

incremental_output

boolean

False

是否使用增量输出。当使用增量输出时每次流式返回的序列仅包含最新生成的增量内容，默认输出完整的全量内容。

返回参数

类型

说明

示例

status_code

integer

200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。

request_id

string

系统生成的标志本次调用的id。

code

string

表示请求失败，表示错误码，成功忽略。

output

object

调用结果信息，对于通义VL模型，包含输出message。

output.choices

array

模型为输入生成的完成选项列表。

"choices": [

{

"finish_reason": null,

"message": {

"role": "assistant",

"content": [

{

"text": "这是一个"

}

]

}

}

]

output.choices[x].message.role

string

信息来源。

output.choices[x].message.content

array

本次请求的算法输出内容,输出可能包含多种模态内容，因此，是一个list，元素为dict，key为内容类型，value为内容值。

usage

object

计量信息，表示本次请求计量数据。

usage.input_tokens

integer

用户输入转换成Token后的长度。

usage.output_tokens

integer

模型生成回复转换为Token后的长度。

usage.image_tokens

integer

当使用图像理解时，用户输入图像转换成Token后的长度。

usage.video_tokens

integer

当使用视频理解时，用户输入视频转换成Token后的长度。

传参方式

字段

数据类型

必选

描述

示例值

Header

Content-Type

string

是

请求类型：application/json或者text/event-stream（开启 SSE 响应）

application/json

Authorization

string

是

API-KEY

Bearer d1**2a

X-DashScope-WorkSpace

string

否

指明本次调用需要使用的workspace；需要注意的是，对于子账号Apikey调用，此参数为必选项，子账号必须归属于某个workspace才能调用；对于主账号Apikey此项为可选项，添加则使用对应的workspace身份，不添加则使用主账号身份。

ws_QTggmeAxxxxx

X-DashScope-SSE

string

否

跟Accept: text/event-stream 二选一即可启用SSE响应。

enable

Body

model

string

是

指明需要调用的模型。

qwen-vl-plus

input.messages[list]

array

是

多模态场景下的输入信息。

"messages":[

{

"role": "user",

"content": [

{"image": "http://XXXX"},

{"text": "这个图片是哪里？"}

]

}]

input.messages[x].role

string

是

信息来源。

input.messages[x].content[list]

array

是

contents列表中包含本次输入的内容列表，每一个列表可以分别是图像（image）或者文本（text）。

input.messages[x].content[list].image

string

至少包含一项

本次输入的图像内容的URL链接。图像格式：bmp、jpg、jpeg、png和tiff。

input.message[x].content[list].text

string

本次输入的文本内容。支持utf-8编码的中文、英文输入。

parameters.top_p

float

否

生成时，核采样方法的概率阈值。

取值范围为（0,1.0），取值越大，生成的随机性越高；取值越小，生成的随机性越低。默认值 0.8。

例如，取值为0.8时，仅保留累计概率之和大于等于0.8的概率分布中的token，作为随机采样的候选集。

0.8

parameters.max_tokens

integer

否

指定模型可生成的最大token个数。

1000

parameters.temperature

float

否

用于控制模型回复的随机性和多样性。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。

取值范围： [0, 2)，不建议取值为0，无意义。

0.8

parameters.top_k

integer

否

生成时，采样候选集的大小。取值越大，生成的随机性越高；取值越小，生成的确定性越高。如果top_k的值大于100，top_k将采用默认值100

例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。

50

parameters.seed

integer

否

生成时，随机数的种子，用于控制模型生成的随机性。如果使用相同的种子，每次运行生成的结果都将相同；当需要复现模型的生成结果时，可以使用相同的种子。默认值为1234。

seed参数支持无符号64位整数类型。

65535

parameters.stop

string or array

否

stop参数用于实现内容生成过程的精确控制，在模型生成的内容即将包含指定的字符串或token_id时自动停止。stop可以为string类型或array类型。

• string类型

  当模型将要生成指定的stop词语时停止。

  例如将stop指定为"你好"，则模型将要生成“你好”时停止。

• array类型

  array中的元素可以为token_id或者字符串，或者元素为token_id的array。当模型将要生成的token或其对应的token_id在stop中时，模型生成将会停止。以下为stop为array时的示例（tokenizer对应模型为qwen-turbo）：

  1.元素为token_id：

  token_id为108386和104307分别对应token为“你好”和“天气”，设定stop为[108386,104307]，则模型将要生成“你好”或者“天气”时停止。

  2.元素为字符串：

  设定stop为["你好","天气"]，则模型将要生成“你好”或者“天气”时停止。

  3.元素为array：

  token_id为108386和103924分别对应token为“你好”和“啊”，token_id为35946和101243分别对应token为“我”和“很好”。设定stop为[[108386, 103924],[35946, 101243]]，则模型将要生成“你好啊”或者“我很好”时停止。

  说明

  stop为array类型时，不可以将token_id和字符串同时作为元素输入，比如不可以指定stop为["你好",104307]。

["天气"]

parameters.incremental_output

boolean

否

是否使用增量输出。当使用增量输出时每次流式返回的序列仅包含最新生成的增量内容，默认值为false，即输出完整的全量内容。

无

字段

类型

描述

示例值

output.choices[list]

array

模型为输入生成的完成选项列表。

"choices": [

{

"finish_reason": null,

"message": {

"role": "assistant",

"content": [

{

"text": "这是一个"

}

]

}

}

]

output.choices[x].message.role

string

信息来源。

output.choices[x].message.content

array

本次请求的算法输出内容，为list，内容为多个dict，key为内容类型，value为内容值

output.finish_reason

string

有三种情况：正在生成时为null，生成结束时如果由于停止token导致则为stop，生成结束时如果因为生成长度过长导致则为length。

stop

usage.output_tokens

integer

输出内容的 token 数目。

380

usage.input_tokens

integer

用户输入内容的 token 数目。

633

usage.image_tokens

integer

当使用图像理解时，用户输入图像转换成Token后的长度。

usage.video_tokens

integer

当使用视频理解时，用户输入视频转换成Token后的长度。

request_id

string

本次请求的系统唯一码

7574ee8f-38a3-4b1e-9280-11c33ab46e51