Dashscope插件功能能夠使得大模型的生成內容與外部三方應用結合，使得模型生成的內容更加準確和豐富，模型將擁有更好的生成能力。您也可以通過開發自定義插件，來使得模型生成更符合您預期的結果。

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

• 可以獲得更加實時性的消息，比如體育賽事報道、實時、熱點新聞

• 可以讓用戶獲得更多的能力，比如查詢酒店信息，預定酒店、預定機票

• 可以讓用戶構建專屬的信息庫

插件模型概覽

插件使用

您可以在插件廣場申請需要使用開通的插件，申請通過后才能使用相應插件功能。

與不使用插件只調用大模型的情況相似，您可以通過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通用狀態碼請查閱：返回狀態碼說明