AI 助理
备案控制台
文档
输入文档关键字查找
首页 大模型服务平台百炼 开发参考 应用调用 应用的参数透传

应用的自定义参数透传

更新时间：
产品详情
相关技术圈
我的收藏

本文介绍在智能体应用、工作流应用和智能体编排应用的调用过程中如何使用自定义参数透传的功能。需要透传参数的场景主要包括两个方面：1. 插件或工作流自身所需的参数；2. 插件中的用户级鉴权Token。通过自定义参数透传功能，您可以在调用应用时，同时传入插件或工作流所需的相关参数。

您需要已获取API Key并配置API Key到环境变量。如果通过SDK调用，还需要安装DashScope SDK。

自定义插件参数透传

本文以百炼提供的寝室公约查询工具作为示例，向您展示应用API如何调用自定义插件的参数透传功能。

已在应用中选择对应插件，并发布应用。

无需鉴权时

  1. 进入插件中心，单击编辑插件，配置接口信息，为参数加入业务透传标识，此处将寝室公约内容序号设置为业务透传参数，添加一行x-source: user并单击保存。

    image

  2. 通过API调用自定义的寝室公约内容查询插件，在input对象中，使用biz_params传递相关数据，根据透传的序号参数查询特定条目并正确返回结果。

    Python

    请求示例

    import os
from http import HTTPStatus
# 建议dashscope SDK 的版本 >= 1.14.0
from dashscope import Application

biz_params = {
    # 智能体应用的自定义插件输入参数透传，自定义的插件ID替换{your_plugin_code}
    "user_defined_params": {
        "{your_plugin_code}": {
            "article_index": 2}}}
response = Application.call(
                            # 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中，以减少API Key泄露风险。
                            api_key=os.getenv("DASHSCOPE_API_KEY"), 
                            app_id='YOUR_APP_ID',
                            prompt='寝室公约内容',
                            biz_params=biz_params)

if response.status_code != HTTPStatus.OK:
    print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
    print('request_id=%s\n output=%s\n usage=%s\n' % (response.request_id, response.output, response.usage))

    响应示例

    request_id=d97e3c58-7a75-9ea1-9ecf-d5be869b748e
 output={"text": "寝室公约的第二条内容为：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这提醒我们，在寝室生活中要维护良好的人际关系，共同营造一个和谐、积极的生活学习环境。如果您需要了解更多的公约内容，请告诉我具体的序号或继续提问。", "finish_reason": "stop", "session_id": "8ec3fa6c59794ed3ab803b921aa38d7a", "thoughts": null, "doc_references": null}
 usage={"models": [{"model_id": "qwen-max", "input_tokens": 453, "output_tokens": 107}]}

    Java

    请求示例

    package org.example;
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import io.reactivex.Flowable;

public class Test {
    public static void streamCall() throws NoApiKeyException, InputRequiredException {
        String bizParams =
                "{\"user_defined_params\":{\"{your_plugin_code}\":{\"article_index\":2}}}";
        ApplicationParam param = ApplicationParam.builder()
                // 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中，以减少API Key泄露风险。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .appId("YOUR_APP_ID")
                .prompt("寝室公约内容")
                .bizParams(JsonUtils.parse(bizParams))
                .build();

        Application application = new Application();
        Flowable<ApplicationResult> result = application.streamCall(param);
        result.blockingForEach(data -> {
            System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
                    data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason());

        });
    }

    public static void main(String[] args) {
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
        }
        System.exit(0);
    }
}

    响应示例

    requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要了解其他条目，请告诉我序号, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要了解其他条目，请告诉我序号。, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要了解其他条目，请告诉我序号。, finishReason: stop
    应用ID替换YOUR_APP_ID，自定义的插件ID替换{YOUR_PLUGIN_ID}。

    curl

    请求示例

    curl -X POST https://dashscope.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "寝室公约内容",
        "biz_params": 
        {
            "user_defined_params":
            {
                "YOUR_PLUGIN_ID":
                    {
                    "article_index": 2
                    }
            }
        } 
    },
    "parameters":  {},
    "debug":{}
}'

    响应示例

    {"output":
{"finish_reason":"stop",
"session_id":"e151267ffded4fbdb13d91439011d31e",
"text":"寝室公约的第二条内容是：“寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。”这意呀着在寝室生活中，大家要彼此支持，共同创造一个和谐、积极向上的生活环境。"},
"usage":{"models":[{"output_tokens":94,"model_id":"qwen-max","input_tokens":453}]},
"request_id":"a39fd2b5-7e2c-983e-84a1-1039f726f18a"}%
    应用ID替换YOUR_APP_ID，自定义的插件ID替换YOUR_PLUGIN_ID。
    传入未带有x-source属性的参数将不会产生任何效果，同时，目标插件的描述请使用自然语言描述插件的功能，帮助大模型判断当前任务是否需要调用当前插件。

需要鉴权时

  1. 进入插件中心，单击编辑插件，打开鉴权开关，选择用户级鉴权，单击保存。

  2. 应用调用API中透传用户级鉴权Token，如应用的API_KEY。

    您可以通过API调用自定义的寝室公约内容查询插件进行鉴权，使用 biz_params 传递相关数据，使用固定字段user_token传递Token信息，鉴权通过后根据透传的序号参数查询特定条目并正确返回结果。

    Python

    请求示例

    from http import HTTPStatus
import os
# 建议dashscope SDK 的版本 >= 1.14.0
from dashscope import Application

biz_params = {
    # 智能体应用的自定义插件鉴权透传，自定义的插件ID替换{your_plugin_code}，token替换YOUR_TOKEN
    "user_defined_params": {
        "{your_plugin_code}": {
            "article_index": 2}},
    "user_defined_tokens": {
        "{your_plugin_code}": {
            "user_token": "YOUR_TOKEN"}}}
response = Application.call(
                            # 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中，以减少API Key泄露风险。
                            api_key=os.getenv("DASHSCOPE_API_KEY"), 
                            app_id='YOUR_APP_ID',
                            prompt='寝室公约内容',
                            biz_params=biz_params)

if response.status_code != HTTPStatus.OK:
    print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
    print('request_id=%s\n output=%s\n usage=%s\n' % (response.request_id, response.output, response.usage))

    响应示例

    request_id=e928fe3b-3df3-9a3f-9ea4-884aed3aea3c
 output={"text": "寝室公约的第二条内容是：“寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。”这强调了寝室成员之间应该建立和谐、支持和尊重彼此的关系。", "finish_reason": "stop", "session_id": "c3b909e48a0b4867a57b482dece9cbb7", "thoughts": null, "doc_references": null}
 usage={"models": [{"model_id": "qwen-max", "input_tokens": 432, "output_tokens": 82}]}

    Java

    请求示例

    package org.example;
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import io.reactivex.Flowable;

public class Test {
    public static void streamCall() throws NoApiKeyException, InputRequiredException {
        String bizParams =
                "{\"user_defined_params\":{\"{your_plugin_code}\":{\"article_index\":2}}," +
                        "\"user_defined_tokens\":{\"{your_plugin_code}\":{\"user_token\":\"YOUR_TOKEN\"}}}";
        ApplicationParam param = ApplicationParam.builder()
                // 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中，以减少API Key泄露风险。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .appId("YOUR_APP_ID")
                .prompt("寝室公约内容")
                .bizParams(JsonUtils.parse(bizParams))
                .build();

        Application application = new Application();
        Flowable<ApplicationResult> result = application.streamCall(param);
        result.blockingForEach(data -> {
            System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
                    data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason());

        });
    }

    public static void main(String[] args) {
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
        }
        System.exit(0);
    }
}

    响应示例

    requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要了解其他条目，请告诉我序号, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要了解其他条目，请告诉我序号。, finishReason: null
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: 寝室公约的第二条内容是：寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。这强调了寝室生活中成员之间和谐相处与共同进步的重要性。如果您需要了解其他条目，请告诉我序号。, finishReason: stop
    应用ID替换YOUR_APP_ID，自定义的插件ID替换YOUR_PLUGIN_ID，鉴权Token替换YOUR_TOKEN。

    curl

    请求示例

    curl -X POST https://dashscope.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "寝室公约内容",
        "biz_params": 
        {
            "user_defined_params":
            {
                "YOUR_PLUGIN_ID":
                    {
                    "article_index": 2
                    }
            },
            "user_defined_tokens":
            {
                "YOUR_PLUGIN_ID":
                    {
                    "user_token": "YOUR_TOKEN"
                    }
            }
        } 
    },
    "parameters":  {},
    "debug":{}
}'

    响应示例

    {"output":{"finish_reason":"stop",
"session_id":"d3b5c3e269dc40479255a7a02df5c630",
"text":"寝室公约的第二条内容为：“寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。”这强调了寝室生活中成员之间和谐相处与共同进步的重要性。"},
"usage":{"models":[{"output_tokens":80,"model_id":"qwen-max","input_tokens":432}]},
"request_id":"1f77154c-edc3-9003-b622-816fa2f849cf"}%
    应用ID替换YOUR_APP_ID，自定义的插件ID替换YOUR_PLUGIN_ID，鉴权Token替换YOUR_TOKEN。

工作流应用和智能体编排应用的参数透传

本文以根据城市名查询城市行政区划作为示例，向您展示应用API如何调用自定义节点参数透传功能。

  1. 在应用中心 - 我的应用中，选择工作流应用或智能体编排应用。

  2. 输入参数设置为city，自定义大模型节点，其中User Prompt输入框中插入要透传的变量city，输出结果设置通过result变量文本返回，发布应用。

    image

  3. 应用调用API中透传自定义节点参数

    您可以通过API调用自定义节点的应用，使用prompt传递query参数，biz_params传递自定义参数，大模型会根据透传的城市名参数查询城市行政区划并返回结果。

    Python

    请求示例

    import os
from http import HTTPStatus
from dashscope import Application

# 工作流和智能体编排应用自定义输入参数透传
biz_params = {"city": "杭州"}
response = Application.call(
    # 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中，以减少API Key泄露风险。
    api_key=os.getenv("DASHSCOPE_API_KEY"), 
    app_id='YOUR_APP_ID',
    prompt='查询这个城市的行政区域划分',
    biz_params=biz_params  # 传递业务参数
)

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}, code={response.status_code}, message={response.message}')
else:
    print(f'output={response.output}, usage={response.usage}')

    响应示例

    output={"text": "杭州，简称“杭”，是浙江省的省会城市，位于中国东南部沿海地区，浙江省北部，地处北纬29°11′～30°33′，东经118°21′～120°30′之间。
全市面积16853.57平方千米，辖上城、拱墅、西湖、滨江、萧山、余杭、临平、钱塘、富阳、临安10个区和桐庐、淳安2县，代管建德1个县级市，共有13个区县（市）。
市政府驻地在上城区。截至2022年末，杭州市常住人口为1237.6万人。\n\n
杭州是中国八大古都之一，自秦朝设县治以来已有2200多年历史，曾是吴越国和南宋的都城，因风景秀丽，有“人间天堂”的美誉。市内人文古迹众多，西湖及其周边有大量的自然及人文景观遗迹，具代表性的有西湖文化、良渚文化、丝绸文化、茶文化等。", 
"finish_reason": "stop", "session_id": "6a3bf88eacda43128f57d87e29323166", 
"thoughts": null, "doc_references": null}, usage={"models": null}
    应用ID替换YOUR_APP_ID。

    Java

    请求示例

    package org.example;
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import io.reactivex.Flowable;

public class Test {
    public static void streamCall() throws NoApiKeyException, InputRequiredException {

        String bizParams =
                "{\"city\":\"杭州\"}";
        ApplicationParam param = ApplicationParam.builder()
                // 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中，以减少API Key泄露风险。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .appId("YOUR_APP_ID")
                .prompt("查询这个城市的行政区域划分")
                .bizParams(JsonUtils.parse(bizParams))
                .build();

        Application application = new Application();
        Flowable<ApplicationResult> result = application.streamCall(param);
        result.blockingForEach(data -> {
            System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
                    data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason());

        });
    }

    public static void main(String[] args) {
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
        }
        System.exit(0);
    }
}

    响应示例

    requestId: 713ebb6e-8840-9f31-bd58-e7e931ef345d, 
text: 杭州市下辖10个区、1个县，代管2个县级市，
即上城区、拱墅区、西湖区、滨江区、萧山区、余杭区、临平区、钱塘区、富阳区、临安区、桐庐县、淳安县、建德市、诸暨市。, 
finishReason: stop
    应用ID替换YOUR_APP_ID。

    curl

    请求示例

    curl -X POST https://dashscope.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "查询这个城市的行政区域划分",
        "biz_params": {
        "city": "杭州"}
    },
    "parameters":  {}
}'

    响应示例

    {"output":{"finish_reason":"stop","session_id":"c211219896004b50a1f6f66f2ec5413e",
"text":"杭州市下辖10个区、1个县，代管2个县级市，分别为：
上城区、拱墅区、西湖区、滨江区、萧山区、余杭区、临平区、钱塘区、富阳区、临安区、桐庐县、淳安县、建德市、诸暨市。
注意，诸暨市由浙江省直辖、杭州市与绍兴市共同管理。"},"usage":{},
"request_id":"02c3c9e1-7912-9505-91aa-248d04fb1f5d"}
    应用ID替换YOUR_APP_ID。

相关文档

请参考创建自定义插件、应用调用和应用调用API参考。

上一篇：应用调用API参考下一篇：获取API-KEY、APP-ID和Workspace ID
文档推荐