文档

API详情

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

如果您熟悉编程语言,推荐您使用SDK或API调用通义千问模型,实现灵活定制和开发。

通义千问

说明

支持的领域/任务:aigc

重要

通义千问2.1(qwen-max千亿级别模型)API限时免费开放中。

通义千问模型支持用户以文本形式的指令(prompt)以及不定轮次的对话历史(history)作为输入,并基于这些信息生成回复作为输出。在这一过程中,文本将被转换为语言模型可以处理的token序列。Token是模型用来表示自然语言文本的基本单位,可以直观地理解为“字”或“词”。对于中文文本来说,1个token通常对应一个汉字;对于英文文本来说,1个token通常对应3至4个字母或1个单词。例如,中文文本“你好,我是通义千问”会被转换成序列['你', '好', ',', '我', '是', '通', '义', '千', '问'],而英文文本"Nice to meet you."则会被转换成['Nice', ' to', ' meet', ' you', '.']。

由于模型调用的计算量与token序列长度相关,输入或输出token数量越多,模型的计算时间越长,我们将根据模型输入和输出的token数量计费。可以从API返回结果的usage字段中了解到您每次调用时使用的token数量。您也可以使用Token计算器或者调用Token计算API来预估文本对应的token数量。

模型概览

模型名称

模型简介

模型输入/输出限制

qwen-turbo

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

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

qwen-plus

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

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

qwen-max

(限时免费开放中)

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

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

qwen-max-1201

(限时免费开放中)

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

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

qwen-max-longcontext

(限时免费开放中)

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

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

说明

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

SDK使用

前提条件

单轮问答

以下示例展示了调用通义千问模型对一个用户指令进行响应的代码。

说明

需要使用您的API-KEY替换示例中的 YOUR_DASHSCOPE_API_KEY

同时满足:

python sdk version: dashscope>=1.10.0

java sdk version: >=2.5.0

代码才能正常运行

警告

java sdk 为了效率您应该尽可能复用Generation以及其他请求对象,但对象(如Generation)不是线程安全的,您应该采取一定的措施,确保对象安全。

API-KEY设置

export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

通过messages调用

import random
from http import HTTPStatus
import dashscope


def call_with_messages():
    messages = [{'role': 'system', 'content': 'You are a helpful assistant.'},
                {'role': 'user', 'content': '如何做西红柿炒鸡蛋?'}]
    response = dashscope.Generation.call(
        dashscope.Generation.Models.qwen_turbo,
        messages=messages,
        # set the random seed, optional, default to 1234 if not set
        seed=random.randint(1, 10000),
        result_format='message',  # set the result to be "message" format.
    )
    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.

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.MessageManager;
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();
    MessageManager msgManager = new MessageManager(10);
    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();
    msgManager.add(systemMsg);
    msgManager.add(userMsg);
    QwenParam param =
        QwenParam.builder().model(Generation.Models.QWEN_PLUS).messages(msgManager.get())
            .resultFormat(QwenParam.ResultFormat.MESSAGE)
            .topP(0.8)
            .enableSearch(true)
            .build();
    GenerationResult result = gen.call(param);
    System.out.println(result);
    msgManager.add(result);
    System.out.println(JsonUtils.toJson(result));
    param.setPrompt("找个近点的");
    param.setMessages(msgManager.get());
    result = gen.call(param);
    System.out.println(result);
    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);
  }
}

通过prompt调用

# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/611472.html
from http import HTTPStatus
import dashscope
def call_with_prompt():
    response = dashscope.Generation.call(
        model=dashscope.Generation.Models.qwen_turbo,
        prompt='如何做炒西红柿鸡蛋?'
    )
    # The response status_code is HTTPStatus.OK indicate success,
    # otherwise indicate request is failed, you can get error code
    # and message from code and message.
    if response.status_code == HTTPStatus.OK:
        print(response.output)  # The output text
        print(response.usage)  # The usage information
    else:
        print(response.code)  # The error code.
        print(response.message)  # The error message.

if __name__ == '__main__':
    call_with_prompt()
// Copyright (c) Alibaba, Inc. and its affiliates.

import java.util.concurrent.Semaphore;
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.ResultCallback;
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 {
  private final static String PROMPT = "如何做西红柿炖牛腩?";
  public static void qwenQuickStart()
      throws NoApiKeyException, ApiException, InputRequiredException {
    Generation gen = new Generation();
    QwenParam param = QwenParam.builder().model(Generation.Models.QWEN_TURBO).prompt(PROMPT)
        .topP(0.8).build();
    GenerationResult result = gen.call(param);
    System.out.println(JsonUtils.toJson(result));
  }

  public static void qwenQuickStartCallback()
      throws NoApiKeyException, ApiException, InputRequiredException, InterruptedException {
    Generation gen = new Generation();
    QwenParam param = QwenParam.builder().model(Generation.Models.QWEN_TURBO).prompt(PROMPT)
        .topP(0.8).build();
    Semaphore semaphore = new Semaphore(0);
    gen.call(param, new ResultCallback<GenerationResult>() {

      @Override
      public void onEvent(GenerationResult message) {
        System.out.println(message);
      }
      @Override
      public void onError(Exception ex){
        System.out.println(ex.getMessage());
        semaphore.release();
      }
      @Override
      public void onComplete(){
        System.out.println("onComplete");
        semaphore.release();
      }
      
    });
    semaphore.acquire();
  }

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

多轮会话

通过messages调用

from http import HTTPStatus
from dashscope import Generation
from dashscope.api_entities.dashscope_response import Role


def conversation_with_messages():
    messages = [{'role': Role.SYSTEM, 'content': 'You are a helpful assistant.'},
                {'role': Role.USER, 'content': '如何做西红柿炖牛腩?'}]
    response = Generation.call(
        Generation.Models.qwen_turbo,
        messages=messages,
        result_format='message',  # set the result to be "message" format.
    )
    if response.status_code == HTTPStatus.OK:
        print(response)
        # append result to 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
        ))
    messages.append({'role': Role.USER, 'content': '不放糖可以吗?'})
    # make second round call
    response = Generation.call(
        Generation.Models.qwen_turbo,
        messages=messages,
        result_format='message',  # set the result to be "message" format.
    )
    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__':
    conversation_with_messages()
// Copyright (c) Alibaba, Inc. and its affiliates.

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.MessageManager;
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();
    MessageManager msgManager = new MessageManager(10);
    Message systemMsg =
        Message.builder().role(Role.SYSTEM.getValue()).content("你是智能助手机器人").build();
    Message userMsg = Message.builder().role(Role.USER.getValue()).content("如何做西红柿炖牛腩?").build();
    msgManager.add(systemMsg);
    msgManager.add(userMsg);
    QwenParam param =
        QwenParam.builder().model(Generation.Models.QWEN_PLUS).messages(msgManager.get())
            .resultFormat(QwenParam.ResultFormat.MESSAGE)
            .topP(0.8)
            .enableSearch(true)
            .build();
    GenerationResult result = gen.call(param);
    System.out.println(result);
    msgManager.add(result);
    System.out.println(JsonUtils.toJson(result));
    param.setPrompt("不放糖可以吗?");
    param.setMessages(msgManager.get());
    result = gen.call(param);
    System.out.println(result);
    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);
  }
}

流式输出

流式输出需要添加对应参数。其中,Python SDK中需要添加stream=True,Java SDK中需要使用streamCall接口调用。

from http import HTTPStatus
from dashscope import Generation


def call_with_stream():
    messages = [
        {'role': 'user', 'content': '如何做西红柿炖牛腩?'}]
    responses = Generation.call(
        Generation.Models.qwen_turbo,
        messages=messages,
        result_format='message',  # set the result to be "message" format.
        stream=True,
        incremental_output=True  # get streaming output incrementally
    )
    full_content = ''  # with incrementally we need to merge output.
    for response in responses:
        if response.status_code == HTTPStatus.OK:
            full_content += response.output.choices[0]['message']['content']
            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
            ))
    print('Full response:\n' + full_content)


if __name__ == '__main__':
    call_with_stream()

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

import java.util.Arrays;
import java.util.concurrent.Semaphore;
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.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 {
  public static void streamCallWithMessage()
      throws NoApiKeyException, ApiException, InputRequiredException {
    Generation gen = new Generation();
    Message userMsg = Message
    .builder()
    .role(Role.USER.getValue())
    .content("如何做西红柿炖牛腩?")
    .build();
    QwenParam param =
        QwenParam.builder().model(Generation.Models.QWEN_PLUS).messages(Arrays.asList(userMsg))
            .resultFormat(QwenParam.ResultFormat.MESSAGE)
            .topP(0.8)
            .enableSearch(true)
            .incrementalOutput(true) // get streaming output incrementally
            .build();
    Flowable<GenerationResult> result = gen.streamCall(param);
    StringBuilder fullContent = new StringBuilder();
    result.blockingForEach(message -> {
      fullContent.append(message.getOutput().getChoices().get(0).getMessage().getContent());
      System.out.println(JsonUtils.toJson(message));
    });
    System.out.println("Full content: \n" + fullContent.toString());
  }

  public static void streamCallWithCallback()
      throws NoApiKeyException, ApiException, InputRequiredException,InterruptedException {
    Generation gen = new Generation();
    Message userMsg = Message
    .builder()
    .role(Role.USER.getValue())
    .content("如何做西红柿炖牛腩?")
    .build();
    QwenParam param = QwenParam
    .builder()
    .model(Generation.Models.QWEN_PLUS)
    .resultFormat(QwenParam.ResultFormat.MESSAGE)
    .messages(Arrays.asList(userMsg))
    .topP(0.8)
    .incrementalOutput(true) // get streaming output incrementally
    .build();
    Semaphore semaphore = new Semaphore(0);
    StringBuilder fullContent = new StringBuilder();
    gen.streamCall(param, new ResultCallback<GenerationResult>() {

      @Override
      public void onEvent(GenerationResult message) {
        fullContent.append(message.getOutput().getChoices().get(0).getMessage().getContent());
        System.out.println(message);
      }
      @Override
      public void onError(Exception err){
        System.out.println(String.format("Exception: %s", err.getMessage()));
        semaphore.release();
      }

      @Override
      public void onComplete(){
        System.out.println("Completed");
        semaphore.release();
      }
      
    });
    semaphore.acquire();
    System.out.println("Full content: \n" + fullContent.toString());
  }
  public static void main(String[] args) {
    try {
      streamCallWithMessage();
    } catch (ApiException | NoApiKeyException | InputRequiredException e) {
      System.out.println(e.getMessage());
    }
    try {
      streamCallWithCallback();
    } catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
      System.out.println(e.getMessage());
    }
    System.exit(0);
  }
}
  • 字符串与token之间的互相转换(Tokenizer)

您可以通过Python SDK中的Tokenizer来直接在本地统计千问模型的token数据,包括将字符串(string)转换到token id列表,以及反向地将token id列表转回字符串。

重要

使用Python SDK进行本地token解析,需要额外安装Tokenizer依赖

# dashscope>=1.14.0
pip install -U dashscope
pip install dashscope[tokenizer]

字符串和token id互相转换

from dashscope import get_tokenizer
# 获取Tokenizer,目前只支持千问系列模型
tokenizer = get_tokenizer('qwen-turbo')

input_str = 'You are a helpful assistant.'

# convert string to token ids
tokens = tokenizer.encode(input_str)
print(tokens)
print('There are %s tokens' % len(tokens))

# convert token ids to string
decoded_str = tokenizer.decode(tokens)
print(decoded_str)

有关通义千问Tokenization参考链接

输入参数配置

参数

类型

默认值

说明

model

string

-

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

说明

qwen-max-1201qwen-max-longcontext在当前SDK版本中未定义,您可以通过入参形式输入模型名称字符串进行调用。

例如,python:model='qwen-max-longcontext'

java:.model("qwen-turbo")

messages

array

-

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

    • system:表示系统级消息,只能用于对话历史的第一条(messages[0])。使用system角色是可选的,如果存在,必须位于列表的最开始。

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

  • prompt:用户当前输入的期望模型执行指令,用于指导模型生成回复。

说明

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

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

prompt

string

-

history (可选)

list[dict]

[]

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

seed (可选)

int

1234

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

max_tokens(可选)

int

1500

用于指定模型在生成内容时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 (可选)

int

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,无意义。

python version >=1.10.1

java version >= 2.5.1

stop (可选)

str/list[str]用于指定字符串;list[int]/list[list[int]]用于指定token_ids

None

  • stop参数用于实现内容生成过程的精确控制,在生成内容即将包含指定的字符串或token_ids时自动停止,生成内容不包含指定的内容。

    例如,如果指定stop为"你好",表示将要生成"你好"时停止;如果指定stop为[37763, 367],表示将要生成"Observation"时停止。

  • stop参数支持以list方式传入字符串数组或者token_ids数组,支持使用多个stop的场景。

    说明

    list模式下不支持字符串和token_ids混用,list模式下元素类型要相同。

stream (可选)

bool

False

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

enable_search (可选)

bool

False

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

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

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

result_format (可选)

string

text

[text|message],默认为text,当为message时,输出参考message结果示例。推荐优先使用message格式。

incremental_output (可选)

bool

False

控制流式输出模式,即后面内容会包含已经输出的内容;设置为True,将开启增量输出模式,后面输出不会包含已经输出的内容,您需要自行拼接整体输出,参考流式输出示例代码。

默认False:

I

I like

i like apple

True:

I

like

apple

该参数只能与stream输出模式配合使用。

返回结果

  • 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
        }
    }
  • prompt结果示例

    {
        "status_code": 200,
        "request_id": "e3472c22-274a-9551-b197-f6510608fe1b",
        "code": "",
        "message": "",
        "output": {
            "text": "材料:\n西红柿2个,鸡蛋3个,葱花适量,盐适量,糖适量,食用油适量\n\n做法:\n1. 西红柿洗净切块,鸡蛋打入碗中搅拌均匀备用。\n2. 热锅凉油,油热后加入葱花爆香。\n3. 加入西红柿块翻炒,炒至西红柿出汁。\n4. 加入适量的盐和糖,继续翻炒均匀。\n5. 倒入鸡蛋液,用铲子快速翻炒均匀,使鸡蛋液均匀地裹在西红柿上。\n6. 炒至鸡蛋熟透即可出锅。\n\n提示:\n1. 炒西红柿时可以适当加一些水,可以使西红柿更加鲜美。\n2. 炒鸡蛋时要快速翻炒,使鸡蛋均匀地裹在西红柿上,避免炒糊。\n3. 可以根据个人口味调整盐和糖的用量。",
            "finish_reason": "stop",
            "choices": null
        },
        "usage": {
            "input_tokens": 6,
            "output_tokens": 193,
            "total_tokens": 199
        }
    }

  • 返回参数说明

    返回参数

    类型

    说明

    备注

    status_code

    int

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

    说明

    Python才有这个字段,Java失败会抛异常,异常信息为code,message内容。

    request_Id

    string

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

    code

    string

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

    python only

    message

    string

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

    python only

    output

    dict

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

    usage

    dict

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

    output.text

    string

    模型生成回复。

    output.finish_reason

    string

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

    usage.input_tokens

    int

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

    参考sdk提供的本地tokenizer统计token数据。

    usage.output_tokens

    int

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

    choices

    List

    []

    当result_format为message输出choices

    choices[i].finish_reason

    String

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

    当result_format为message输出choices

    choices[i].message

    dict

    模型生成消息输出

    当result_format为message输出choices

    message.role

    String

    模型role,固定为assistant

    message.content

    String

    模型生成的文本

HTTP调用接口

功能描述

通义千问模型同时支持 HTTP 调用来完成客户的响应,目前提供普通 HTTP 和 HTTP SSE 两种协议,您可根据自己的需求自行选择。

前提条件

已开通服务并获得API-KEY:开通DashScope并创建API-KEY

提交接口调用

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

入参描述

传参方式

字段

类型

必选

描述

示例值

Header

Content-Type

String

请求类型:application/json

application/json

Accept

String

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

text/event-stream

Authorization

String

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

Bearer d1**2a

X-DashScope-SSE

String

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

enable

Body

model

String

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

说明

qwen-max-1201qwen-max-longcontext在当前SDK版本中未定义,您可以通过入参形式输入模型名称字符串进行调用。

例如,python:model='qwen-max-longcontext'

java:.model("qwen-turbo")

qwen-turbo

input.prompt

String

用户当前输入的期望模型执行指令,支持中英文。

哪个公园距离我更近

input.history

List

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

"history": [

{

"user":"今天天气好吗?",

"bot":"今天天气不错,要出去玩玩嘛?"

},

{

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

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

}

]

input.messages

List

用户与模型的对话历史,对话接口未来都会有message传输,不过prompt和history会持续兼容,list中的每个元素形式为{"role":角色, "content": 内容}。角色当前可选值:systemuserassistant。未来可以扩展到更多role。

"input":{

"messages":[

{

"role": "system",

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

},

{

"role": "user",

"content": "你好,附近哪里有博物馆?"

}]

}

input.messages.role

String

message存在的时候不能缺省

input.messages.content

String

parameters.result_format

String

"text"表示旧版本的text

"message"表示兼容openai的message

"text"

parameters.seed

Integer

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

65535

parameters.max_tokens

Integer

用于限制模型生成token的数量,max_tokens设置的是生成上限,并不表示一定会生成这么多的token数量。其中qwen-turbo 最大值和默认值为1500, qwen-max、qwen-max-1201 、qwen-max-longcontext 和 qwen-plus最大值和默认值均为2000。

1500

parameters.top_p

Float

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

0.8

parameters.top_k

Integer

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

50

parameters.repetition_penalty

Float

用于控制模型生成时的重复度。提高repetition_penalty时可以降低模型生成的重复度。1.0表示不做惩罚。默认为1.1。

1.1

parameters.temperature

Float

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

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

0.85

parameters.stop

String/List[String]用于指定字符串;List[Integer]/List[List[Integer]]用于指定token_ids

  • stop参数用于实现内容生成过程的精确控制,在生成内容即将包含指定的字符串或token_ids时自动停止,生成内容不包含指定的内容。

    例如,如果指定stop为"你好",表示将要生成"你好"时停止;如果指定stop为[37763, 367],表示将要生成"Observation"时停止。

  • stop参数支持以list方式传入字符串数组或者token_ids数组,支持使用多个stop的场景。

    说明

    list模式下不支持字符串和token_ids混用,list模式下元素类型要相同。

[[37763, 367]]

parameters.enable_search

Bool

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

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

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

true 或者 false

parameters.incremental_output

Bool

用于控制流式输出模式,默认False,即后面内容会包含已经输出的内容;设置为True,将开启增量输出模式,后面输出不会包含已经输出的内容,您需要自行拼接整体输出,参考流式输出示例代码。

默认False:

I

I like

i like apple

True:

I

like

apple

该参数只能与stream输出模式配合使用。

出参描述

字段

类型

输出格式

描述

示例值

output.text

String

入参result_format=text时候的返回值

包含本次请求的算法输出内容。

我建议你去颐和园

output.finish_reason

String

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

stop

output.choise[list]

List

入参result_format=message时候的返回值

入参result_format=message时候的返回值

"choices": [

{

"finish_reason":"null",

"message": {

"role": "bot",

"content": "周围的咖啡馆在...",

}

]

output.choise[x].finish_reason

String

停止原因,null:生成过程中

stop:stop token导致结束

length:生成长度导致结束

output.choise[x].message

String

message每个元素形式为{"role":角色, "content": 内容}。角色按当前可选值:systemuserassistant。未来可以扩展到更多role,content则包含本次请求算法输出的内容。

output.choise[x].message.role

String

output.choise[x].message.content

String

usage.output_tokens

Integer

通用

本次请求算法输出内容的 token 数目。

380

usage.input_tokens

Integer

本次请求输入内容的 token 数目。在打开了搜索的情况下,输入的 token 数目因为还需要添加搜索相关内容支持,所以会超出客户在请求中的输入。

633

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": {
    }
}'

响应示例(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":{
        "choices": [
        	{
            	"finish_reason":"stop",
            	"message": {
              		"role": "system",
                	"content": "如果你在中国,我推荐你去北京的颐和园 ... ... 适合散步和欣赏景色。",
            	}
        }
        ]
        "finish_reason":"stop"    
    },
    "usage":{
        "output_tokens":380,
        "input_tokens":633
    },
    "request_id":"d89c06fb-46a1-47b6-acb9-bfb17f814969"
}

请求示例(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' \
--header 'X-DashScope-SSE: enable' \
--data '{
    "model": "qwen-turbo",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "你好,哪个公园距离我最近?"
            }
        ]
    },
    "parameters": {
    }
}'

响应示例(SSE开启)

id:1
event:result
data:{"output":{"finish_reason":"null","text":"最近"},"usage":{"output_tokens":3,"input_tokens":85},"request_id":"1117fb64-5dd9-9df0-a5ca-d7ee0e97032d"}

id:2
event:result
data:{"output":{"finish_reason":"null","text":"最近的公园是公园,它"},"usage":{"output_tokens":11,"input_tokens":85},"request_id":"1117fb64-5dd9-9df0-a5ca-d7ee0e97032d"}

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

id:8
event:result
data:{"output":{"finish_reason":"stop","text":"最近的公园是公园,它距离你的家大约1.5公里。你可以使用Google地图或者百度地图来查看具体的路线和距离。"},"usage":{"output_tokens":51,"input_tokens":85},"request_id":"1117fb64-5dd9-9df0-a5ca-d7ee0e97032d"}

异常响应示例

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

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

状态码说明

DashScope灵积模型服务通用状态码详情,请参见返回状态码说明

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