文档

通过API调用通义千问数学模型

更新时间:

通义千问数学模型具有强大的数学解题能力,您可以通过API接口调用,将通义千问数学模型集成到您的业务中。

模型概览

模型名称

上下文长度

最大输入

最大输出

输入成本

输出成本

免费额度

(Token数)

(每千Token)

qwen-math-plus

4,096

3,072

3,072

目前仅供免费体验。

免费额度用完后不可调用,敬请关注后续动态。

100万Token

有效期:百炼开通后30天内

qwen-math-plus-0816

关于模型的限流条件,请参见限流

前提条件

  • 请您参考获取API-KEY,开通百炼服务并获得API-KEY。

  • 请在模型概览中选择您需要使用的模型。

  • 您可以使用OpenAI Python SDK、DashScope SDK或HTTP接口调用通义千问模型,请您根据您的需求,参考以下方式准备您的计算环境。

    说明

    如果您之前使用OpenAI SDK以及HTTP方式调用OpenAI的服务,只需在原有框架下调整API-KEY、base_url、model等参数,就可以直接调用通义千问数学模型。

    调用方式

    准备条件

    通过OpenAI Python SDK调用

    您可以通过以下命令安装或更新OpenAI SDK:

    # 如果下述命令报错,请将pip替换为pip3
    pip install -U openai

    您需要配置的base_url如下:

    https://dashscope.aliyuncs.com/compatible-mode/v1

    通过OpenAI兼容-HTTP调用

    如果您需要通过OpenAI兼容的HTTP方式进行调用,需要配置的完整访问endpoint如下:

    POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

    通过DashScope SDK调用

    DashScope SDK提供了Python和Java两个版本,请参考安装SDK,安装最新版SDK。

    通过DashScope HTTP调用

    如果您需要通过DashScope的HTTP方式进行调用,需要配置的完整访问endpoint如下:

    POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation
我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄漏风险,详情可参考配置API-KEY到环境变量。您也可以在代码中配置API-KEY,但是会存在泄露风险。

示例代码

通义千问数学模型擅长解决英文数学类问题,在您的输入问题中请使用LaTex表示数学符号或公式,如:

$x$ 表示数学符号
$4x+5 = 6x+7$ 表示数学公式

此处以一元一次方程为例,向您展示通过OpenAI或者DashScope的方式体验通义千问数学模型在数学问题上的能力。

OpenAI兼容

您可以通过OpenAI SDK或OpenAI兼容的HTTP方式调用通义千问数学模型。

Python

示例代码

from openai import OpenAI
import os

def get_response():
    client = OpenAI(
        api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量,请在此处用您的API Key进行替换
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
    )
    completion = client.chat.completions.create(
        model="qwen-math-plus",
        messages=[
            {'role': 'system', 'content': 'You are a helpful assistant.'},
            {'role': 'user', 'content': 'Find the value of $x$ that satisfies the equation $4x+5 = 6x+7$.'}],
        )
    print(completion.model_dump_json())

if __name__ == '__main__':
    get_response()

返回结果

{
  "id": "chatcmpl-f3b3102c-0e16-9718-9731-0a98fc69b50a",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "To solve the equation \\(4x + 5 = 6x + 7\\), we will follow a step-by-step approach to isolate the variable \\(x\\).\n\n1. **Subtract \\(4x\\) from both sides of the equation:**\n   \\[\n   4x + 5 - 4x = 6x + 7 - 4x\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   5 = 2x + 7\n   \\]\n\n2. **Subtract 7 from both sides of the equation:**\n   \\[\n   5 - 7 = 2x + 7 - 7\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -2 = 2x\n   \\]\n\n3. **Divide both sides by 2:**\n   \\[\n   \\frac{-2}{2} = \\frac{2x}{2}\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -1 = x\n   \\]\n\nTherefore, the value of \\(x\\) that satisfies the equation is \\(\\boxed{-1}\\).",
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1725357364,
  "model": "qwen-math-plus",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 244,
    "prompt_tokens": 42,
    "total_tokens": 286
  }
}

curl

示例代码

curl --location "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "model": "qwen-math-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "Find the value of $x$ that satisfies the equation $4x+5 = 6x+7$."
        }
    ]
}'

返回结果

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "To solve the equation \\(4x + 5 = 6x + 7\\), we will follow a step-by-step approach to isolate the variable \\(x\\).\n\n1. **Subtract \\(4x\\) from both sides of the equation:**\n   \\[\n   4x + 5 - 4x = 6x + 7 - 4x\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   5 = 2x + 7\n   \\]\n\n2. **Subtract 7 from both sides of the equation:**\n   \\[\n   5 - 7 = 2x + 7 - 7\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -2 = 2x\n   \\]\n\n3. **Divide both sides by 2:**\n   \\[\n   \\frac{-2}{2} = \\frac{2x}{2}\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -1 = x\n   \\]\n\nTherefore, the value of \\(x\\) that satisfies the equation is \\(\\boxed{-1}\\)."
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 244,
    "total_tokens": 286
  },
  "created": 1725357415,
  "system_fingerprint": null,
  "model": "qwen-math-plus",
  "id": "chatcmpl-44e32959-aa42-9eb8-9c36-d7ab521bb75c"
}

DashScope

您可以通过DashScope SDK或HTTP方式调用通义千问模型,体验单轮对话的功能。

Python

示例代码

from http import HTTPStatus
import dashscope


def call_with_messages():
    messages = [
        {'role': 'user', 'content': 'Find the value of $x$ that satisfies the equation $4x+5 = 6x+7$.'}]
    response = dashscope.Generation.call(
        model='qwen-math-plus',
        messages=messages,
        result_format='message',  
    )
    if response.status_code == HTTPStatus.OK:
        print(response)
    else:
        print('Request id: %s, Status code: %s, error code: %s, error message: %s' % (
            response.request_id, response.status_code,
            response.code, response.message
        ))

if __name__ == '__main__':
    call_with_messages()
    

返回结果

{
  "status_code": 200,
  "request_id": "ffd50262-6c76-9de0-8027-f454ce5d6453",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "To solve the equation \\(4x + 5 = 6x + 7\\), we will follow a step-by-step approach to isolate the variable \\(x\\).\n\n1. **Subtract \\(4x\\) from both sides of the equation:**\n   \\[\n   4x + 5 - 4x = 6x + 7 - 4x\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   5 = 2x + 7\n   \\]\n\n2. **Subtract 7 from both sides of the equation:**\n   \\[\n   5 - 7 = 2x + 7 - 7\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -2 = 2x\n   \\]\n\n3. **Divide both sides by 2:**\n   \\[\n   \\frac{-2}{2} = \\frac{2x}{2}\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -1 = x\n   \\]\n\nTherefore, the value of \\(x\\) that satisfies the equation is \\(\\boxed{-1}\\)."
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 31,
    "output_tokens": 244,
    "total_tokens": 275
  }
}

Java

示例代码

// Copyright (c) Alibaba, Inc. and its affiliates.

import java.util.Arrays;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.aigc.generation.models.QwenParam;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

public class Main {
    public static void callWithMessage()
            throws NoApiKeyException, ApiException, InputRequiredException {
        Generation gen = new Generation();
        Message userMsg = Message.builder().role(Role.USER.getValue()).content("Find the value of $x$ that satisfies the equation $4x+5 = 6x+7$.").build();
        QwenParam param =
                QwenParam.builder().model("qwen-math-plus").messages(Arrays.asList(userMsg))
                        .resultFormat(QwenParam.ResultFormat.MESSAGE)
                        .build();
        GenerationResult result = gen.call(param);
        System.out.println(JsonUtils.toJson(result));
    }


    public static void main(String[] args){
        try {
            callWithMessage();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

返回结果

{
  "requestId": "d2e87a6d-ba04-9aa5-acaa-ba09a2783c6e",
  "usage": {
    "input_tokens": 31,
    "output_tokens": 244,
    "total_tokens": 275
  },
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "To solve the equation \\(4x + 5 = 6x + 7\\), we will follow a step-by-step approach to isolate the variable \\(x\\).\n\n1. **Subtract \\(4x\\) from both sides of the equation:**\n   \\[\n   4x + 5 - 4x = 6x + 7 - 4x\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   5 = 2x + 7\n   \\]\n\n2. **Subtract 7 from both sides of the equation:**\n   \\[\n   5 - 7 = 2x + 7 - 7\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -2 = 2x\n   \\]\n\n3. **Divide both sides by 2:**\n   \\[\n   \\frac{-2}{2} = \\frac{2x}{2}\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -1 = x\n   \\]\n\nTherefore, the value of \\(x\\) that satisfies the equation is \\(\\boxed{-1}\\)."
        }
      }
    ]
  }
}

curl

示例代码

curl --location "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "model": "qwen-math-plus",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Find the value of $x$ that satisfies the equation $4x+5 = 6x+7$."
            }
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}'

返回结果

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "To solve the equation \\(4x + 5 = 6x + 7\\), we will follow a step-by-step approach to isolate the variable \\(x\\).\n\n1. **Subtract \\(4x\\) from both sides of the equation:**\n   \\[\n   4x + 5 - 4x = 6x + 7 - 4x\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   5 = 2x + 7\n   \\]\n\n2. **Subtract 7 from both sides of the equation:**\n   \\[\n   5 - 7 = 2x + 7 - 7\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -2 = 2x\n   \\]\n\n3. **Divide both sides by 2:**\n   \\[\n   \\frac{-2}{2} = \\frac{2x}{2}\n   \\]\n   Simplifying both sides, we get:\n   \\[\n   -1 = x\n   \\]\n\nTherefore, the value of \\(x\\) that satisfies the equation is \\(\\boxed{-1}\\)."
        }
      }
    ]
  },
  "usage": {
    "total_tokens": 286,
    "output_tokens": 244,
    "input_tokens": 42
  },
  "request_id": "f5f6206f-46ac-9d65-9107-f5e9ced59945"
}

输入与输出参数

您可以通过下表查看不同调用方式的输入参数与输出参数。其中,数据类型列中各字段的含义如下所示:

  • string:字符串类型。

  • array:在Python中表示列表,在Java中表示ArrayList。

  • integer:表示整数型。

  • float:浮点型。

  • boolean:布尔型。

  • object:哈希表。

OpenAI Python SDK

输入参数

参数

类型

默认值

说明

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等工具调用能力较弱,不建议将通义千问数学模型用于function call;如需使用function call能力,建议使用通用的文本模型。

用于指定可供模型调用的工具库,一次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的总和。

OpenAI兼容HTTP

输入参数

传参方式

参数

类型

默认值

说明

Header

Authorization

string

-

API-KEY,例如:Bearer d1**2a

Content-Type

string

-

请求类型,例如:application/json

Body

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等工具调用能力较弱,不建议将通义千问数学模型用于function call;如需使用function call能力,建议使用通用的文本模型。

用于指定可供模型调用的工具库,一次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参数。

说明

tools暂时无法与stream=True同时使用。

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的总和。

DashScope SDK

输入参数

参数

数据类型

默认值

说明

model(必选)

string

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

messages

array

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

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

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

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

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

说明

messages和prompt任选一个参数使用即可。由于和prompt组合使用的对话历史参数history即将废弃,仅依赖prompt指令会限制模型进行有记忆的对话能力。

messages参数允许模型参考历史对话,从而更准确地解析用户的意图,确保对话的流程性和连续性,因此在多轮对话场景下推荐您优先使用messages参数。

prompt

string

无(与messages不可同时为空)

seed(可选)

integer

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

max_tokens(可选)

说明

Java SDK中为maxTokens。

integer

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

top_p(可选)

说明

Java SDK中为topP。

float

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

top_k(可选)

说明

Java SDK中为topK。

integer

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

repetition_penalty(可选)

说明

Java SDK中为repetitionPenalty。

float

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

presence_penalty(可选)

说明

Java SDK中暂不支持该参数。

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

说明

Java SDK中为resultFormat。

string

text

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

incremental_output (可选)

说明

Java SDK中为incrementalOutput。

boolean

False

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

默认False:

I

I like

I like apple

True:

I

like

apple

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

说明

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

tools

array

None

说明

通义千问数学模型对于function call等工具调用能力较弱,不建议将通义千问数学模型用于function call;如需使用function call能力,建议使用通用的文本模型。

用于指定可供模型调用的工具库,一次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参数。

返回结果

  • result_format设置为message时,返回结果示例如下:

    {
        "status_code": 200,
        "request_id": "b3d8bb75-05a2-9044-8e9e-ec8c87689a5e",
        "code": "",
        "message": "",
        "output": {
            "text": null,
            "finish_reason": null,
            "choices": [
                {
                    "finish_reason": "stop",
                    "message": {
                        "role": "assistant",
                        "content": "材料:\n- 萝卜:2根\n- 土豆:2个\n- 茄子:2个\n- 大葱:1根\n- 姜:适量\n- 蒜:适量\n- 食用油:适量\n- 盐:适量\n- 生抽:适量\n- 蚝油:适量\n\n做法:\n\n1. 将萝卜、土豆、茄子分别洗净去皮,切成块状备用。\n2. 大葱切断,姜切片,蒜切末备用。\n3. 烧热锅,加入适量的食用油,放入葱段、姜片、蒜末爆香。\n4. 加入萝卜块,翻炒几分钟,加入适量的盐、生抽调味。\n5. 加入土豆块,继续翻炒几分钟,加入适量的盐、生抽调味。\n6. 加入茄子块,继续翻炒几分钟,加入适量的盐、生抽调味。\n7. 加入适量的蚝油,翻炒均匀,让每一块蔬菜都均匀地裹上蚝油。\n8. 翻炒几分钟,让蔬菜熟透,即可出锅。\n\n这道菜色香味俱佳,营养丰富,可以作为主食或配菜食用。"
                    }
                }
            ]
        },
        "usage": {
            "input_tokens": 31,
            "output_tokens": 267
        }
    }
  • result_format设置为text时,返回结果示例如下:

    {
        "status_code": 200,
        "request_id": "446877aa-dbb8-99ca-98eb-d78a5e90fe61",
        "code": "",
        "message": "",
        "output": {
            "text": "材料:\n- 萝卜:2根\n- 土豆:2个\n- 茄子:2个\n- 大葱:1根\n- 姜:适量\n- 蒜:适量\n- 食用油:适量\n- 盐:适量\n- 生抽:适量\n- 蚝油:适量\n\n做法:\n\n1. 将萝卜、土豆、茄子分别洗净去皮,切成块状备用。\n2. 大葱切段,姜切片,蒜切末备用。\n3. 烧热锅,加入适量的食用油,放入葱段、姜片、蒜末爆香。\n4. 加入萝卜块,翻炒几分钟,加入适量的盐、生抽调味。\n5. 加入土豆块,继续翻炒几分钟,加入适量的盐、生抽调味。\n6. 加入茄子块,继续翻炒几分钟,加入适量的盐、生抽调味。\n7. 加入适量的蚝油,翻炒均匀,让每一块蔬菜都均匀地裹上蚝油。\n8. 翻炒几分钟,让蔬菜熟透,即可出锅。\n\n这道菜色香味俱佳,营养丰富,可以作为主食或配菜食用。",
            "finish_reason": "stop",
            "choices": null
        },
        "usage": {
            "input_tokens": 31,
            "output_tokens": 267
        }
    }

出参描述

参数

类型

说明

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

模型生成的文本。

DashScope HTTP

输入参数

传参方式

字段

数据类型

必选

描述

示例值

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-math-plus"

input

object

输入模型的信息。

input.prompt

说明

字段中的点号(.)表示后者为前者的属性。在API测试工具中,并不能直接将Key设置为input.prompt。传入方式为"input":{"prompt":"xxx"}。

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":工具函数名}

角色可选值:systemuserassistanttool

"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响应时使用。

说明

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

"parameters":{"incremental_output":false}

parameters.tools

array

说明

通义千问数学模型对于function call等工具调用能力较弱,不建议将通义千问数学模型用于function call;如需使用function call能力,建议使用通用的文本模型。

用于指定可供模型调用的工具列表。当输入多个工具时,模型会选择其中一个生成结果。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": 内容}。角色可选值:systemuserassistant。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