AI 助理
备案控制台
文档
产品文档
输入文档关键字查找
首页 大模型服务平台百炼 开发参考 应用调用 SDK详情

SDK详情

更新时间：
一键部署
产品详情
我的收藏

本文主要介绍如何使用SDK调用阿里云百炼的应用，即从应用中心->我的应用中新建的应用。

SDK详情

前提条件

快速调用

以下示例展示了调用应用的代码。

说明

需要使用您的API-KEY替换示例中的YOUR_API_KEY，并将APP-ID替换示例中的YOUR_APP_ID，代码才能正常运行。

python sdk version: dashscope>=1.10.0

java sdk version: >=2.5.0

设置API-KEY

export DASHSCOPE_API_KEY=YOUR_API_KEY

调用示例

from http import HTTPStatus
from dashscope import Application


def app_call():
    response = Application.call(app_id='YOUR_APP_ID',
                                prompt='API接口说明中, TopP参数改如何传递?',
                                )

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


if __name__ == '__main__':
    app_call()

import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.List;


public class Main{
      public static void appCall()
            throws ApiException, NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                .appId("YOUR_APP_ID")
                .prompt("API接口说明中, TopP参数改如何传递?")
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);

        System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
                result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());

        if (result.getUsage() != null && result.getUsage().getModels() != null) {
            for (ApplicationUsage.ModelUsage usage : result.getUsage().getModels()) {
                System.out.printf("modelId: %s, inputTokens: %d, outputTokens: %d\n",
                        usage.getModelId(), usage.getInputTokens(), usage.getOutputTokens());
            }
        }
    }

    public static void main(String[] args) {
        try {
            appCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            throw new RuntimeException(e);
        }
        System.exit(0);
    }  
}

多轮会话

阿里云百炼应用提供云端托管多轮对话功能，通过session_id进行多轮会话，阿里云百炼云端将自动托管多轮会话，调用侧无需自行维护多轮会话。

下面的例子中，第一次调用后返回session_id，在第二次调用时，可以传入第一次返回的session_id，这样第二次调用模型服务时，将携带第一次调用的会话信息。

说明

目前session id会话有效期是1个小时，最大历史会话轮数为50。

from http import HTTPStatus
from dashscope import Application


def call_with_session():
    response = Application.call(app_id='YOUR_APP_ID',
                                prompt='我想去新疆',
                                )

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

    response = Application.call(app_id='your app id',
                                prompt='那边有什么旅游景点或者美食?',
                                session_id=response.output.session_id
                                )
    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, output=%s, usage=%s\n' % (response.request_id, response.output, response.usage))


if __name__ == '__main__':
    call_with_session()

import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

import java.util.Arrays;
import java.util.List;

public class Main {
      public static void callWithSession()
            throws ApiException, NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                .appId("YOUR_APP_ID")
                .prompt("我想去新疆")
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);

        param.setSessionId(result.getOutput().getSessionId());
        param.setPrompt("那边有什么旅游景点或者美食?");
        result = application.call(param);

        System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
                result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
    }
  
   public static void main(String[] args) {
        try {
            callWithSession();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
        }
        System.exit(0);
    }  
}

流式输出

流式输出需要添加对应参数。其中，Python SDK中需要添加stream=True，Java SDK中需要使用streamCall接口调用。

重要

Java SDK设置增量输出的字段incrementalOutput，需要更新SDK版本>=2.14.5。

from http import HTTPStatus
from dashscope import Application


def call_with_stream():
    responses = Application.call(app_id='YOUR_APP_ID',
                                 prompt='如何做炒西红柿鸡蛋？',
                                 stream=True,
                                 incremental_output=True
                                 )

    for response in responses:
        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('output=%s, usage=%s\n' % (response.output, response.usage))


if __name__ == '__main__':
    call_with_stream()

import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import io.reactivex.Flowable;

import java.util.Arrays;
import java.util.List;

public class Main {
      public static void streamCall() throws NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                .appId("YOUR_APP_ID")
                .prompt("如何做土豆炖猪脚?")
                .incrementalOutput(true)
                .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);
    }
}

业务空间

上述调用示例调用的是默认业务空间的应用，如果需要调用其他业务空间，需要传入指定的业务空间标识。

说明

请将WORKSPACE替换示例中的YOUR_WORKSPACE，代码才能正常运行。请参考获取API-KEY、APP-ID和Workspace ID获取WORKSPACE。

from http import HTTPStatus
from dashscope import Application


def call_with_workspace():
    response = Application.call(app_id='YOUR_APP_ID',
                                workspace='YOUR_WORKSPACE',
                                prompt='如何做炒西红柿鸡蛋？',
                                )

    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, text=%s, usage=%s\n' % (response.request_id, response.output.text, response.usage))


if __name__ == '__main__':
    call_with_workspace()

import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

public class Main {
      public static void callWithWorkspace() throws NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                .workspace("YOUR_WORKSPACE")
                .appId("YOUR_APP_ID")
                .prompt("如何做土豆炖猪脚?")
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);

        System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
                result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
    }

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

输入参数

参数

类型

默认值

说明

app_id

string

-

应用标识。

prompt

string

-

用户当前输入的期望模型执行指令，用于指导模型生成回复。

session_id

string

-

对话历史会话唯一标识，传入session_id后，将在云端进行对话历史记录，调用大模型将自动携带存储的对话历史。

workspace（可选）

string

-

业务空间标识，当调用子业务空间的应用时，需要传递workspace标识，调用默认业务空间的应用无需传递workspace。

memoryId（可选）

string

-

长期记忆体Id，只有应用开启长期记忆，且api调用传入memoryId时长期记忆才会生效。

stream（可选）

bool

False

是否使用流式输出。当以stream模式输出结果时，接口返回结果为generator，需要通过迭代获取结果，默认每次输出为当前生成的整个序列，最后一次输出为最终全部生成结果。

has_thoughts（可选）

bool

False

是否输出插件调用和知识检索过程信息。开启后，将返回插件调用和知识检索的过程信息。

incremental_output（可选）

bool

False

控制在流式输出模式下是否开启增量输出，即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。默认False。

输出参数

返回参数

类型

说明

备注

status_code

int

200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。

说明

Python才有这个字段，Java失败会抛出异常，异常信息为code，message内容。

request_Id

string

系统生成的标识本次调用的id。

code

string

表示请求失败，表示错误码，成功忽略。

python only

message

string

失败，表示失败详细信息，成功忽略。

python only

output

dict

调用结果信息，对于千问模型，包含输出text。

output.text

string

模型生成回复。

output.finish_reason

string

正在生成时为null，生成结束时如果由于停止token导致则为stop。

output.session_id

string

对话历史会话的唯一标识。

在多轮会话时，可以使用此标识进行多轮会话保持。

output.thoughts[].throught

string

模型的思考结果。

output.thoughts[].action_type

string

大模型返回的执行步骤类型

api：执行API插件，response：返回最终结果。

output.thoughts[].action_name

string

执行的action名称，如文档检索、API插件。

output.thoughts[].action

string

执行的步骤。

output.thoughts[].action_input_stream

string

入参的流式结果。

output.thoughts[].action_input

string

插件的输入参数。

output.thoughts[].response

string

模型调用返回的结果。

output.thoughts[].observation

string

检索或插件的返回结果。

usage

dict

计量信息，表示本次请求的计量数据。

usage.models[].model_id

string

本次应用调用到的模型。

usage.models[].input_tokens

int

用户输入文本转换成Token后的长度。

usage.models[].output_tokens

int

模型生成回复转换为Token后的长度。

output.doc_reference

list

检索的引用信息。

output.doc_reference[].index_id

string

引用信息的索引，用以关联模型回复中的角标索引<ref>[x]</ref>

output.doc_reference[].title

string

引用的文本片段标题

output.doc_reference[].doc_id

string

引用的文档Id

output.doc_reference[].doc_name

string

引用的文档名

output.doc_reference[].text

string

引用的具体文本内容

output.doc_reference[].images

string

引用的图片URL列表

自定义参数透传

  • 在工作流应用和智能体编排应用中，您可以自定义开始节点的参数。例如，在一个查询城市天气信息的工作流应用中，您可以定义String类型的参数city和date。系统还设置了一个默认参数query，用于接收您输入的Prompt。

    您可以使用prompt传递query参数，使用biz_params传递自定义参数。

  • 为了使用插件参数透传功能，您需要在调用应用的 API 的 input 对象中，使用 biz_params 传递相关数据：

    user_defined_params是一个固定参数，表示这个对象中传入的是自定义插件参数信息

    接下来，以插件 ID 为键（例如 plugin_code_xxx），每一个值的对象即相关插件的待透传参数信息

    在对象最内侧，将包含多个键值对，每个键值对表示用户自定义的待透传参数名及其指定值。请注意，插件的自定义参数透传要配合插件录入时指定的传入x-source如果没有x-source属性修饰的参数将不会产生任何效果，而工作流没有x-source的限制。

  • 为了使用插件的用户级鉴权功能，您需要在调用应用的 API 的 input 对象中，使用 biz_params 传递相关数据

    user_defined_tokens是一个固定参数，表示这个对象中传入的是用户级鉴权信息

    接下来，以插件 ID 为键（例如 plugin_code_xxx），每一个值的对象即相关插件的鉴权信息

    user_token是一个固定参数，以该参数为键，其值为该插件需要的用户鉴权 Token

from http import HTTPStatus
from dashscope import Application


def call_with_stream():
    # 查询今天的天气
    biz_params = {
        # 工作流和智能体编排应用自定义输入参数透传
        "city": "杭州",
        "date": "2024-08-23",
        # 自定义插件输入参数透传
        "user_defined_params": {
            "plugin_code_xxx": {
                "id": 1,
                "title": "my_title1"
            }
        },
        # 自定义插件用户级鉴权透传
        "user_defined_tokens": {
            "plugin_code_xxx": {
                "user_token": "my_token1"
            }
        }
    }

    responses = Application.call(app_id='YOUR_APP_ID',
                                 prompt='如何做炒西红柿鸡蛋？',
                                 stream=True,
                                 biz_params=biz_params  # 传递业务参数
                                 )

    for response in responses:
        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('output=%s, usage=%s\n' % (response.output, response.usage))


if __name__ == '__main__':
    call_with_stream()

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\":\"Hangzhou\",\"date\":\"2024-08-23\",\"user_defined_params\":{\"plugin_code_xxx\":{\"id\":1,\"title\":\"my_title1\"}},\"user_defined_tokens\":{\"plugin_code_xxx\":{\"user_token\":\"my_token1\"}}}";

        ApplicationParam param = ApplicationParam.builder()
            .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);
    }
}

长期记忆

在智能体应用中，您可以打开长期记忆开关，同时在应用调用中指定记忆体Id（MemoryId），即可实现应用调用的长期记忆功能。

# SDK版本号应不低于1.20.6
from http import HTTPStatus
from dashscope import Application


def call_with_memory():
    response = Application.call(app_id='YOUR_APP_ID',
                                prompt='如何做炒西红柿鸡蛋？',
                                memory_id='6bff4f317a14442fbc9f73d29dbd5fc3'
                                )

    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, text=%s, usage=%s\n' % (response.request_id, response.output.text, response.usage))


if __name__ == '__main__':
    call_with_memory()

// SDK版本号应不低于2.16.3
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

public class Main {
      public static void callWithMemory() throws NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                .appId("YOUR_APP_ID")
                .prompt("如何做土豆炖猪脚?")
                .memoryId("6bff4f317a14442fbc9f73d29dbd5fc3")
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);

        System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
                result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
    }

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

上一篇：API详情下一篇：获取API-KEY、APP-ID和Workspace ID
文档推荐