文档

快速开始

更新时间:
重要

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

Dashscope插件功能能够使得大模型的生成内容与外部三方应用结合,使得模型生成的内容更加准确和丰富,模型将拥有更好的生成能力。您也可以通过开发自定义插件,来使得模型生成更符合您预期的结果。

使用插件功能,大模型生成可以在如下几个方面得到更好的扩展:

  • 可以获得更加实时性的消息,比如体育赛事报道、实时、热点新闻

  • 可以让用户获得更多的能力,比如查询酒店信息,预定酒店、预定机票

  • 可以让用户构建专属的信息库

插件模型概览

支持模型

模型英文名

支持插件中文名

支持插件英文名

通义千问

qwen-turbo

qwen-plus

qwen-max

文字识别

ocr

计算器

calculator

图片生成

text_to_image

万豪酒店预定推荐

haozhu_recommend_hotel

PDF解析

pdf_extracter

Python代码解释器

code_interpreter

插件使用

您可以在插件广场申请需要使用开通的插件,申请通过后才能使用相应插件功能。

与不使用插件只调用大模型的情况相似,您可以通过SDK和HTTP请求两种方法,让大模型在插件的支持下,返回生成结果。

本文仅描述了插件调用的基础方法,若您希望了解详细的输入输出参数的含义,请查阅插件调用详细说明;若您希望获得调用具体插件的例子,请查阅调用样例

SDK使用

前提条件

示例代码

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

说明

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

同时满足:

Python SDK version: dashscope>=1.13.1

注意:

Java SDK暂不支持插件功能。

设置API-KEY

export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

执行下列python代码。

import json
from http import HTTPStatus
import dashscope


def call_with_messages():
    plugins = {'calculator': {}}  # choose the desired plugin(s).
    messages = [{'role': 'system', 'content': 'You are a helpful assistant.'},
                {"role": 'user', 'content': '12345*98765是多少'}]
    response = dashscope.Generation.call(
        model='qwen-plus',
        messages=messages,
        result_format='message',  # set the result to be "message" format.
        plugins=plugins,
    )
    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()
    

python调用成功,将输出如下结果。关于输入的参数、结果中每个字段的详细信息,以及多轮对话等更加高级的调用方式,请查阅插件调用详细说明

{
    "status_code": 200,
    "request_id": "1ba713ab-b05a-914e-b4a6-72258ec1d5d8",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": null,
                "messages": [
                    {
                        "role": "assistant",
                        "plugin_call": {
                            "name": "calculator",
                            "arguments": "{\"payload__input__text\": \"12345*98765\", \"header__request_id\": \"f275e6\"}"
                        },
                        "content": "Thought: 我需要进行乘法运算,需要用到计算器API。"
                    },
                    {
                        "role": "plugin",
                        "name": "calculator",
                        "content": "{\"equations\": [\"12345 * 98765\"], \"results\": [1219253925.0]}",
                        "status": {
                            "code": 200,
                            "name": "Success",
                            "message": "success"
                        }
                    },
                    {
                        "role": "assistant",
                        "content": "Thought: 这个问题的答案是1219253925.0。\nFinal Answer: 1219253925.0"
                    }
                ]
            }
        ]
    },
    "usage": {
        "input_tokens": 22,
        "output_tokens": 130,
        "total_tokens": 152
    }
}

HTTP使用

前提条件

请求示例

HTTP接口使用POST方式请求https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation ,获取大模型推理结果。

以下示例展示通过CURL命令来调用通义千问模型的脚本(SSE 关闭)。SSE关闭意味着服务端将一次性返回所有结果。

说明

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

在命令行窗口中,执行下列命令。

curl -v --location --request POST '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-Plugin: {"calculator":{}}' \
--data-raw '{
    "model": "qwen-plus",
    "input": {
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "12345*98765是多少"
            }
        ]
    },
    "parameters": {
        "seed": 42,
        "result_format": "message"
    }
}'

大模型将一次性返回如下结果。关于请求中的每个参数、结果中每个字段的详细信息,请查阅插件调用详细说明

{
    "status_code": 200,
    "request_id": "1ba713ab-b05a-914e-b4a6-72258ec1d5d8",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": null,
                "messages": [
                    {
                        "role": "assistant",
                        "plugin_call": {
                            "name": "calculator",
                            "arguments": "{\"payload__input__text\": \"12345*98765\", \"header__request_id\": \"f275e6\"}"
                        },
                        "content": "Thought: 我需要进行乘法运算,需要用到计算器API。"
                    },
                    {
                        "role": "plugin",
                        "name": "calculator",
                        "content": "{\"equations\": [\"12345 * 98765\"], \"results\": [1219253925.0]}",
                        "status": {
                            "code": 200,
                            "name": "Success",
                            "message": "success"
                        }
                    },
                    {
                        "role": "assistant",
                        "content": "Thought: 这个问题的答案是1219253925.0。\nFinal Answer: 1219253925.0"
                    }
                ]
            }
        ]
    },
    "usage": {
        "input_tokens": 22,
        "output_tokens": 130,
        "total_tokens": 152
    }
}

接收流式输出

上述代码会在整体文本生成完成后,一次性返回所有输出结果。无论您使用SDK还是HTTP接口,均可以通过参数配置,让大模型一边生成一边输出,即通过流式输出的方式尽快地将中间结果显示在屏幕上,请查阅插件调用详细说明

状态码说明

DashScope灵积模型服务通用状态码请查阅:返回状态码说明

  • 本页导读 (0)