快速开始_模型服务灵积(DashScope)-阿里云帮助中心

重要

模型插件调用需"申请体验"并通过后才可使用，否则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-KEY：API-KEY的获取与配置。
已安装最新版Python SDK：安装DashScope SDK，Java 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使用

前提条件

已开通服务并获得API-KEY：API-KEY的获取与配置。

请求示例

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通用状态码请查阅：返回状态码说明