文档

API详情

更新时间:
一键部署

通义千问模型具有强大的自然语言处理能力,您可以使用DashScope SDK或HTTP接口调用通义千问模型,将通义千问模型集成到您的业务中。

模型概览

您可以通过API使用的通义千问系列模型详情如下表所示:

模型名称

模型简介

模型输入/输出限制

qwen-turbo

通义千问超大规模语言模型,支持中文、英文等不同语言输入。

模型支持8k tokens上下文,为了保证正常的使用和输出,API限定用户输入为6k tokens

qwen-plus

通义千问超大规模语言模型增强版,支持中文、英文等不同语言输入。

模型支持32k tokens上下文,为了保证正常的使用和输出,API限定用户输入为30k tokens

qwen-max

通义千问千亿级别超大规模语言模型支持中文、英文等不同语言输入。随着模型的升级,qwen-max将滚动更新升级,如果希望使用稳定版本,请使用下面的历史快照版本。

模型支持8k tokens上下文,为了保证正常的使用和输出,API限定用户输入为6k tokens

qwen-max-0403

通义千问千亿级别超大规模语言模型,支持中文、英文等不同语言输入。该模型为qwen-max的2024年4月3号的历史快照稳定版本,预期维护到下个快照版本发布时间(待定)后一个月。

qwen-max-0107

通义千问千亿级别超大规模语言模型,支持中文、英文等不同语言输入。该模型为qwen-max的2024年1月7号的历史快照稳定版本,仅推荐特定需求客户访问。

qwen-max-1201

通义千问千亿级别超大规模语言模型,支持中文、英文等不同语言输入。

说明

该模型为qwen-max的2023年12月1号的历史快照稳定版本,该版本的维护时间已经到期,4月22日下线,请及时迁移到更新版本模型。(4月8日开始模型限流也会逐步调低直至下线)

qwen-max-longcontext

通义千问千亿级别超大规模语言模型支持中文、英文等不同语言输入。

模型支持30k tokens上下文,为了保证正常的使用和输出,API限定用户输入为28k tokens

说明

您可以在调用时按需选择不同版本的模型,不同版本模型的计费规则不一致,具体详情,请参见计量计费

重要

不同版本的模型每分钟可被调用次数与tokens数不同,在您调用前建议查看基础限流了解您所使用模型的限流条件。

SDK使用

前提条件

说明

当您使用DashScope Java SDK时,为了效率您应该尽可能复用Generation以及其他请求对象,但对象(如Generation)不是线程安全的,您应该采取一定的措施,如及时关闭进程、管理同步机制等,来确保对象安全。

单轮对话

您可以将通义千问应用在内容创作、翻译服务、文本摘要等多种场景。您可以运行以下示例代码,体验通义千问模型的单轮对话能力。

import random
from http import HTTPStatus
from dashscope import Generation  # 建议dashscope SDK 的版本 >= 1.14.0


def call_with_messages():
    messages = [{'role': 'system', 'content': 'You are a helpful assistant.'},
                {'role': 'user', 'content': '如何做西红柿炒鸡蛋?'}]
    response = Generation.call(model="qwen-turbo",
                               messages=messages,
                               # 设置随机数种子seed,如果没有设置,则随机数种子默认为1234
                               seed=random.randint(1, 10000),
                               # 将输出设置为"message"格式
                               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()
// Copyright (c) Alibaba, Inc. and its affiliates.

// 建议dashscope SDK的版本 >= 2.12.0

import java.util.Arrays;  
import com.alibaba.dashscope.aigc.generation.Generation;  
import com.alibaba.dashscope.aigc.generation.GenerationParam;  
import com.alibaba.dashscope.aigc.generation.GenerationResult;  
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;  
  
public class Main {  
  
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {  
        Generation gen = new Generation();  
          
        Message systemMsg = Message.builder()  
                .role(Role.SYSTEM.getValue())  
                .content("You are a helpful assistant.")  
                .build();  
          
        Message userMsg = Message.builder()  
                .role(Role.USER.getValue())  
                .content("如何做西红柿炒鸡蛋?")  
                .build();  
          
        GenerationParam param = GenerationParam.builder()  
                .model("qwen-turbo")  
                .messages(Arrays.asList(systemMsg, userMsg))  
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)  
                .topP(0.8)  
                .build();  
          
        return gen.call(param);  
    }  
  
    public static void main(String[] args) {  
        try {  
            GenerationResult result = callWithMessage();  
            System.out.println(result);  
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {  
            // 使用日志框架记录异常信息  
            // Logger.error("An error occurred while calling the generation service", e);  
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());  
        }  
         System.exit(0);
    }  
}

运行结果的示例如下所示:

{
    "status_code": 200,
    "request_id": "5d768057-2820-91ba-8c99-31cd520e7628",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "材料:\n西红柿2个,鸡蛋3个,油适量,盐适量,糖适量,葱花适量。\n\n步骤:\n\n1. 鸡蛋打入碗中,加入少许盐,用筷子搅拌均匀,放置一会儿让蛋白和蛋黄充分融合。\n\n2. 西红柿洗净,切成小块。如果喜欢口感更沙一些,可以切得稍微大一些;如果喜欢口感细腻,可以切得小一些。\n\n3. 热锅凉油,油热后倒入打好的鸡蛋液,用铲子快速搅拌,炒至鸡蛋凝固并变成金黄色,盛出备用。\n\n4. 锅中再加一点油,放入切好的西红柿,用中小火慢慢翻煮,让西红柿出汁,这样炒出来的西红柿才会更甜。\n\n5. 西红柿出汁后,加入适量的糖,继续翻煮,直到西红柿变得软烂。\n\n6. 将炒好的鸡蛋倒回锅中,与西红柿一起翻煮均匀,让鸡蛋充分吸收西红柿的汁水。\n\n7. 最后,根据个人口味加入适量的盐调味,撒上葱花进行提香,翻炒均匀即可出锅。\n\n8. 如果喜欢汤汁多一些,可以适当加点水,调整一下浓稠度。\n\n西红柿炒鸡蛋就做好了,简单易做,营养美味,是一道家常菜的经典之作。"
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 25,
        "output_tokens": 289,
        "total_tokens": 314
    }
}

多轮对话

相比于单轮对话,多轮对话可以参考历史聊天信息,更符合日常交流的场景。但由于调用时会引入历史聊天信息,使用的token量会增多。您可以运行以下示例代码,体验通义千问模型的多轮对话能力。

from http import HTTPStatus
from dashscope import Generation


def multi_round():
    messages = [{'role': 'system', 'content': 'You are a helpful assistant.'},
                {'role': 'user', 'content': '如何做西红柿炖牛腩?'}]
    response = Generation.call(model="qwen-turbo",
                               messages=messages,
                               # 将输出设置为"message"格式
                               result_format='message')
    if response.status_code == HTTPStatus.OK:
        print(response)
        # 将assistant的回复添加到messages列表中
        messages.append({'role': response.output.choices[0]['message']['role'],
                         'content': response.output.choices[0]['message']['content']})
    else:
        print('Request id: %s, Status code: %s, error code: %s, error message: %s' % (
            response.request_id, response.status_code,
            response.code, response.message
        ))
        # 如果响应失败,将最后一条user message从messages列表里删除,确保user/assistant消息交替出现
        messages = messages[:-1]
    # 将新一轮的user问题添加到messages列表中
    messages.append({'role': 'user', 'content': '不放糖可以吗?'})
    # 进行第二轮模型的响应
    response = Generation.call(model="qwen-turbo",
                               messages=messages,
                               result_format='message',  # 将输出设置为"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__':
    multi_round()
// Copyright (c) Alibaba, Inc. and its affiliates.

import java.util.ArrayList;  
import java.util.List;    
import com.alibaba.dashscope.aigc.generation.Generation;  
import com.alibaba.dashscope.aigc.generation.GenerationParam;  
import com.alibaba.dashscope.aigc.generation.GenerationResult;  
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 GenerationParam createGenerationParam(List<Message> messages) {  
        return GenerationParam.builder()  
                .model("qwen-turbo")  
                .messages(messages)  
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)  
                .topP(0.8)  
                .build();  
    }  
  
    public static GenerationResult callGenerationWithMessages(GenerationParam param) throws ApiException, NoApiKeyException, InputRequiredException {  
        Generation gen = new Generation();  
        return gen.call(param);  
    }  
  
    public static void main(String[] args) {  
        try {  
            List<Message> messages = new ArrayList<>();  
            messages.add(createMessage(Role.SYSTEM, "You are a helpful assistant."));  
            messages.add(createMessage(Role.USER, "如何做西红柿炖牛腩?"));  
  
            GenerationParam param = createGenerationParam(messages);  
            GenerationResult result = callGenerationWithMessages(param);  
            printResult(result);  
  
            // 添加assistant返回的消息到列表  
            messages.add(result.getOutput().getChoices().get(0).getMessage());  
  
            // 添加新的用户消息  
            messages.add(createMessage(Role.USER, "不放糖可以吗?"));  
  
            result = callGenerationWithMessages(param);  
            printResult(result);  
            printResultAsJson(result);  
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {  
            e.printStackTrace(); 
        } 
           System.exit(0); 
    }  
  
    private static Message createMessage(Role role, String content) {  
        return Message.builder().role(role.getValue()).content(content).build();  
    }  
  
    private static void printResult(GenerationResult result) {  
        System.out.println(result);  
    }  
  
    private static void printResultAsJson(GenerationResult result) {  
        System.out.println(JsonUtils.toJson(result));  
    }  
}

运行结果的示例如下所示:

{
    "status_code": 200,
    "request_id": "10b7f68b-f4a3-9798-8f1b-c2177eadf4b2",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "材料:\n牛腩500克,西红柿3个,洋葱1个,大蒜4瓣,生姜2片,八角2颗,香叶2片,干辣椒2个,生抽、老抽、料酒、糖、盐适量,清水适量\n\n步骤:\n\n1. 牛腩切块,用清水浸泡半小时,去除血水和杂质。然后冲洗干净备用。\n\n2. 西红柿洗净,切成滚刀块。洋葱切块,大蒜和生姜切片。\n\n3. 热锅凉油,下入八角、香叶、干辣椒炒出香味。\n\n4. 加入洋葱块,翻炒至微黄。\n\n5. 倒入牛腩块,大火翻炒几分钟,使其表面微焦,这样可以锁住肉的鲜味。\n\n6. 加入大蒜和生姜片,继续翻炒均匀。\n\n7. 倒入料酒,煮一会儿去腥。\n\n8. 加入生抽、老抽上色,再加适量糖,翻炒均匀。\n\n9. 倒入足够的清水,水量要没过牛腩,大火烧开后撇去浮沫。\n\n10. 转小火,加入西红柿块,盖上锅盖慢慢炖煮,期间可适当调整火力,保持汤汁微微沸腾。\n\n11. 炖煮约1-1.5小时,直到牛腩变得软烂,汤汁浓稠。\n\n12. 最后根据个人口味加盐调味,收汁即可。\n\n13. 出锅前可撒些葱花或者香菜提香。\n\n这道西红柿炖牛腩就做好了,香气四溢,肉质酥烂,非常美味。"
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 26,
        "output_tokens": 361,
        "total_tokens": 387
    }
}
{
    "status_code": 200,
    "request_id": "a00b67bd-f477-93ea-a648-862179d7d1fe",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "当然可以,糖主要是为了中和牛肉的腥味并增加一些甜味。如果你不喜欢或不添加糖,也可以,只是口感可能会稍微偏重于牛肉本身的原味,而且可能没有那么甜润。你可以根据自己的口味来调整,如果牛腩本身比较嫩,或者你喜欢酸甜口,可以少放或者不放糖,如果牛腩较老,可能会需要一些糖来提升风味。"
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 403,
        "output_tokens": 88,
        "total_tokens": 491
    }
}

您也可以运行以下代码,体验实时交互的功能。

from dashscope import Generation

def get_response(messages):
    response = Generation.call(model="qwen-turbo",
                               messages=messages,
                               # 将输出设置为"message"格式
                               result_format='message')
    return response


messages = [{'role': 'system', 'content': 'You are a helpful assistant.'}]

# 您可以自定义设置对话轮数,当前为3
for i in range(3):
    user_input = input("请输入:")
    messages.append({'role': 'user', 'content': user_input})
    assistant_output = get_response(messages).output.choices[0]['message']['content']
    messages.append({'role': 'assistant', 'content': assistant_output})
    print(f'用户输入:{user_input}')
    print(f'模型输出:{assistant_output}')
    print('\n')
import java.util.ArrayList;
import java.util.List;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
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 java.util.Scanner;

public class Main {

    public static GenerationParam createGenerationParam(List<Message> messages) {
        return GenerationParam.builder()
                .model("qwen-turbo")
                .messages(messages)
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .topP(0.8)
                .build();
    }

    public static GenerationResult callGenerationWithMessages(GenerationParam param) throws ApiException, NoApiKeyException, InputRequiredException {
        Generation gen = new Generation();
        return gen.call(param);
    }

    public static void main(String[] args) {
        try {
            List<Message> messages = new ArrayList<>();

            messages.add(createMessage(Role.SYSTEM, "You are a helpful assistant."));
            for (int i = 0; i < 3;i++) {
                Scanner scanner = new Scanner(System.in);
                System.out.print("请输入:");
                String userInput = scanner.nextLine();
                if ("exit".equalsIgnoreCase(userInput)) {
                    break;
                }
                messages.add(createMessage(Role.USER, userInput));
                GenerationParam param = createGenerationParam(messages);
                GenerationResult result = callGenerationWithMessages(param);
                System.out.println("模型输出:"+result.getOutput().getChoices().get(0).getMessage().getContent());
                messages.add(result.getOutput().getChoices().get(0).getMessage());
            }
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            e.printStackTrace();
        }
        System.exit(0);
    }

    private static Message createMessage(Role role, String content) {
        return Message.builder().role(role.getValue()).content(content).build();
    }
}

在您输入问题后,点击Enter键令模型生成回复。使用过程示例如下图所示:

2024-04-08_18-58-36 (1).gif

流式输出

大模型并不是一次性生成最终结果,而是逐步地生成中间结果,最终结果由中间结果拼接而成。非流式输出方式等待模型生成结束后再将生成的中间结果拼接后返回,而流式输出可以实时地将中间结果返回,您可以在模型进行输出的同时进行阅读,减少等待模型回复的时间。使用流式输出需要您进行一些配置,DashScope Python SDK中需要设置stream为True,DashScope Java SDK中需要使用streamCall接口调用。

from http import HTTPStatus
from dashscope import Generation


def call_with_stream():
    messages = [
        {'role': 'user', 'content': '如何做西红柿炖牛腩?'}]
    responses = Generation.call(model="qwen-turbo",
                                messages=messages,
                                result_format='message',  # 设置输出为'message'格式
                                stream=True,  # 设置输出方式为流式输出
                                incremental_output=True  # 增量式流式输出
                                )
    for response in responses:
        if response.status_code == HTTPStatus.OK:
            print(response.output.choices[0]['message']['content'], end='')
        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_stream()
// Copyright (c) Alibaba, Inc. and its affiliates.

import java.util.Arrays;
import java.util.concurrent.Semaphore;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.concurrent.Semaphore;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.ResultCallback;
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;
import io.reactivex.Flowable;

public class Main {

    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    private static void handleGenerationResult(GenerationResult message, StringBuilder fullContent) {
        fullContent.append(message.getOutput().getChoices().get(0).getMessage().getContent());
        logger.info("Received message: {}", JsonUtils.toJson(message));
    }

    public static void streamCallWithMessage(Generation gen, Message userMsg)
            throws NoApiKeyException, ApiException, InputRequiredException {
        GenerationParam param = buildGenerationParam(userMsg);
        Flowable<GenerationResult> result = gen.streamCall(param);
        StringBuilder fullContent = new StringBuilder();

        result.blockingForEach(message -> handleGenerationResult(message, fullContent));

        logger.info("Full content: \n{}", fullContent.toString());
    }

    public static void streamCallWithCallback(Generation gen, Message userMsg)
            throws NoApiKeyException, ApiException, InputRequiredException, InterruptedException {
        GenerationParam param = buildGenerationParam(userMsg);
        Semaphore semaphore = new Semaphore(0);
        StringBuilder fullContent = new StringBuilder();

        gen.streamCall(param, new ResultCallback<GenerationResult>() {
            @Override
            public void onEvent(GenerationResult message) {
                handleGenerationResult(message, fullContent);
            }

            @Override
            public void onError(Exception err) {
                logger.error("Exception occurred: {}", err.getMessage());
                semaphore.release();
            }

            @Override
            public void onComplete() {
                logger.info("Completed");
                semaphore.release();
            }
        });

        semaphore.acquire();
        logger.info("Full content: \n{}", fullContent.toString());
    }

    private static GenerationParam buildGenerationParam(Message userMsg) {
        return GenerationParam.builder()
                .model("qwen-turbo")
                .messages(Arrays.asList(userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .topP(0.8)
                .incrementalOutput(true)
                .build();
    }

    public static void main(String[] args) {
        try {
            Generation gen = new Generation();
            Message userMsg = Message.builder().role(Role.USER.getValue()).content("如何做西红柿炖牛腩?").build();

            streamCallWithMessage(gen, userMsg);
            streamCallWithCallback(gen, userMsg);
        } catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
            logger.error("An exception occurred: {}", e.getMessage());
        }
    }
}

流式输出效果如下图所示:2024-04-08_19-12-00 (1).gif

Function call

大模型在面对实时性问题、私域知识型问题或数学计算等问题时可能效果不佳。您可以使用function call功能,通过调用外部工具来提升模型的输出效果。您可以在调用大模型时,通过tools参数传入工具的名称、描述、入参等信息。大模型在收到提示词以及工具信息后,会判断是否需要使用工具:

  • 如果不需要使用工具,大模型不会返回tool_calls参数,您的程序可以直接返回大模型的回答。

  • 如果需要使用工具,大模型会返回一个包含tool_calls字段的信息,您的程序可以根据此信息判断需要调用工具。您的程序需要解析tool_calls信息中包含的工具函数名和入参,并将入参输入到工具函数来得到工具调用的结果。您的程序需要将工具信息按照以下格式配置:

    {
        "name": "$工具名",
        "role": "tool",
        "content": "$工具输出"
    }

    将工具信息添加到历史对话信息中,再次向大模型提问,获得最终回答。

Function call的工作流程示意图如下所示:

image
说明

Function call信息暂时不支持增量输出,增量输出请参考输入参数配置中incremental_output参数。

示例代码如下所示:

from dashscope import Generation
from datetime import datetime
import random

# 定义工具列表,模型在选择使用哪个工具时会参考工具的name和description
tools = [
    # 工具1 获取当前时刻的时间
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "当你想知道现在的时间时非常有用。",
            "parameters": {}  # 因为获取当前时间无需输入参数,因此parameters为空字典
        }
    },  
    # 工具2 获取指定城市的天气
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "当你想查询指定城市的天气时非常有用。",
            "parameters": {  # 查询天气时需要提供位置,因此参数设置为location
                        "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "城市或县区,比如北京市、杭州市、余杭区等。"
                    }
                }
            },
            "required": [
                "location"
            ]
        }
    }
]

# 模拟天气查询工具。返回结果示例:“北京今天是晴天。”
def get_current_weather(location):
    return f"{location}今天是晴天。 "

# 查询当前时间的工具。返回结果示例:“当前时间:2024-04-15 17:15:18。“
def get_current_time():
    # 获取当前日期和时间
    current_datetime = datetime.now()
    # 格式化当前日期和时间
    formatted_time = current_datetime.strftime('%Y-%m-%d %H:%M:%S')
    # 返回格式化后的当前时间
    return f"当前时间:{formatted_time}。"

# 封装模型响应函数
def get_response(messages):
    response = Generation.call(
        model='qwen-turbo',
        messages=messages,
        tools=tools,
        seed=random.randint(1, 10000),  # 设置随机数种子seed,如果没有设置,则随机数种子默认为1234
        result_format='message'  # 将输出设置为message形式
    )
    return response

def call_with_messages():
    messages = [
            {
                "content": input('请输入问题:'),  # 提问示例:"现在几点了?" "一个小时后几点" "北京天气如何?"
                "role": "user"
            }
    ]
    
    # 模型的第一轮调用
    assistant_output = get_response(messages).output.choices[0].message
    messages.append(assistant_output)
    if 'tool_calls' not in assistant_output:  # 如果模型判断无需调用工具,则将assistant的回复直接打印出来,无需进行模型的第二轮调用
        print(assistant_output.content)
        return
    # 如果模型选择的工具是get_current_weather
    elif assistant_output.tool_calls[0]['function']['name'] == 'get_current_weather':
        tool_info = {"name": "get_current_weather", "role":"tool"}
        location = assistant_output.tool_calls[0]['function']['arguments']
        tool_info['content'] = get_current_weather(location)
    # 如果模型选择的工具是get_current_time
    elif assistant_output.tool_calls[0]['function']['name'] == 'get_current_time':
        tool_info = {"name": "get_current_time", "role":"tool"}
        tool_info['content'] = get_current_time()
    messages.append(tool_info)

    # 模型的第二轮调用,对工具的输出进行总结
    response = get_response(messages)
    print(f"模型回复:{response.output.choices[0].message['content']}")

if __name__ == '__main__':
    call_with_messages()
// Copyright (c) Alibaba, Inc. and its affiliates.
// version >= 2.12.0
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import com.alibaba.dashscope.aigc.conversation.ConversationParam.ResultFormat;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationOutput.Choice;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
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.tools.FunctionDefinition;
import com.alibaba.dashscope.tools.ToolCallBase;
import com.alibaba.dashscope.tools.ToolCallFunction;
import com.alibaba.dashscope.tools.ToolFunction;
import com.alibaba.dashscope.utils.JsonUtils;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.github.victools.jsonschema.generator.Option;
import com.github.victools.jsonschema.generator.OptionPreset;
import com.github.victools.jsonschema.generator.SchemaGenerator;
import com.github.victools.jsonschema.generator.SchemaGeneratorConfig;
import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
import com.github.victools.jsonschema.generator.SchemaVersion;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Scanner;

public class Main {

    public class GetWhetherTool {
        private String location;

        public GetWhetherTool(String location) {
            this.location = location;
        }

        public String call() {
            return location+"今天是晴天";
        }
    }

    public class GetTimeTool {

        public GetTimeTool() {
        }

        public String call() {
            LocalDateTime now = LocalDateTime.now();
            DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
            String currentTime = "当前时间:" + now.format(formatter) + "。";
            return currentTime;
        }
    }

    public static void SelectTool()
            throws NoApiKeyException, ApiException, InputRequiredException {

        SchemaGeneratorConfigBuilder configBuilder =
                new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON);
        SchemaGeneratorConfig config = configBuilder.with(Option.EXTRA_OPEN_API_FORMAT_VALUES)
                .without(Option.FLATTENED_ENUMS_FROM_TOSTRING).build();
        SchemaGenerator generator = new SchemaGenerator(config);


        ObjectNode jsonSchema = generator.generateSchema(GetWhetherTool.class);


        FunctionDefinition fd1 = FunctionDefinition.builder().name("get_current_whether").description("获取指定地区的天气")
                .parameters(JsonUtils.parseString(jsonSchema.toString()).getAsJsonObject()).build();

        FunctionDefinition fd2 = FunctionDefinition.builder().name("get_current_time").description("获取当前时刻的时间")
                .parameters(JsonUtils.parseString(jsonSchema.toString()).getAsJsonObject()).build();

        Message systemMsg = Message.builder().role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant. When asked a question, use tools wherever possible.")
                .build();

        Scanner scanner = new Scanner(System.in);
        System.out.print("请输入:");
        String userInput = scanner.nextLine();
        Message userMsg =
                Message.builder().role(Role.USER.getValue()).content(userInput).build();

        List<Message> messages = new ArrayList<>();
        messages.addAll(Arrays.asList(systemMsg, userMsg));

        GenerationParam param = GenerationParam.builder().model(Generation.Models.QWEN_MAX)
                .messages(messages).resultFormat(ResultFormat.MESSAGE)
                .tools(Arrays.asList(ToolFunction.builder().function(fd1).build(),ToolFunction.builder().function(fd2).build())).build();
        // 大模型的第一轮调用
        Generation gen = new Generation();
        GenerationResult result = gen.call(param);

        System.out.println("大模型第一轮输出信息:"+JsonUtils.toJson(result));

        for (Choice choice : result.getOutput().getChoices()) {
            messages.add(choice.getMessage());
            // 如果需要调用工具
            if (result.getOutput().getChoices().get(0).getMessage().getToolCalls() != null) {
                for (ToolCallBase toolCall : result.getOutput().getChoices().get(0).getMessage()
                        .getToolCalls()) {
                    if (toolCall.getType().equals("function")) {
                        // 获取工具函数名称和入参
                        String functionName = ((ToolCallFunction) toolCall).getFunction().getName();
                        String functionArgument = ((ToolCallFunction) toolCall).getFunction().getArguments();
                        // 大模型判断调用天气查询工具的情况
                        if (functionName.equals("get_current_whether")) {
                            GetWhetherTool GetWhetherFunction =
                                    JsonUtils.fromJson(functionArgument, GetWhetherTool.class);
                            String whether = GetWhetherFunction.call();
                            Message toolResultMessage = Message.builder().role("tool")
                                    .content(String.valueOf(whether)).toolCallId(toolCall.getId()).build();
                            messages.add(toolResultMessage);
                            System.out.println("工具输出信息:"+whether);
                        }
                        // 大模型判断调用时间查询工具的情况
                        else if (functionName.equals("get_current_time")) {
                            GetTimeTool GetTimeFunction =
                                    JsonUtils.fromJson(functionArgument, GetTimeTool.class);
                            String time = GetTimeFunction.call();
                            Message toolResultMessage = Message.builder().role("tool")
                                    .content(String.valueOf(time)).toolCallId(toolCall.getId()).build();
                            messages.add(toolResultMessage);
                            System.out.println("工具输出信息:"+time);
                        }
                    }
                }
            }
            // 如果无需调用工具,直接输出大模型的回复
            else {
                System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
                return;
            }
        }
        // 大模型的第二轮调用 包含工具输出信息
        param.setMessages(messages);
        result = gen.call(param);
        System.out.println("大模型第二轮输出信息:"+JsonUtils.toJson(result));
    }


    public static void main(String[] args) {
        try {
            SelectTool();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(String.format("Exception %s", e.getMessage()));
        }
        System.exit(0);
    }
}

通过运行以上代码,您可以输入问题,得到在工具辅助条件下模型的输出结果。使用过程示例如下图所示:2024-04-18_16-02-10 (1).gif

以下是发起function call流程(模型的第一轮调用)时模型的返回信息。当输入“杭州天气”时,模型会返回tool_calls参数;当输入“你好”时,模型判断无需调用工具,不会返回tool_calls参数。

输入:杭州天气

{
    "status_code": 200,
    "request_id": "bd803417-56a7-9597-9d3f-a998a35b0477",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "tool_calls",
                "message": {
                    "role": "assistant",
                    "content": "",
                    "tool_calls": [
                        {
                            "function": {
                                "name": "get_current_weather",
                                "arguments": "{\"properties\": {\"location\": \"杭州市\"}, \"type\": \"object\"}"
                            },
                            "id": "",
                            "type": "function"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 222,
        "output_tokens": 27,
        "total_tokens": 249
    }
}

输入:你好

{
    "status_code": 200,
    "request_id": "28e9d70c-c4d7-9bfb-bd07-8cf4228dda91",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "你好!有什么能帮到你的吗?如果有关于天气、时间或者其他问题,随时告诉我。"
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 221,
        "output_tokens": 21,
        "total_tokens": 242
    }
}

您可以根据您的需求,参照代码中tools的定义来扩充您的工具库。

输入参数配置

模型的生成结果由输入参数的配置决定,如用户指令、模型名称、是否流式输出、温度参数等。您可以查看下表来了解响应函数输入参数的配置方式。

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

  • string表示字符串类型;

  • array在Python中表示列表,在Java中表示ArrayList;

  • integer表示整数型;

  • float表示浮点型;

  • boolean表示布尔型;

  • object表示哈希表。

参数

数据类型

默认值

说明

model(必选)

string

指定用于对话的通义千问模型名,目前可选择qwen-turboqwen-plusqwen-maxqwen-max-0403qwen-max-0107qwen-max-1201qwen-max-longcontext

说明

qwen-max-0403qwen-max-0107qwen-max-1201qwen-max-longcontext在当前SDK版本中未定义,您可以指定model为模型名称字符串进行调用。

例如:

Python:model='qwen-max-longcontext'

Java:.model("qwen-max-0403")

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不可同时为空)

history(可选)

array

[]

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

seed (可选)

integer

1234

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

max_tokens(可选)

integer

1500或2000

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

  • qwen-turbo最大值和默认值为1500 tokens。

  • qwen-maxqwen-max-1201qwen-max-longcontextqwen-plus模型,最大值和默认值均为2000 tokens。

top_p (可选)

float

0.8

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

top_k (可选)

integer

None

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

repetition_penalty (可选)

float

1.1

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

temperature(可选)

float

0.85

用于控制模型回复的随机性和多样性。具体来说,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改变输出模式为非增量输出。

enable_search (可选)

boolean

False

用于控制模型在生成文本时是否使用互联网搜索结果进行参考。取值如下:

  • True:启用互联网搜索,模型会将搜索结果作为文本生成过程中的参考信息,但模型会基于其内部逻辑判断是否使用互联网搜索结果。

  • False(默认):关闭互联网搜索。

result_format (可选)

string

text

用于指定返回结果的格式,默认为text,也可选择message。当设置为message时,输出格式请参考返回结果。推荐您优先使用message格式。

incremental_output (可选)

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流程模型会从中选择其中一个工具。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参数。当前支持的模型包括qwen-turbo、qwen-plus、qwen-max和qwen-max-longcontext。

说明

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

返回结果

  • result_format设置为"message"时的结果示例:

    {
        "status_code": 200,
        "request_id": "05dc83af-7185-9e14-9b0b-4466de159d6a",
        "code": "",
        "message": "",
        "output": {
            "text": null,
            "finish_reason": null,
            "choices": [
                {
                    "finish_reason": "stop",
                    "message": {
                        "role": "assistant",
                        "content": "首先,准备两个鸡蛋,一个西红柿,适量的盐、糖、料酒和生抽。将鸡蛋打入碗中,搅拌均匀,西红柿切块。锅中加油,油热后加入鸡蛋液,炒至金黄色,盛出备用。锅中加油,油热后加入西红柿块,翻炒均匀,加入适量的盐、糖、料酒和生抽,炒至西红柿软烂,加入炒好的鸡蛋,翻炒均匀即可。"
                    }
                }
            ]
        },
        "usage": {
            "input_tokens": 12,
            "output_tokens": 98,
            "total_tokens": 110
        }
    }
  • 发起function call时的结果示例:

    {
        "status_code": 200,
        "request_id": "a2b49cd7-ce21-98ff-87ac-b00cc590dc5e",
        "code": "",
        "message": "",
        "output": {
            "text": null,
            "finish_reason": null,
            "choices": [
                {
                    "finish_reason": "tool_calls",
                    "message": {
                        "role": "assistant",
                        "content": "",
                        "tool_calls":[
                            {
                                'function': {
                                    'name': 'get_current_weather',
                                    'arguments': '{"properties": {"location": "北京市"}}'
                                    },
                                'id': '',
                                'type': 'function'}]
                    }
                }
            ]
        },
        "usage": {
            "input_tokens": 12,
            "output_tokens": 98,
            "total_tokens": 110
        }
    }
  • 返回参数说明

    返回参数

    数据类型

    说明

    备注

    status_code

    integer

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

    说明

    只有Python会输出该参数,使用Java调用失败会抛出异常,异常信息为code和message的内容。

    request_id

    string

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

    code

    string

    表示错误码,调用成功时为空值。仅适用于Python。

    message

    string

    表示调用失败的详细信息,调用成功时为空值。仅适用于Python。

    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场景。

    包含三个参数:type、function和id。返回结果中给出了function_call的示例。type、function参数详情如下:

    • type,类型为string,当前只能设置为function。

    • function,类型为object,包含name和arguments两个参数:

      • name,类型为string,表示需要调用的工具的名称,如果是function call场景则表示要调用的工具函数名称。

      • arguments,类型为string,表示模型生成的要传入工具的参数。可以通过Python中的json.loads方法解析为字典。

    usage

    object

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

    usage.input_tokens

    integer

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

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

    usage.output_tokens

    integer

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

    usage.total_tokens

    integer

    usage.input_tokens与usage.output_tokens的总和

HTTP调用接口

功能描述

您可以通过HTTP调用接口来使用通义千问模型,免去安装DashScope SDK的步骤。目前提供普通HTTP和HTTP SSE两种协议,您可根据自己的需求自行选择。

前提条件

已开通服务并获得API-KEY:获取API-KEY

提交接口调用

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation

入参描述

您可以参考下表参考输入参数的配置。其中数据类型列的字段含义如下所示:

  • string表示字符串类型;

  • array表示数组;

  • integer表示整数型;

  • float表示浮点型;

  • boolean表示布尔型;

  • object表示哈希表。

传参方式

字段

数据类型

必选

描述

示例值

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

指定用于对话的通义千问模型名,目前可选择qwen-turbo、qwen-plus、qwen-max、qwen-max-0403、qwen-max-0107、qwen-max-1201和qwen-max-longcontext。

"model":"qwen-turbo"

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

角色可选值: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时,输出格式请参考返回结果。推荐优先使用message格式。

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

parameters.seed

integer

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

"parameters":{"seed":666}

parameters.max_tokens

integer

用于限制模型生成token的数量,表示生成token个数的上限。其中qwen-turbo最大值和默认值为1500,qwen-max、qwen-max-1201 、qwen-max-longcontext 和 qwen-plus最大值和默认值均为2000。

"parameters":{"max_tokens":1500}

parameters.top_p

float

生成时,核采样方法的概率阈值。例如,取值为0.8时,仅保留累计概率之和大于等于0.8的概率分布中的token,作为随机采样的候选集。取值范围为(0,1.0),取值越大,生成的随机性越高;取值越低,生成的随机性越低。默认值为0.8。注意,取值不要大于等于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表示不做惩罚,默认为1.1。没有严格的取值范围。

"parameters":{"repetition_penalty":1.0}

parameters.temperature

float

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

取值范围:[0, 2),系统默认值0.85。不建议取值为0,无意义。

"parameters":{"repetition_penalty":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.enable_search

boolean

模型内置了互联网搜索服务,该参数控制模型在生成文本时是否参考使用互联网搜索结果。取值如下:

true:启用互联网搜索,模型会将搜索结果作为文本生成过程中的参考信息,但模型会基于其内部逻辑“自行判断”是否使用互联网搜索结果。

false(默认):关闭互联网搜索。

"parameters":{"enable_search":false}

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

用于指定可供模型调用的工具列表。当输入多个工具时,模型会选择其中一个生成结果。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参数。当前支持的模型包括qwen-turbo、qwen-plus、qwen-max和qwen-max-longcontext。

说明

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

"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两个参数,参考代码中给出了function_call的示例。参数详情如下::

  • 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 个数。在enable_search设置为true时,输入的 token 数目由于需要添加搜索相关内容,因此会比您在请求中的输入 token 个数多。

633

usage.total_tokens

integer

usage.output_tokens与usage.input_tokens的总和。

1013

request_id

string

本次请求的系统唯一码。

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

请求示例(SSE 关闭)

以下示例展示通过CURL命令来调用通义千问模型的脚本(SSE 关闭)。

说明

您需要使用API-KEY替换示例中的 $your-dashscope-api-key。

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \
--header 'Authorization: Bearer $your-dashscope-api-key' \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen-turbo",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "你好,哪个公园距离我最近?"
            }
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}'
import requests

url = 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation'
headers = {'Content-Type': 'application/json',
           'Authorization':'Bearer $your-dashscope-api-key'}
body = {
    'model': 'qwen-turbo',
    "input":{
    "messages":[
    {
    "role": "system",
    "content": "You are a helpful assistant."
    },
    {
    "role": "user",
    "content": "你好,哪个公园距离我最近?"
    }]
    },
    
}

response = requests.post(url, headers=headers, json=body)
print(response.text)

响应示例(SSE关闭)

result_format参数为text的时候的输出结果

{
    "output":{
        "text":"如果你在中国,我推荐你去北京的颐和园 ... ... 适合散步和欣赏景色。",
        "finish_reason":"stop"    
    },
    "usage":{
        "output_tokens":380,
        "input_tokens":633
    },
    "request_id":"d89c06fb-46a1-47b6-acb9-bfb17f814969"
}

result_format参数为message的时候的输出结果

{
    "output":{
        "text":"如果你在中国,我推荐你去北京的颐和园 ... ... 适合散步和欣赏景色。",
        "finish_reason":"stop"    
    },
    "usage":{
        "output_tokens":380,
        "input_tokens":633
    },
    "request_id":"d89c06fb-46a1-47b6-acb9-bfb17f814969"
}

使用function_call时的输出结果

{
    "status_code": 200,
    "request_id": "a2b49cd7-ce21-98ff-87ac-b00cc590dc5e",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "tool_calls",
                "message": {
                    "role": "assistant",
                    "content": "",
                    "tool_calls":[
                        {
                            'function': {
                                'name': 'get_current_weather',
                                'arguments': '{"properties": {"location": "北京市"}}'
                                },
                            'id': '',
                            'type': 'function'}]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 12,
        "output_tokens": 98,
        "total_tokens": 110
    }
}

请求示例(SSE开启

以下示例展示通过curl命令或Python脚本来调用通义千问模型(SSE 开启),可实现类似于流式输出的效果。

说明

需要使用您的API-KEY替换示例中的 $your-dashscope-api-key ,代码才能正常运行。

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \
--header 'Authorization: Bearer $your-dashscope-api-key' \
--header 'Content-Type: application/json' \
--header 'X-DashScope-SSE: enable' \
--data '{
    "model": "qwen-turbo",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "你好,哪个公园距离我最近?"
            }
        ]
    },
    "parameters": {
        "result_format": "message",
        "incremental_output":true
    }
}'
import requests

url = 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation'
headers = {'Content-Type': 'application/json',
           'Authorization':'Bearer $your-dashscope-api-key',
           'X-DashScope-SSE': 'enable'}
body = {
    'model': 'qwen-turbo',
    "input":{
    "messages":[
    {
    "role": "system",
    "content": "You are a helpful assistant."
    },
    {
    "role": "user",
    "content": "你好"
    }]
    },
    'parameters':{'incremental_output':True}
    
}

response = requests.post(url, headers=headers, json=body)
print(response.text)

响应示例(SSE开启)

id:1
event:result
:HTTP_STATUS/200
data:{"output":{"finish_reason":"null","text":"你好"},"usage":{"total_tokens":21,"input_tokens":20,"output_tokens":1},"request_id":"fad8f7ee-5bf5-900f-a482-f8a683f704d6"}

id:2
event:result
:HTTP_STATUS/200
data:{"output":{"finish_reason":"null","text":"!"},"usage":{"total_tokens":22,"input_tokens":20,"output_tokens":2},"request_id":"fad8f7ee-5bf5-900f-a482-f8a683f704d6"}

... ... ... ...
... ... ... ...

id:5
event:result
:HTTP_STATUS/200
data:{"output":{"finish_reason":"stop","text":""},"usage":{"total_tokens":27,"input_tokens":20,"output_tokens":7},"request_id":"fad8f7ee-5bf5-900f-a482-f8a683f704d6"}

异常响应示例

在访问请求出错的情况下,输出的结果中会通过 code 和 message 指明错误原因。

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

状态码说明

大模型服务平台通用状态码详情,请参见状态码说明

  • 本页导读 (1)
文档反馈