通义千问( 二 ) 输入输出参数

3.参数说明

3.1.输入参数

数据类型列中各字段的含义如下所示：

• string表示字符串类型；
• array在Python中表示列表，在Java中表示ArrayList；
• integer表示整数型；
• float表示浮点型；
• boolean表示布尔型；
• object表示哈希表。

参数	数据类型	默认值	说明
model（必选）	string	无	指定用于对话的通义千问模型名。如 : qwen-max, qwen-plus, qwen-turbo
messages	array	无	messages：用户与模型的对话历史。
prompt	string	无（与messages不可同时为空）
seed（可选）	integer		生成时使用的随机数种子，用于控制模型生成内容的随机性。seed支持无符号64位整数。
max_tokens（可选）	integer	1500或2000	Java SDK中为 maxTokens。 指定模型可生成的最大token个数。qwen-turbo最大值和默认值为1500 tokens。qwen-max、qwen-max-1201、qwen-max-longcontext和qwen-plus模型，最大值和默认值均为2000 tokens。
top_p（可选）	float		Java SDK中为topP 生成过程中的核采样方法概率阈值，例如，取值为0.8时，仅保留概率加起来大于等于0.8的最可能token的最小集合作为候选集。取值范围为（0,1.0)，取值越大，生成的随机性越高；取值越低，生成的确定性越高。
top_k（可选）	integer		Java SDK中为 topK 生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为None或当top_k大于100时，表示不启用top_k策略，此时，仅有top_p策略生效。
repetition_penalty（可选）	float		Java SDK中为repetitionPenalty 用于控制模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。没有严格的取值范围。
presence_penalty（可选）	float		Java SDK中暂不支持该参数 用户控制模型生成时整个序列中的重复度。提高presence_penalty时可以降低模型生成的重复度，取值范围[-2.0, 2.0]。
temperature（可选）	float		用于控制模型回复的随机性和多样性。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。取值范围：[0, 2)，不建议取值为0，无意义。
stop (可选）	string or array	None	stop参数用于实现内容生成过程的精确控制，在模型生成的内容即将包含指定的字符串或token_id时自动停止。
stream (可选）	boolean	False	用于控制是否使用流式输出。当以stream模式输出结果时，接口返回结果为generator，需要通过迭代获取结果，默认每次输出为当前生成的整个序列，最后一次输出为最终全部生成结果，可以通过设置参数incremental_output为False改变输出模式为非增量输出。
incremental_output (可选）	boolean	False	Java SDK中为incrementalOutput 控制在流式输出模式下是否开启增量输出，即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。默认False：II likeI like appleTrue:Ilikeapple该参数只能在stream为True时使用。 说明: incremental_output暂时无法和tools参数同时使用。
enable_search（可选）	boolean	False	Java SDK中为enableSearch 用于控制模型在生成文本时是否使用互联网搜索结果进行参考。取值如下：True：启用互联网搜索，模型会将搜索结果作为文本生成过程中的参考信息，但模型会基于其内部逻辑判断是否使用互联网搜索结果。False（默认）：关闭互联网搜索。
result_format（可选）	string	text	Java SDK中为resultFormat 用于指定返回结果的格式，默认为text，也可选择message。推荐您优先使用message格式。
tools	array	None	用于指定可供模型调用的工具库，一次function call流程模型会从中选择其中一个工具。
tool_choice	string or object	见说明	Java SDK中为toolChoice。 在使用tools参数时，用于控制模型调用指定工具。

3.1.1.messages 与prompt

messages：用户与模型的对话历史。在array中包含多种不同的角色的信息内容, 每个元素形式为{ "role": 角色 , "content": 内容}。

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

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

• user : 表示用户的消息。一定出现在对话的最后一个。

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

• tool：表示工具的消息。在使用function call功能时，如果要传入工具的结果，需将元素的形式设为{"content":"工具返回的结果", "name":"工具的函数名", "role":"tool"}。

  • 其中name是工具函数的名称，需要和上轮 response 中的 tool_calls[i]['function']['name']参数保持一致；
  • content是工具函数的输出。

prompt：用户输入的指令，用于指导模型生成回复。messages和prompt任选一个参数使用即可。

由于和prompt组合使用的对话历史参数history即将废弃，仅依赖prompt指令会限制模型进行有记忆的对话能力。messages参数允许模型参考历史对话，从而更准确地解析用户的意图，确保对话的流程性和连续性，因此在多轮对话场景下推荐您优先使用messages参数。

3.1.2. stop

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

3.1.3.tools

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

tools中每一个tool的结构如下：

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

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

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

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

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

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

tools暂时无法和incremental_output参数同时使用。

3.1.4.toolChoice

toolChoice在使用tools参数时，用于控制模型调用指定工具。

有三种取值：

• "none"表示不调用工具。tools参数为空时，默认值为"none"。

• "auto"表示模型判断是否调用工具，可能调用也可能不调用。tools参数不为空时，默认值为"auto"。

• object结构可以指定模型调用指定工具。例如tool_choice={"type": "function", "function": {"name": "user_function"}}。

  • type 只支持指定为"function"。

  • function

    • name表示期望被调用的工具名称，例如"get_current_time"。

当前支持qwen-max/qwen-max-0428/qwen-max-0403/qwen-plus/qwen-turbo

3.2.输出参数

返回参数	数据类型	说明	备注
status_code	integer	200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。	只有Python会输出该参数，使用Java调用失败会抛出异常，异常信息为code和message的内容。
code	string	表示错误码，调用成功时为空值。	仅适用于Python。
message	string	表示调用失败的详细信息，调用成功时为空值。	仅适用于Python。
request_id	string	系统生成的标志本次调用的id。	无
output	object	表示调用结果信息。	无
output.text	string	模型生成的回复。	在使用prompt传入指令时不为空
output.finish_reason	string	有四种情况：正在生成时为null； 因触发输入参数中的stop条件而结束为stop； 因生成长度过长而结束为length； 因发生工具调用为tool_calls。
output.choices	array	当result_format为message时输出choices。	当result_format为message时输出choices。
output.choices[i].finish_reason	string	有三种情况： 正在生成时为null； 因触发输入参数中的stop条件而结束为stop； 因生成长度过长而结束为length。
output.choices[i].message	object	模型输出的消息。
output.choices[i].message.role	string	模型的角色，固定为assistant。
output.choices[i].message.content	string	模型生成的文本。
output.choices[i].message.tool_calls	object	如果模型需要调用工具，则会生成tool_calls参数，应用于function call场景。
usage	object	计量信息，表示本次请求所消耗的token数据。	无
usage.input_tokens	integer	用户输入文本转换成token后的长度。	可以进行token的估计。
usage.output_tokens	integer	模型生成回复转换为token后的长度。	无
usage.total_tokens	integer	usage.input_tokens与usage.output_tokens的总和	无

3.2.1.tool_calls

output.choices[i].message.tool_calls

包含三个参数：type、function和id 。

• type :

  ​ 类型为string，当前只能设置为function。

• function :

  ​ 类型为object，包含name和arguments两个参数：

  • name : 类型为string，表示需要调用的工具的名称，如果是function call场景则表示要调用的工具函数名称。
  • arguments : 类型为string，表示模型生成的要传入工具的参数。可以通过Python中的json.loads方法解析为字典。