阿里AI通义千问api python开发文档

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

您可以使用SDK或API调用通义千问模型，根据您的需求实现灵活的定制和开发。

通义千问

说明

支持的领域/任务：aigc

通义千问大语言模型以用户文本形式的指令（prompt）以及不定轮次的对话消息作为输入，并基于这些信息生成回复作为输出。在这一过程中，文本将被转换为语言模型可以处理的token序列。Token是模型用来表示自然语言文本的基本单位，可以直观地理解为“字”或“词”。对于中文，一个token平均对应1.8到2个汉字，例如“通义千问大语言模型”，转换成token后为： ["通", "义", "千", "问", "大", "语言", "模型"], 对于英文，通常一个token对应3到4个字母或者一个单词，例如：Artificial intelligence has made great progress at present. 转换成为token后为： ["Art", "ificial", " intelligence", " has", " made", " great", " progress", " at", " present", "."]。

由于模型以token为单位进行计算，所以在计量上以token个数为单位，单次请求的token数与输入和输出的长度相关。具体计量信息，可以从API返回结果的usage字段中查看您每次调用使用的token数量。

Token计算API是帮助用户估算指定文本对应多少Token数目的API。在灵积平台中，包括通义千问、LLaMa2等在内的语言模型都是基于用户输入和输出的token数目来进行计量和计费的。在语言模型使用中，字符数目和Token数目并不一定是一一对应的，例如在通义千问开源7B模型中：

• "苹果"对应1个token；
• "my friends"对应3个token；
• " 周"对应3个token。

故而，灵积平台提供Token计算API供用户参考。

模型概览

您可以通过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。

说明

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

重要

每种模型都有不同的限流条件，在您调用前建议查看基础限流了解您所使用模型的限流条件，并制定适合的调用策略，以免在调用时达到限流条件而报错。

SDK使用

前提条件

• 已开通服务并获得API-KEY：开通DashScope并创建API-KEY。
• 已安装最新版SDK：安装DashScope SDK。
• 我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄漏风险，详情可参考通过环境变量配置API-KEY。您也可以在代码中配置API-KEY，但是泄漏风险会提高。

说明

您的SDK版本应该满足：

DashScope Python SDK Version >= 1.14.0

DashScope Java SDK Version >= 2.5.0

重要

在调用SDK时，您可以查看输入参数配置来了解输入参数的详情。

警告

当您使用DashScope Java SDK时，为了效率您应该尽可能复用Generation以及其他请求对象，但对象（如Generation）不是线程安全的，您应该采取一定的措施，确保对象安全。

单轮对话

您可以运行以下示例代码，体验通义千问模型的单轮对话能力。

Python示例代码

import random
from http import HTTPStatus
from dashscope import Generation


def call_with_messages():
    messages = [{'role': 'system', 'content': 'You are a helpful assistant.'},
                {'role': 'user', 'content': '如何做西红柿炒鸡蛋？'}]
    response = Generation.call("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()

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

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

多轮对话

您可以运行以下示例代码，体验通义千问模型的多轮对话能力。

Python示例代码

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("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("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()

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

{"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("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')

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

流式输出

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

Python示例代码

from http import HTTPStatus
from dashscope import Generation

def call_with_stream():
    messages = [
        {'role': 'user', 'content': '如何做西红柿炖牛腩？'}]
    responses = Generation.call("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()

流式输出效果如下图所示：

Function call

Function call功能可以使用工具对模型的输出提供辅助信息。使用function call功能需要添加对应参数。在调用DashScope Python SDK时需要您在调用函数中添加tools, DashScope Java SDK Version>=2.12.0开始支持tools。

重要

function call信息暂时不支持增量输出。

单轮调用

您可以为模型配置多个工具，查看输入不同指令时模型选择工具的能力。您需要准备工具tools，工具tools的格式请参考输入参数配置中的tools参数。

您可以通过运行以下示例代码来查看模型面对不同指令时选择工具的能力。

Python

import json
from dashscope import Generation
from datetime import datetime

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


def call_with_messages():
    # 此处的content是用户的问题
    messages = [
            {
                "content": "现在几点了？", # 您也可以用"北京天气怎么样？"进行测试
                "role": "user"
            }]

    response = Generation.call(
            model='qwen-turbo',
            messages=messages,
            tools=tools,
            seed=random.randint(1, 10000),  # 设置随机数种子seed，如果没有设置，则随机数种子默认为1234
            result_format='message' # 将输出设置为message形式
        )
    print(response.output.choices[0].message['tool_calls'][0])

if __name__ == '__main__':
    call_with_messages()

当您输入问题“现在几点了？”时，工具name为“get_current_time”，输入工具的参数arguments为空；当您输入问题"北京天气怎么样？"时，工具name为"get_current_weather"，arguments中的location为"北京市"，符合tools定义的参数格式。

多轮调用

单轮调用展示了模型选择工具的能力，多轮调用可以展示模型对工具输出结果的总结能力。

重要

在提交工具输出结果时，仍然需要配置tools参数。

Python

from dashscope import Generation
from datetime import datetime

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

# 模拟天气查询工具
def get_current_weather(location):
    return f"{location}今天是晴天。 "

# 查询当前时间的工具
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": "杭州市的天气", # 您也可以提问"现在几点了？"
                "role": "user"
            }
    ]
    
    # 模型的第一轮调用
    assistant_output= get_response(messages).output.choices[0].message
    messages.append(assistant_output)
    # 如果模型选择的工具是get_current_weather
    if 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(response.output.choices[0].message['content'])

if __name__ == '__main__':
    call_with_messages()

通过运行以上代码，您可以得到在工具辅助条件下模型的输出结果。

字符串与token之间的互相转换

不同的大模型对相同的一句话分词的结果可能不同。您可以使用DashScope Python SDK在本地查看经过通义千问模型分词后的token数据，包括将字符串（string）转换到token id列表，以及反向地将token id转回对应的字符串。

重要

若您的DashScope Python SDK版本较低，请运行以下命令进行更新。

pip install -U dashscope

需要Dashscope Java SDK Version >=2.13.0

本地运行的Tokenizer用于估计文本token量，绝对值和结果不保证与模型服务端完全一致，仅供参考。

您可以运行以下代码查看经过通义千问模型分词后的token id，以及token id转化为字符串的结果。

Python

from dashscope import get_tokenizer

# 获取tokenizer对象，目前只支持通义千问系列模型
tokenizer = get_tokenizer('qwen-turbo')

input_str = 'You are a helpful assistant.'

# 将字符串切分成token并转换为token id
tokens = tokenizer.encode(input_str)
print(f"经过分词后的token id为：{tokens}。")
print(f"经过分词后共有{len(tokens)}个token")

# 将token id转化为字符串并打印出来
for i in range(len(tokens)):
    print(f"token id为{tokens[i]}对应的字符串为：{tokenizer.decode(tokens[i])}")

输入参数配置

在您调用SDK中的响应函数时，您可以查看下表来了解输入参数的配置方式。

 

参数	类型	默认值	说明
model	string	-	指定用于对话的通义千问模型名，目前可选择qwen-turbo、qwen-plus、qwen-max、qwen-max-0403、qwen-max-0107、qwen-max-1201和qwen-max-longcontext。 说明 qwen-max-0403、qwen-max-0107、qwen-max-1201、qwen-max-longcontext在当前SDK版本中未定义，您可以通过指定model为模型名称字符串来进行调用。 例如：Python：model='qwen-max-longcontext' Java：.model("qwen-max-0403")
messages	array	-	messages：用户与模型的对话历史。list中的每个元素形式为{"role":角色, "content": 内容}，角色当前可选值：system、user、assistant和tool。 system：表示系统级消息，只能位于对话历史的第一条（messages[0]）。是否使用system角色是可选的，如果使用则必须位于列表的最开始。 user和assistant：表示用户和模型的消息。它们应交替出现在对话中，模拟实际对话流程。 tool：在使用function_call功能时，如果要传入function的结果，需将message的形式设为{"content":"工具返回的结果", "name":"工具的函数名", "role":"tool"}。其中name是function的名称，需要和上轮response中的tool_calls[i]['function']['name']参数保持一致；content为function的输出。参考代码中的多轮调用给出了示例。 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-max、qwen-max-1201、qwen-max-longcontext和qwen-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，无意义。
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混用，元素类型要相同。
stream (可选）	bool	False	是否使用流式输出。当以stream模式输出结果时，接口返回结果为generator，需要通过迭代获取结果，默认每次输出为当前生成的整个序列，最后一次输出为最终全部生成结果，可以通过参数incremental_output为False改变输出模式为非增量输出。
enable_search (可选）	bool	False	模型内置了互联网搜索服务，该参数控制模型在生成文本时是否参考使用互联网搜索结果。取值如下： True：启用互联网搜索，模型会将搜索结果作为文本生成过程中的参考信息，但模型会基于其内部逻辑判断是否使用互联网搜索结果。 False（默认）：关闭互联网搜索。
result_format (可选）	string	text	[text|message],默认为text，当设置为message时，输出格式请参考返回结果。推荐优先使用message格式。
incremental_output (可选）	bool	False	控制流式输出模式；即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。您可以参考流式输出代码。 默认False： I I like i like apple True: I like apple 该参数只能在stream为True时使用。 重要 incremental_output暂时无法和tools参数同时使用。
tools	list[dict]	None	模型可选调用的工具列表。目前仅支持function。当输入多个function时，模型会选择其中一个生成结果。模型根据tools参数内容可以生产函数调用的参数。tools中每一个tool的结构如下： type，类型为string，表示tools的类型，当前仅支持function。 function，类型为dict，键值包括name，description和parameters： name，类型为string，表示function的名称，必须是字母、数字，或包含下划线和短划线，最大长度为64。 description，类型为string，表示function的描述，供模型选择何时以及如何调用function。 parameters，类型为dict，表示function的参数描述，需要是一个合法的json schema。json schema的描述可以见链接。参考代码中给出了一个参数描述的示例。如果parameters参数为空，表示function没有入参。 使用tools功能时需要指定result_format为message。在多轮对话中，无论是发起function_call的轮次，还是向模型提交function的执行结果，均请设置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
    }
}

• 当您指定tools时的function call结果示例

{
    "status_code": 200,
    "request_id": "d4080508-602e-9ecf-801c-508676cad0a3",
    "code": "",
    "message": "",
    "output": {
        "choices": [
            {
                "finish_reason": "tool_calls",
                "message": {
                    "role": "assistant",
                    "content": "",
                    "tool_calls": [
                        {
                            "function": {
                                "name": "get_current_weather",
                                "arguments": "{\"location\": \"Boston\", \"unit\": \"fahrenheit\"}"
                            },
                            "type": "function"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 8,
        "output_tokens": 30,
        "total_tokens": 38
    }
}

• 返回参数说明

返回参数	类型	说明	备注
status_code	int	200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。 说明 只有Python有这个字段，Java失败会抛出异常，异常信息为code，message内容。
request_Id	string	系统生成的标志本次调用的id。
code	string	表示错误码，成功时为空值。仅适用于Python。
message	string	表示调用失败的详细信息，成功时为空值。仅适用于Python。
output	dict	调用结果信息，对于通义千问模型，包含输出text。
usage	dict	计量信息，表示本次请求所消耗的计量数据。
output.text	string	模型生成回复，仅在使用prompt参数而不是messages参数调用时不为空，过时的格式。
output.finish_reason	string	有四种情况：正在生成时为null，生成结束时如果由于停止token导致则为stop，如果因为生成长度过长导致则为length，如果因为发生工具调用则为tool_calls。
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； 生成结束时如果因为生成的token过多则为length。	当result_format为message输出choices
choices[i].message	dict	模型生成消息输出	当result_format为message输出choices
message.role	string	模型role，固定为assistant
message.content	string	模型生成的文本
message.tool_calls	dict	如果模型判断需要调用工具，则会生成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解析为dict类型。

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-turbo、qwen-plus、qwen-max、qwen-max-0403、qwen-max-0107、qwen-max-1201和qwen-max-longcontext。	qwen-turbo
	input.prompt（需要您预先定义一个input字典，将prompt作为input的键值，以下字段同理）	String	是	用户当前输入的期望模型执行指令，支持中英文。	哪个公园距离我更近
	input.history	List	否	即将废弃，请使用messages字段。用户与模型的对话历史，list中的每个元素是形式为{"user":"用户输入","bot":"模型输出"}的一轮对话，多轮对话按时间正序排列。	"history": [ { "user":"今天天气好吗？", "bot":"今天天气不错，要出去玩玩嘛？" }, { "user":"那你有什么地方推荐？", "bot":"我建议你去公园，春天来了，花朵开了，很美丽。" } ]
	input.messages	List	否	用户与模型的对话历史，对话接口未来都会有message传输，不过prompt和history会持续兼容，list中的每个元素形式为{"role":角色, "content": 内容}。角色当前可选值：system、user、assistant和tool。未来可以扩展到更多role。	"input":{ "messages":[ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "你好，附近哪里有博物馆？" }] }
	input.messages.role	String	message存在的时候不能缺省
	input.messages.content	String
	input.messages.name	String	是	role为tool表示当前message为function_call的调用结果，name是function的名称，需要和上轮response中的tool_calls[i].function.name参数保持一致，content为function的输出。参考代码的多轮调用给出了示例。
	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混用，元素类型要相同。	[[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输出模式配合使用。 重要 incremental_output暂时无法和tools参数同时使用。
	parameters.tools	List[Json]	None	模型可选调用的工具列表。目前仅支持function，并且即使输入多个function，模型仅会选择其中一个生成结果。模型根据tools参数内容可以生产函数调用的参数，tools中每一个tool的结构如下： type，类型为string，表示tools的类型，当前仅支持function。 function，类型为dict，包括name，description和parameters： name，类型为string，表示function的名称，必须是字母、数字，或包含下划线和短划线，最大长度为64。 description，类型为string，表示function的描述，供模型选择何时以及如何调用function。 parameters，类型为dict，表示function的参数描述，需要是一个合法的json schema。json schema的描述可以见链接。参考代码中给出了一个参数描述的示例。如果parameters参数缺省了，表示function没有入参。 使用tools功能时需要指定result_format为message。在多轮对话中，无论是发起function_call的轮次，还是向模型提交function的执行结果，均请设置tools参数。当前支持qwen-turbo、qwen-plus、qwen-max和qwen-max-longcontext。 重要 tools暂时无法和incremental_output参数同时使用。	[ { "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。	stop
output.choices[list]	List	入参result_format=message时候的返回值	入参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	String		message每个元素形式为{"role":角色, "content": 内容}。角色按当前可选值：system、user、assistant。未来可以扩展到更多role，content则包含本次请求算法输出的内容。
output.choices[x].message.role	String
output.choices[x].message.content	String
output.choices[x].message.tool_calls	Json		如果模型判断需要调用工具，则会生成tool_calls参数，当前应用于function_call场景。其中包含type和function两个参数，返回结果中给出了function_call的示例。参数详情如下：： type，类型为string，当前只可能为function function，类型为dict，包含name和arguments两个参数： name，类型为string，表示需要调用的工具的名称，如果是function_call场景则表示要调用的function名称 arguments，类型为string，表示模型生成的工具入参，一般情况下可以json.loads为dict类型。
usage.output_tokens	Integer	通用	本次请求算法输出内容的 token 数目。	380
usage.input_tokens	Integer		本次请求输入内容的 token 数目。在打开了搜索的情况下，输入的 token 数目因为还需要添加搜索相关内容支持，所以会超出客户在请求中的输入。	633
request_id	String		本次请求的系统唯一码。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例（SSE 关闭）

以下示例展示如何通过CURL命令和Python脚本来调用通义千问模型（SSE 关闭）。

说明

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

Shell

Python

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

响应示例（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"
}

使用function_call的时候的输出结果

{
    "output": {
        "choices": [
            {
                "finish_reason": "tool_calls",
                "message": {
                    "role": "assistant",
                    "content": "",
                    "tool_calls": [
                        {
                            "function": {
                                "name": "get_current_weather",
                                "arguments": "{\"location\": \"Boston\", \"unit\": \"fahrenheit\"}"
                            },
                            "type": "function"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 8,
        "output_tokens": 30,
        "total_tokens": 38
    },
    "request_id": "d4080508-602e-9ecf-801c-508676cad0a3"
}

请求示例（SSE开启）

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

说明

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

Shell

Python

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

响应示例（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灵积模型服务的API调用将返回状态码以标识调用结果。通用状态码由DashScope约定，各算法模型还可能在通用状态码的基础上增加自定义的状态码和状态信息。请通过返回结果中的 code 和 status 字段定位调用成功或失败的详细信息。

下表列出DashScope通用状态码信息。各算法模型自定义的状态码信息则可在模型详情页进行查找。

重要

通义千问模型API目前处于"申请体验"阶段，请点击此处申请。

在您的账号未申请体验或申请未通过时，调用通义千问模型API将返回错误状态码。

Code	Status	可能的原因	含义说明
400	InvalidParameter	Required parameter(s) missing or invalid, please check the request parameters.(可根据实际情况修改)	接口调用参数不合法
429	Throttling	Requests throttling triggered.	接口调用触发限流
429	Throttling.RateQuota	Requests rate limit exceeded, please try again later.	调用频次触发限流，比如 QPM
429	Throttling.AllocationQuota	Allocated quota exceeded, please increase your quota limit.	一段时间调用量触发限流，比如 TPM
500	InternalError	An internal error has occured, please try again later or contact service support.(可根据实际情况修改)	内部错误
500	InternalError.Algo	An internal error has occured during execution, please try again later or contact service support.(可根据实际情况修改)	内部算法错误
400	DataInspectionFailed	Input or output data may contain sensitive content.	数据检查错误，输入或者输出包含疑似敏感内容被绿网拦截
400	BadRequest.EmptyInput	Required input parameter missing from request.	请求的输入不能为空
400	BadRequest.EmptyParameters	Required parameter "parameters" missing from request.	请求的参数不能为空
400	BadRequest.EmptyModel	Required parameter "model" missing from request.	请求输入的模型不能为空
500	SystemError	An system error has occured, please try again later.	系统错误
401	InvalidApiKey	Invalid API-key provided.	请求中的 ApiKey 错误
408	RequestTimeOut	Request timed out, please try again later.	请求超时
400	InvalidURL	Invalid URL provided in your request.	请求的 URL 错误
400	AccessDenied	Access denied.	无权访问此 API，比如不在邀测中
400	AccessDenied.Unpurchased	Access to model denied. Please make sure you are eligible for using the model.	客户没有开通此商品
400	Arrearage	Access denied, plesase make sure your account is in good standing.	客户账户因为欠费而访问被拒绝
413	BadRequest.TooLarge	Payload Too Large	接入层网关返回请求体过大错误，错误如果是由mse网关层直接拦截，则没有 code，并且 message 不能自定义。如果是restful网关拦截返回code。
500	InternalError.Timeout	An internal timeout error has occured during execution, please try again later or contact service support.	异步任务从网关提交给算法服务层之后等待时间 3 小时，如果 3 小时始终没有结果，则超时。
400	UnsupportedOperation	The operation is unsupported on the referee object.	关联的对象不支持该操作（可以根据实际情况修改）

注：http 返回码在某些特定协议之下可能不存在