Skip to main content

Integrate Alibaba Cloud Model Studio large model applications using Spring AI Alibaba

Alibaba Cloud Model Studio applications overcome the limitations of large models in handling issues in private realms, retrieving the latest information, executing fixed procedures, and automatically planning complex projects. This capability significantly expands the application scope of large models. This topic describes how to use Spring AI Alibaba to integrate applications from Alibaba Cloud Model Studio. Only agent applications and workflow applications are supported.

Prerequisites

  1. Obtain and configure an API key and configure the API key as an environment variable. You must name the environment variable DASHSCOPE_API_KEY to avoid the security threat of hard coding.
  2. Create an Alibaba Cloud Model Studio application. You must create one of the following application types, obtain its application ID, and set the ID as an environment variable named APP_ID.
  3. If the Alibaba Cloud Model Studio application was created in a child workspace, obtain the workspace ID and set it as an environment variable named WORKSPACE_ID.

Procedure

1. Initialize a Spring Boot project

Environment requirements

  • Spring Boot 3.x
  • JDK 17 or later
You can initialize the project in one of the following two ways:
  1. Download the sample project for a quick start (Recommended) For the complete sample project, see bailian-agent.zip. After you download the code, you can skip to Step 3. Configure parameters and then proceed to Step 5. Start the Spring Boot project and test it.
  2. Build a project from scratch You can visit https://start.spring.io/ or use an IDE, such as IntelliJ IDEA, to create an empty Spring Boot project. Then, follow the subsequent steps.

2. Add dependencies

Add the dependencies for Spring AI Alibaba and related components to the pom.xml file of your project: 
<dependencies>
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        <version>1.0.0.2</version>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-logging</artifactId>
            </exclusion>
        </exclusions>
        <version>3.4.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-log4j2</artifactId>
        <version>3.4.0</version>
    </dependency>

    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.14.0</version>
    </dependency>
</dependencies>

3. Configure parameters

In the application.yml file, configure the application ID, Model Studio API key, and workspace ID. The workspace ID is required only if the Model Studio application was created in a child workspace. 
spring:
  ai:
    dashscope:
      agent:
        app-id: ${APP_ID} # The large model application ID. If no environment variable is set, replace this with the actual value.
      api-key: ${DASHSCOPE_API_KEY} # The Model Studio API key. If no environment variable is set, replace this with the actual value.
      #workspace-id: ${WORKSPACE_ID} # The workspace ID. Optional. If not set, the workspace of the Alibaba Cloud account is used.
# If a port conflict occurs, you can define a new port.
#server:
#  port: 9000

4. Call the Alibaba Cloud Model Studio large model application

Spring AI Alibaba uses the DashScopeAgent class to call the Alibaba Cloud Model Studio application. 
import com.alibaba.cloud.ai.dashscope.agent.DashScopeAgent;
import com.alibaba.cloud.ai.dashscope.agent.DashScopeAgentOptions;
import com.alibaba.cloud.ai.dashscope.api.DashScopeAgentApi;

import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.List;

@RestController
@RequestMapping("/ai")
public class BailianAgentController {
    private static final Logger logger = LoggerFactory.getLogger(BailianAgentController.class);

    private DashScopeAgent agent;

    @Value("${spring.ai.dashscope.agent.app-id}")
    private String appId;

    public BailianAgentController(DashScopeAgentApi dashscopeAgentApi) {
        this.agent = new DashScopeAgent(dashscopeAgentApi);
    }

    @GetMapping("/bailian/agent/call")
    public String call(@RequestParam(value = "message",
            defaultValue = "How do I use the SDK to quickly call an Alibaba Cloud Model Studio application?") String message) {
        ChatResponse response = agent.call(new Prompt(message, DashScopeAgentOptions.builder().withAppId(appId).build()));
        if (response == null || response.getResult() == null) {
            logger.error("chat response is null");
            return "chat response is null";
        }

        AssistantMessage app_output = response.getResult().getOutput();
        String content = app_output.getText();

        DashScopeAgentApi.DashScopeAgentResponse.DashScopeAgentResponseOutput output = (DashScopeAgentApi.DashScopeAgentResponse.DashScopeAgentResponseOutput) app_output.getMetadata().get("output");
        List<DashScopeAgentApi.DashScopeAgentResponse.DashScopeAgentResponseOutput.DashScopeAgentResponseOutputDocReference> docReferences = output.docReferences();
        List<DashScopeAgentApi.DashScopeAgentResponse.DashScopeAgentResponseOutput.DashScopeAgentResponseOutputThoughts> thoughts = output.thoughts();

        logger.info("content:\n{}\n\n", content);

        if (docReferences != null && !docReferences.isEmpty()) {
            for (DashScopeAgentApi.DashScopeAgentResponse.DashScopeAgentResponseOutput.DashScopeAgentResponseOutputDocReference docReference : docReferences) {
                logger.info("{}\n\n", docReference);
            }
        }

        if (thoughts != null && !thoughts.isEmpty()) {
            for (DashScopeAgentApi.DashScopeAgentResponse.DashScopeAgentResponseOutput.DashScopeAgentResponseOutputThoughts thought : thoughts) {
                logger.info("{}\n\n", thought);
            }
        }

        return content;
    }
}

5. Start the Spring Boot project and test it

Run the following code to start the Spring Boot project. Then, you can test the project using a tool such as Postman. 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BailianAgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(BailianAgentApplication.class, args);
    }
}
image

Billing

Model Studio applications are free to use. However, you are charged for model inference when you call models using these applications. For more information about model inference fees, see Billing items.

Error codes

For more information about common error codes, see Error message.

Learn more

  • Spring AI Alibaba: Provides documentation, tutorials, hands-on blog posts, and a developer community to help you develop generative AI applications in Java.
  • DashScope API Reference: Provides API descriptions and call examples for application calls.
  • spring-ai-alibaba-examples: The GitHub repository with more Spring AI Alibaba sample code.
Managed Agent API
Flow Agent API
Sandbox API
RAG API
Long-term Memory
ParseX API
Security API
Framework Integration
Application components
More
Assistant API (Deprecated)