Use SDKs to call applications in Alibaba Cloud Model Studio - Alibaba Cloud Model Studio

This topic describes how to use SDKs to call applications in Alibaba Cloud Model Studio.

SDK reference

Prerequisites

Alibaba Cloud Model Studio is activated. For more information, see Activate Alibaba Cloud Model Studio.

An API key is obtained. For more information, see Obtain an API key.
The SDK of the latest version is installed. For more information, see Install Alibaba Cloud Model Studio SDK.
An application is created and the ID of the application is obtained. For more information, see Application center and Obtain the ID and workspace of an application.

Quick start

The following examples show how to call an application in Alibaba Cloud Model Studio.

Note

Replace YOUR_API_KEY with your API key and YOUR_APP_ID with your application ID.

If you use Python, SDK for Python version 1.10.0 or later is required. If you use Java, SDK for Java version 2.5.0 or later is required.

Specify API key

export DASHSCOPE_API_KEY=YOUR_API_KEY

Sample code

Python

from http import HTTPStatus
from dashscope import Application


def app_call():
    response = Application.call(app_id='YOUR_APP_ID',
                                prompt='How do you specify the TopP parameter when you call an API operation?',
                                )

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

Java

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("'How do you specify the TopP parameter when you call an API operation?")
                .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);
    }  
}

Multi-round conversation

Alibaba Cloud Model Studio can manage multiple rounds of conversation in the cloud based on the session ID.

Alibaba Cloud Model Studio returns the session ID when you call an application for the first time. When you call the application again, specify the session ID to include information about the first call.

Note

The session ID is valid for 1 hour. Alibaba Cloud Model Studio supports up to 50 rounds of conversation history.

Python

from http import HTTPStatus
from dashscope import Application


def call_with_session():
    response = Application.call(app_id='YOUR_APP_ID',
                                prompt='I want to visit Singapore.'
                                )

    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='What are the attractions and foods in Singapore?',
                                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()

Java

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("I want to visit Singapore.")
                .build();

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

        param.setSessionId(result.getOutput().getSessionId());
        param.setPrompt("What are the attractions and foods in Singapore?");
        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);
    }  
}

Streaming output

You must specify relevant parameters to enable streaming output. If you use SDK for Python, set the stream parameter to True. If you use SDK for Java, use the streamCall method.

Important

To specify the incrementalOutput parameter when using SDK for Java, the SDK version 2.14.5 or later is required.

Python

from http import HTTPStatus
from dashscope import Application


def call_with_stream():
    responses = Application.call(app_id='YOUR_APP_ID',
                                 prompt='How do I make scrambled eggs? ',
                                 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()

Java

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("How do I make a hamburger?")
                .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);
    }
}

Sub-workspace

The preceding sample codes call an application in the default workspace. If you want to call an application in a sub-workspace, you must specify the workspace ID.

Note

Replace YOUR_WORKSPACE in the sample code with your workspace ID.

Python

from http import HTTPStatus
from dashscope import Application


def call_with_workspace():
    response = Application.call(app_id='YOUR_APP_ID',
                                workspace='YOUR_WORKSPACE',
                                prompt='How do I make scrambled eggs? ',
                                )

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

Java

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("How do I make a hamburger?")
                .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);
    }
}

Request parameters

Parameter	Type	Description
app_id	string	The application ID.
prompt	string	The input prompt.
session_id	string	The unique session ID. Alibaba Cloud Model Studio can retrieve conversation history from the cloud based on the session ID and pass the history to the model.
workspace	string	Optional. The workspace ID. When you call an application in a sub-workspace, you must specify the workspace ID. When you call an application in the default workspace, you do not need to specify the workspace ID.
stream	bool	Optional. Specifies whether to enable the streaming output mode. In streaming output mode, the model returns a generator. You need to use an iterative loop to fetch the results from the generator. By default, each output is the entire currently generated sequence and the final output is the whole generated content. Default value: False.
has_thoughts	bool	Optional. Specifies whether to generate information about the plug-in call or knowledge retrieval process. If you set this parameter to True, the model returns the step information about the plug-in call or knowledge retrieval process. Default value: False.
incremental_output	bool	Optional. Specifies whether to enable the incremental streaming output mode. In incremental streaming output mode, the later outputs do not contain previously generated content. You need to join the outputs together to obtain the whole response. Default value: False.

Response parameters

Parameter	Type	Description
status_code	int	The returned status code. The status code 200 indicates that the request is successful. Other status codes indicate that the request failed. If the request failed, you can obtain the error code and error message from the code and message parameters. Note This parameter is returned only in Python. If a request failed in Java, an error is reported and the code and message parameters are returned.
request_Id	string	The request ID.
code	string	The error code that is returned if the request failed. If the request is successful, no value is returned for this parameter. python only
message	string	The error message that is returned if the request failed. If the request is successful, no value is returned for this parameter. python only
output	dict	The information about the call results. For Qwen models, this parameter includes the generated output.
output.text	string	The response that is generated by the model.
output.finish_reason	string	The reason why the model stops generating content. Valid values: null: The model has not stopped. stop: The model stops generating the response due to a stop token.
output.session_id	string	The unique ID of the conversation history. The ID maintains the context during multiple rounds of conversation.
output.thoughts[].throught	string	The thoughts of the model.
output.thoughts[].action_type	string	The type of the action that is executed by the model. Valid values: api: Calls a plug-in. response: Returns the final response.
output.thoughts[].action_name	string	The name of the action that is executed by the model, such as document retrieval or plug-in call.
output.thoughts[].action	string	The action that is executed by the model.
output.thoughts[].action_input_stream	string	The streaming result of the input parameters.
output.thoughts[].action_input	string	The request parameters of the plug-in.
output.thoughts[].response	string	The response that is returned by the model.
output.thoughts[].observation	string	The result of document retrieval or plug-in call.
usage	dict	The usage metrics of the request.
usage.models[].model_id	string	The model that is called.
usage.models[].input_tokens	int	The number of tokens that are converted from the input text.
usage.models[].output_tokens	int	The number of tokens that are converted from the response generated by the model.
output.doc_reference	list	The reference information that is retrieved.
output.doc_reference[].index_id	string	The index of the reference information, which is associated with the subscript index in the <ref>[x]</ref> format in the response generated by the model.
output.doc_reference[].title	string	The title of the referenced text.
output.doc_reference[].doc_id	string	The ID of the referenced document.
output.doc_reference[].doc_name	string	The name of the referenced document.
output.doc_reference[].text	string	The text that is referenced.
output.doc_reference[].images	string	The URLs of the referenced images.