插件调用详细说明

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

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

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

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

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

插件模型概览

插件使用

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

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

本文详细描述了输入输出参数的含义，若您希望获得调用具体插件的例子，请查阅调用样例。

SDK使用

前提条件

• 已开通服务并获得API-KEY：开通DashScope并创建API-KEY。

• 已安装最新版Python SDK：安装DashScope SDK，Java暂不支持插件功能。

示例代码

说明

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

同时满足：

Python SDK version: dashscope>=1.13.1

代码才能正常运行。

注意

Java暂不支持插件功能。

API-KEY设置

export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

单轮问答

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

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

多轮会话

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


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)
        messages.extend(response.output.choices[0]['messages'])
    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': '调用插件计算一下再加上22222是多少'})
        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()

流式输出

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是多少'}]
    responses = dashscope.Generation.call(
        model='qwen-plus',
        messages=messages,
        result_format='message',  # set the result to be "message" format.
        plugins=plugins,
        stream=True,
    )
    for response in responses:
        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": "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
    }
}

若使用上述的多轮对话例子，第二轮对话返回结果如下。

{
    "status_code": 200,
    "request_id": "c9a32395-562f-91a8-ae75-87fb149b4595",
    "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\": \"1219253925+22222\", \"header__request_id\": \"2\"}"
                        },
                        "content": "Thought: 首先我需要将1219253925.0与22222相加，然后再使用计算器API来进行这个运算。"
                    },
                    {
                        "role": "plugin",
                        "name": "calculator",
                        "content": "{\"equations\": [\"1219253925 + 22222\"], \"results\": [1219276147.0]}",
                        "status": {
                            "code": 200,
                            "name": "Success",
                            "message": "success"
                        }
                    },
                    {
                        "role": "assistant",
                        "content": "Thought: 现在我知道了结果。\nFinal Answer: 1219276147.0"
                    }
                ]
            }
        ]
    },
    "usage": {
        "input_tokens": 86,
        "output_tokens": 147,
        "total_tokens": 233
    }
}

返回参数说明

HTTP使用

前提条件

• 已开通服务并获得API-KEY：开通DashScope并创建API-KEY。

请求地址

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

入参描述

出参描述

请求示例（SSE关闭）

以下示例展示通过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": {
        "result_format": "message",
        "seed": 42
    }
}'

响应示例（SSE关闭）

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

上述代码会在整体文本生成完成后，一次性返回所有输出结果。

请求示例（SSE开启）

通过代码--header 'X-DashScope-SSE: enable'在HTTP header中设置SSE开启，让大模型一边生成一边输出，即通过流式输出的方式尽快地将中间结果显示在屏幕上。

以下示例展示通过CURL命令来调用通义千问模型的脚本（SSE 开启）。

curl -v --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \
--header 'Authorization: Bearer <your-dashscope-api-key>' \
--header 'X-DashScope-SSE: enable' \
--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": {
        "result_format": "message",
        "seed": 42
    }
}'

响应示例（SSE开启）

id:1
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"messages":[{"content":"Thought: ","role":"assistant"}],"finish_reason":"null"}]},"usage":{"total_tokens":25,"input_tokens":22,"output_tokens":3},"request_id":"3a072613-a0e9-9980-a93d-32bb1fbe6f99"}

id:2
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"messages":[{"content":"Thought: 我需要使用计算器API来进行数学运算","role":"assistant"}],"finish_reason":"null"}]},"usage":{"total_tokens":33,"input_tokens":22,"output_tokens":11},"request_id":"3a072613-a0e9-9980-a93d-32bb1fbe6f99"}
... ... ... ...
... ... ... ...


id:15
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"messages":[{"plugin_call":{"name":"calculator","arguments":"{\"payload__input__text\": \"12345*98765\", \"header__request_id\": \"\"}"},"content":"Thought: 我需要使用计算器API来进行数学运算。","role":"assistant"},{"name":"calculator","role":"plugin","content":"{\"equations\": [\"12345 * 98765\"], \"results\": [1219253925.0]}","status":{"name":"Success","message":"success","code":200}},{"content":"Thought: 这个结果是正确的，我可以告诉用户12345乘以98765等于多少了。\nFinal Answer: 1219253925","role":"assistant"}],"finish_reason":"stop"}]},"usage":{"total_tokens":148,"input_tokens":22,"output_tokens":126},"request_id":"3a072613-a0e9-9980-a93d-32bb1fbe6f99"}

状态码说明

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