通过API调用通义千问代码模型

参数

类型

默认值

说明

model

string

-

用户使用model参数指明对应的模型。

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]，取值越大，生成的随机性越高；取值越低，生成的确定性越高。

temperature（可选）

float

-

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

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

presence_penalty

（可选）

float

-

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

max_tokens（可选）

integer

-

指定模型可生成的最大token个数。根据模型不同有不同的上限限制，一般不超过2000。

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]。

tools（可选）

array

None

用于指定可供模型调用的工具库，一次function call流程模型会从中选择其中一个工具。tools中每一个tool的结构如下：

• type，类型为string，表示tools的类型，当前仅支持function。

• function，类型为object，键值包括name，description和parameters：

  • name：类型为string，表示工具函数的名称，必须是字母、数字，可以包含下划线和短划线，最大长度为64。

  • description：类型为string，表示工具函数的描述，供模型选择何时以及如何调用工具函数。

  • parameters：类型为object，表示工具的参数描述，需要是一个合法的JSON Schema。JSON Schema的描述可以见链接。如果parameters参数为空，表示function没有入参。

在function call流程中，无论是发起function call的轮次，还是向模型提交工具函数的执行结果，均需设置tools参数。

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后的长度。

您可以参考字符串与token之间的互相转换进行token的估计。

usage.completion_tokens

integer

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

无

usage.total_tokens

integer

usage.prompt_tokens与usage.completion_tokens的总和。

无

参数

数据类型

默认值

说明

model（必选）

string

无

指定用于对话的通义千问模型名。

messages

array

无

• messages：用户与模型的对话历史。array中的每个元素形式为{"role":角色, "content": 内容}，角色当前可选值：system、user、assistant和tool。

  • system：表示系统级消息，用于指导模型按照预设的规范、角色或情境进行回应。是否使用system角色是可选的，如果使用则必须位于messages的最开始部分。

  • user和assistant：表示用户和模型的消息。它们应交替出现在对话中，模拟实际对话流程。

  • tool：表示工具的消息。在使用function call功能时，如果要传入工具的结果，需将元素的形式设为{"content":"工具返回的结果", "name":"工具的函数名", "role":"tool"}。其中name是工具函数的名称，需要和上轮response中的tool_calls[i]['function']['name']参数保持一致；content是工具函数的输出。

• prompt：用户输入的指令，用于指导模型生成回复。

prompt

string

无（与messages不可同时为空）

seed（可选）

integer

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

max_tokens（可选）

integer

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

top_p（可选）

float

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

top_k（可选）

integer

生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为None或当top_k大于100时，表示不启用top_k策略，此时，仅有top_p策略生效。

repetition_penalty（可选）

float

用于控制模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。没有严格的取值范围。

presence_penalty（可选）

float

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

temperature（可选）

float

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

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

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]。

stream (可选）

boolean

False

用于控制是否使用流式输出。当以stream模式输出结果时，接口返回结果为generator，需要通过迭代获取结果，默认每次输出为当前生成的整个序列，最后一次输出为最终全部生成结果，可以通过设置参数incremental_output为False改变输出模式为非增量输出。

result_format（可选）

string

text

用于指定返回结果的格式，默认为text，也可选择message。推荐您优先使用message格式。

incremental_output (可选）

boolean

False

控制在流式输出模式下是否开启增量输出，即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。

默认False：

I

I like

I like apple

True:

I

like

apple

该参数只能在stream为True时使用。

tools

array

None

用于指定可供模型调用的工具库，一次function call流程模型会从中选择其中一个工具。tools中每一个tool的结构如下：

• type，类型为string，表示tools的类型，当前仅支持function。

• function，类型为object，键值包括name，description和parameters：

  • name：类型为string，表示工具函数的名称，必须是字母、数字，可以包含下划线和短划线，最大长度为64。

  • description：类型为string，表示工具函数的描述，供模型选择何时以及如何调用工具函数。

  • parameters：类型为object，表示工具的参数描述，需要是一个合法的JSON Schema。JSON Schema的描述可以见链接。如果parameters参数为空，表示function没有入参。

使用tools时需要同时指定result_format为message。在function call流程中，无论是发起function call的轮次，还是向模型提交工具函数的执行结果，均需设置tools参数。

参数

类型

说明

status_code

int

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

request_Id

string

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

code

string

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

message

string

失败，表示失败详细信息，成功忽略。

output

dict

调用结果信息，对于千问模型，包含输出text。

output.usage

dict

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

output.text

string

模型生成回复。

output.finish_reason

string

包括以下三种情况：

• null：正在生成

• stop：生成结束时，停止token。

• length：生成结束时，生成长度过长。

usage.input_tokens

int

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

usage.output_tokens

int

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

choices

List

[]

choices[i].finish_reason

string

包括以下三种情况：

• null：正在生成

• stop：生成结束时，停止token。

• length：生成结束时，生成长度过长。

choices[i].message

dict

模型生成消息输出。

message.role

string

模型role，固定为assistant。

message.content

string

模型生成的文本。

传参方式

字段

数据类型

必选

描述

示例值

Header

Content-Type

string

是

请求类型：application/json

"Content-Type":"application/json"

Accept

string

否

选择text/event-stream则会开启SSE响应，默认无设置。

"Accept":"text/event-stream"

Authorization

string

是

API-KEY，例如：Bearer d1**2a

"Authorization":"Bearer d1**2a"

X-DashScope-WorkSpace

string

否

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

ws_QTggmeAxxxxx

X-DashScope-SSE

string

否

设置为enable或者设置Accept: text/event-stream即可启用SSE响应。

"X-DashScope-SSE":"enable"

Body

model

string

是

指定用于对话的通义千问模型名。

"model":"qwen-coder-turbo"

input

object

是

输入模型的信息。

无

input.prompt

string

否

用户当前输入的期望模型执行指令，支持中英文。与input.messages指定其中一个即可。

"input":{"prompt":"你好"}

input.history

array

否

即将废弃，请使用messages字段。用户与模型的对话历史，array中的每个元素形式为{"user":"用户输入","bot":"模型输出"}的一轮对话，多轮对话按时间正序排列。

"input":{"history":[{"user":"今天天气好吗？",

"bot":"今天天气不错，要出去玩玩嘛？"},

{"user":"那你有什么地方推荐？",

"bot":"我建议你去公园，春天来了，花朵开了，很美丽。"}]}

input.messages

array

否

表示用户与模型的对话历史。array中的每个元素形式为{"role":角色, "content": 内容}，如果role为tool，元素形式为：

{"role":"tool","content":内容,"name":工具函数名}

角色可选值：system、user、assistant和tool。

"input":{

"messages":[

{

"role": "system",

"content": "You are a helpful assistant."

},

{

"role": "user",

"content": "你好，附近哪里有博物馆？"

}]

}

input.messages.role

string

messages存在的时候不能省略。

input.messages.content

string

input.messages.name

string

input.messages.role为tool时不能省略

role为tool表示当前message为function_call的调用结果，name是工具函数名，需要和上轮response中的tool_calls[i].function.name参数保持一致，content为工具函数的输出。

parameters

object

否

用于控制模型生成的参数

无

parameters.result_format

string

否

用于指定返回结果的格式，默认为text，也可设置为message。推荐优先使用message格式。

"parameters":{"result_format":"message"}

parameters.seed

integer

否

生成时使用的随机数种子，用户控制模型生成内容的随机性。seed支持无符号64位整数。在使用seed时，模型将尽可能生成相同或相似的结果，但目前不保证每次生成的结果完全相同。

"parameters":{"seed":666}

parameters.max_tokens

integer

否

用于限制模型生成token的数量，表示生成token个数的上限。

"parameters":{"max_tokens":1500}

parameters.top_p

float

否

生成时，核采样方法的概率阈值。例如，取值为0.8时，仅保留累计概率之和大于等于0.8的概率分布中的token，作为随机采样的候选集。取值范围为（0,1.0]，取值越大，生成的随机性越高；取值越低，生成的随机性越低。注意，取值不要大于等于1。

"parameters":{"top_p":0.7}

parameters.top_k

integer

否

生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。注意：如果top_k参数为空或者top_k的值大于100，表示不启用top_k策略，此时仅有top_p策略生效。

"parameters":{"top_k":50}

parameters.repetition_penalty

float

否

用于控制模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度。1.0表示不做惩罚。没有严格的取值范围。

"parameters":{"repetition_penalty":1.0}

parameters.presence_penalty

float

否

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

"parameters":{"presence_penalty":1.0}

parameters.temperature

float

否

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

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

"parameters":{"temperature":0.85}

parameters.stop

string/array

否

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

• string类型

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

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

• array类型

  array中的元素可以为token_id或者字符串，或者元素为token_id的array。当模型将要生成的token或其对应的token_id在stop中时，模型生成将会停止。

  例如将stop指定为["你好","天气"]或者[108386,104307]，则模型将要生成“你好”或者“天气”时停止。如果将stop指定为[[108386, 103924],[35946, 101243]]，则模型将要生成“你好啊”或者“我很好”时停止。

  说明

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

"parameters":{"stop":["你好","天气"]}

parameters.incremental_output

boolean

否

控制在流式输出模式下是否开启增量输出，即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。

默认False：

I

I like

I like apple

True:

I

like

apple

该参数只能在开启SSE响应时使用。

"parameters":{"incremental_output":false}

parameters.tools

array

否

用于指定可供模型调用的工具列表。当输入多个工具时，模型会选择其中一个生成结果。tools中每一个tool的结构如下：

• type，类型为string，表示tools的类型，当前仅支持function。

• function，类型为object，键值包括name，description和parameters：

  • name：类型为string，表示工具函数的名称，必须是字母、数字，可以包含下划线和短划线，最大长度为64。

  • description：类型为string，表示工具函数的描述，供模型选择何时以及如何调用工具函数。

  • parameters：类型为object，表示工具的参数描述，需要是一个合法的JSON Schema。JSON Schema的描述可以见链接。

使用tools时需要同时指定result_format为message。在function call流程中，无论是发起function call的轮次，还是向模型提交工具函数的执行结果，均需设置tools参数。

"parameters":{"tools":[
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": [
                            "celsius",
                            "fahrenheit"
                        ]
                    }
                },
                "required": [
                    "location"
                ]
            }
        }
    }
]}

字段

数据类型

描述

示例值

output.text

string

模型输出的内容。当result_format设置为text时返回该字段。

我建议你去颐和园

output.finish_reason

string

有三种情况：正在生成时为null，生成结束时如果由于停止token导致则为stop，生成结束时如果因为生成长度过长导致则为length。当result_format设置为text时返回该字段。

stop

output.choices

array

当result_format设置为message时返回该字段。

• 普通示例

  {
      "choices": [
          {
              "finish_reason": "null",
              "message": {
                  "role": "assistant",
                  "content": "周围的咖啡馆在..."
              }
          }
      ]
  }

• function call示例

  {
      "choices": [
          {
              "finish_reason": "tool_calls",
              "message": {
                  "role": "assistant",
                  "content": "",
                  "tool_calls": [
                      {
                          "function": {
                              "name": "get_current_weather",
                              "arguments": "{\"location\": \"Boston\", \"unit\": \"fahrenheit\"}"
                          },
                          "type": "function"
                      }
                  ]
              }
          }
      ]
  }

output.choices[x].finish_reason

string

停止原因，null：生成过程中

stop：stop token导致结束

length：生成长度导致结束

output.choices[x].message

object

message每个元素形式为{"role":角色, "content": 内容}。角色可选值：system、user、assistant。content为模型输出的内容。

output.choices[x].message.role

string

output.choices[x].message.content

string

output.choices[x].message.tool_calls

object

如果模型需要调用工具，则会生成tool_calls参数，应用于function_call场景。其中包含type和function两个参数，参数详情如下：

• type，类型为string，当前只可能为function

• function，类型为dict，包含name和arguments两个参数：

  • name，类型为string，表示需要调用的工具的名称，如果是function_call场景则表示要调用的function名称

  • arguments，类型为string，表示模型生成的工具入参，在Python中可以使用json.loads方法转化为字典类型。

usage

object

本次调用使用的token信息。

无

usage.output_tokens

integer

模型输出内容的 token个数。

380

usage.input_tokens

integer

本次请求输入内容的token个数。

633

usage.total_tokens

integer

usage.output_tokens与usage.input_tokens的总和。

1013

request_id

string

本次请求的系统唯一码。

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