阅读(1.8k) 书签 (0)

通义千问API详情

2023-07-20 11:37 更新
重要 

通义千问模型API调用需"申请体验"并通过后才可使用,否则API调用将返回错误状态码。

通义千问

说明 

支持的领域 / 任务:aigc

通义千问是阿里巴巴达摩院自主研发的超大规模语言模型,能够在用户自然语言输入的基础上,通过自然语言理解和语义分析,理解用户意图,在不同领域、任务内为用户提供服务和帮助。您可以通过提供尽可能清晰详细的指令,来获取更符合您预期的结果。

模型具备的能力包括但不限于:

  1. 创作文字,如写故事、写公文、写邮件、写剧本、写诗歌等

  2. 编写代码

  3. 提供各类语言的翻译服务,如英语、日语、法语、西班牙语等

  4. 进行文本润色和文本摘要等工作

  5. 扮演角色进行对话

  6. 制作图表

通义千问以用户以文本形式输入的指令(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数量。

模型概览

模型名

模型简介

qwen-v1

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

qwen-plus-v1

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

SDK使用

前提条件

单轮问答

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

说明 

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

API-KEY设置

export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY
Python 示例
# coding=utf-8
# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/611472.html

import dashscope
from dashscope import Generation
from http import HTTPStatus
import json

response=Generation.call(
    model='qwen-v1',
    prompt='就当前的海洋污染的情况,写一份限塑的倡议书提纲,需要有理有据地号召大家克制地使用塑料制品'
    )

if response.status_code==HTTPStatus.OK:
    print(json.dumps(response.output, indent=4, ensure_ascii=False))
else:
    print('Code: %d, status: %s, message: %s' % (response.status_code, response.code, response.message))
多轮会话

您也可以通过history参数传入对话历史,以达到与模型进行多轮交互的目的。

对话历史是以列表的形式,按时间正序组织的。列表中的一个元素为字典形式记录的人机交互的一轮对话记录,用户的输入用“user”表示,模型生成的输出用“bot”。

Python示例
# coding=utf-8
# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/611472.html

import dashscope
from dashscope import Generation
from http import HTTPStatus
import json

response=Generation.call(
    model='qwen-v1',
    prompt='能否缩短一些,只讲三点',
    history=[
        {
            "user": "就当前的海洋污染的情况,写一份限塑的倡议书提纲,需要有理有据地号召大家克制地使用塑料制品",
            "bot": "好的,以下是一份限塑的倡议书提纲,以理有据地号召大家克制地使用塑料制品:\n\n一、限塑背景\n塑料污染已成为全球环境问题之一,海洋污染更是其中严重的一环。塑料制品 的过量使用已经对海洋生态环境造成了严重破坏,对海洋生物的生存和繁殖造成了严重影响,威胁到了人类的生存环境和健康。因此,我们需要采取行动来限制塑料的使用,保护我们的海洋家园。\n\n二、塑料污染的危害\n1. 对海洋生态环境的破坏:塑料垃圾污染海洋,导致海洋生物生存环境恶化,尤其是对海鸟等候鸟的危害极大。\n2. 对海洋资源的影响:塑料垃圾会阻碍海洋生态系统中的光合作用和营养物质的循环,对海洋生物的生长和繁殖产生负面影响。\n3. 对人体健康的威胁:塑料垃圾会对人类的健康产生长期影响,例如通过食物链传递给人类。\n\n三、限塑的建议\n1. 减少使用塑料制品:除了餐具和厨具等必须使用塑料制品外,其他塑料制品的使用量应该尽量减少。\n2. 减少一次性塑料制品的使用:一次性塑料制品对环境造成的危害很大,应该尽量减少使 用。\n3. 购买可重复使用的商品:购买可重复使用的商品,例如纸袋和水瓶,以减少对塑料的需求。\n\n四、限塑的实践方式\n1. 节约使用塑料制品:可以选择自备餐具、带布袋子购物等方式减少塑料制品的使用。\n2. 推广环保理念:可以通过社交媒体和宣传资料等途径,宣传环保理念,鼓励更多人加入到限塑行动中来。\n\n五、总结\n限塑行动是我们保护海洋生态环境和生物多样性 的重要举措。让我们一起行动起来,从自己做起,克制地使用塑料制品,共同保护我们的地球家园。"
        }
     ]
  )

if response.status_code==HTTPStatus.OK:
    print(json.dumps(response.output, indent=4, ensure_ascii=False))
else:
    print('Code: %d, status: %s, message: %s' % (response.status_code, response.code, response.message))
流式输出
Python示例
# coding=utf-8
# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/611472.html

import dashscope
from dashscope import Generation
from http import HTTPStatus
import json

responses=Generation.call(
    model='qwen-v1',
    prompt='就当前的海洋污染的情况,写一份限塑的倡议书提纲,需要有理有据地号召大家克制地使用塑料制品',
    stream=True)

for response in responses:
    if response.status_code==HTTPStatus.OK:
        print(json.dumps(response.output, indent=4, ensure_ascii=False))
    else:
        print('Code: %d, status: %s, message: %s' % (response.status_code, response.code, response.message))
参数配置

参数

类型

默认值

说明

model

string

-

指定用于对话的通义千问模型名,目前仅支持 qwen-v1 

prompt

string

-

用户当前输入的期望模型执行指令。

history (可选)

list[dict]

[]

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

top_p (可选)

float

0.8

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

stream (可选)

bool

False

是否使用流式输出。当以stream模式输出结果时,接口返回结果为generator,需要通过迭代获取结果,每个输出为当前生成的整个序列,最后一次输出为最终全部生成结果。

top_k

float

100.0

生成时,采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。注意:如果top_k的值大于100,top_k将采用默认值100

enable_search

bool

False

生成时,是否参考夸克搜索的结果。注意:打开搜索并不意味着一定会使用搜索结果;如果打开搜索,模型会将搜索结果作为prompt,进而“自行判断”是否生成结合搜索结果的文本,默认为false

seed

int

1234

生成时,随机数的种子,用于控制模型生成的随机性。如果使用相同的种子,每次运行生成的结果都将相同;当需要复现模型的生成结果时,可以使用相同的种子。seed参数支持无符号64位整数类型。默认值 1234

返回结果

  • 返回结果示例

{
    "status_code": 200,
    "request_id": "39a41abe-1bed-430a-b9b5-277130c7eb82",
    "code": "",
    "message": "",
    "output": {
        "text": "好的,以下是一份限塑的倡议书提纲:\n\nI. 引言\n\n- 阐明海洋污染的严重性,并介绍倡议书的目的和主要内容\n\nII. 海洋塑料污染的严重性\n\n- 详细描述海洋中塑料垃圾对海洋生态环境的危害,如何对海洋生态环境造成不可逆转的损害\n\n- 引用相关的研究和数据,让读者更加深入地了解海洋塑料污染的严重性\n\nIII. 推广限塑行动\n\n- 介绍限塑行动的必 要性和重要性,以及塑料制品的优点和缺点\n\n- 分析目前市场上可以使用的替代品,并向读者推荐可以减少使用塑料制品的替代品\n\n- 鼓励读者参与限塑行动,从小做起,做到减少塑料垃圾的贡献\n\nIV. 号召更多人加入限塑行动\n\n- 鼓励读者与身边的朋友和家人分享限塑行动的相关知识,让更多的人了解限塑行动的必要性\n\n- 号召更多企业加入限塑行动,为海洋环保做出贡献\n\n- 提供更多资源和渠道,让读者更加深入地了解限塑行动,并积极参与到这个行动中\n\nV. 结语\n\n- 总结限塑行动的必要性和重要性,并向读者表示感谢和祝福\n\n- 呼吁更多的人加入限塑 行动,为保护海洋环境做出自己的贡献\n\n希望这份限塑的倡议书提纲能够帮助您号召更多的人关注海洋环境保护,为建设美丽的海洋家园做出自己的贡献。",
    		"finish_reason": "stop"
    },
    "usage": {
        "input_tokens": 633,
        "output_tokens": 491
    }
}
  • 返回参数说明

返回参数

类型

说明

status_code

int

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

request_Id

string

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

code

string

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

message

string

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

output

dict

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

usage

dict

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

text

string

模型生成回复。

finish_reason

string

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

input_tokens

int

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

output_tokens

int

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

HTTP调用接口

功能描述

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

前提条件

提交接口调用

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

入参描述

传参方式

字段

类型

必选

描述

示例值

Url Path

version-id

String

API 版本,固定取值v1

v1

task-group

String

任务组,固定取值aigc

aigc

task

String

推理任务名称,固定取值text-generation

text-generation

function-call

String

调用模型特定功能,固定取值generation

generation

Header

Content-Type

String

请求类型:application/json 或者text/event-stream(开启 SSE 响应)

application/json

Authorization

String

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

Bearer d1**2a

X-DashScope-SSE

String

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

enable

X-DashScope-DataInspection

String

接口输入和输出的信息是否通过绿网过滤,默认不调用绿网。

enable

Body

model

String

指明需要调用的模型,目前可选 qwen-v1 和 qwen-plus-v1

qwen-v1

input.prompt

String

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

qwen-v1 prompt字段支持 1.5k Tokens 长度;

qwen-plus-v1 prompt字段支持 6.5k Tokens 长度

哪个公园距离我更近

input.history

List

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

"history": [

{

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

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

},

{

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

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

}

]

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的值大于100,top_k将采用默认值100

50

parameters.seed

Integer

生成时,随机数的种子,用于控制模型生成的随机性。如果使用相同的种子,每次运行生成的结果都将相同;当需要复现模型的生成结果时,可以使用相同的种子。seed参数支持无符号64位整数类型。默认值 1234

65535

parameters.enable_search

Bool

生成时,是否参考夸克搜索的结果。注意:打开搜索并不意味着一定会使用搜索结果;如果打开搜索,模型会将搜索结果作为prompt,进而“自行判断”是否生成结合搜索结果的文本,默认为false

true 或者 false

出参描述

字段

类型

描述

示例值

output.text

String

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

我建议你去颐和园

output.finish_reason

String

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

stop

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-v1",
    "input":{
        "prompt":"哪个公园距离我最近",
        "history":[
            {
                "user":"今天天气好吗?",
                "bot":"今天天气不错,要出去玩玩嘛?"
            },
            {
                "user":"那你有什么地方推荐?",
                "bot":"我建议你去公园,春天来了,花朵开了,很美丽。"
            }
        ]
    },
    "parameters": {
    }
}'

响应示例(SSE关闭)

{
    "output":{
        "text":"如果你在中国,我推荐你去北京的颐和园 ... ... 适合散步和欣赏景色。",
        "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-v1",
    "input":{
        "prompt":"哪个公园距离我最近",
        "history":[
            {
                "user":"今天天气好吗?",
                "bot":"今天天气不错,要出去玩玩嘛?"
            },
            {
                "user":"那你有什么地方推荐?",
                "bot":"我建议你去公园,春天来了,花朵开了,很美丽。"
            }
        ]
    },
    "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灵积模型服务通用状态码请查阅:返回状态码说明