MiaoDu best practices-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

This topic provides best practices for the MiaoDu writing pipeline API to help you get started and develop your applications.

Prerequisites

You have activated the service.
To obtain the Workspace ID, see Obtain Workspace ID.
Import the AiMiaoBi SDK and obtain the latest SDK version.

The Maven dependency for the SDK is as follows:

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-aimiaobi20230801</artifactId>
  <version>1.0.86</version>
</dependency>

Procedure

Step 1: Upload a document to the document library

Call the UploadDoc API to upload a document to the MiaoDu document library. The following code provides an example:

package com.aliyun.sdk.service.aimiaobi20230801;

import com.alibaba.fastjson.JSON;
import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
import com.aliyun.sdk.gateway.pop.Configuration;
import com.aliyun.sdk.gateway.pop.auth.SignatureVersion;
import com.aliyun.sdk.service.aimiaobi20230801.models.UploadDocRequest;
import com.aliyun.sdk.service.aimiaobi20230801.models.UploadDocResponse;
import com.aliyun.sdk.service.aimiaobi20230801.AsyncClient;
import darabonba.core.client.ClientOverrideConfiguration;

import java.util.ArrayList;
import java.util.List;

import java.util.concurrent.CompletableFuture;

/**
 * packageName quanmiao
 *
 * @author zhujin
 * @version JDK 8
 * @className uploadDocTest
 * @date 2024/8/15
 * @description Document upload test
 */
public class uploadDocTest {
    public static void main(String[] args) {
        try{

            StaticCredentialProvider provider = StaticCredentialProvider.create(
                    Credential.builder()
                            .accessKeyId(Constant.accessKeyId)
                            .accessKeySecret(Constant.accessKeySecret)
                            .build()
            );

            AsyncClient client = AsyncClient.builder()
                    .region("cn-beijing") // Region ID
                    .credentialsProvider(provider)
                    .serviceConfiguration(Configuration.create()
                            .setSignatureVersion(SignatureVersion.V3)
                    )
                    .overrideConfiguration(
                            ClientOverrideConfiguration.create()
                                    .setProtocol("HTTPS")
                                    .setEndpointOverride("aimiaobi.cn-beijing.aliyuncs.com")
                    )
                    .build();


            List<UploadDocRequest.Docs> docsList = new ArrayList<>();
            UploadDocRequest.Docs doc = UploadDocRequest.Docs.builder()
                    .docName("test_document.pdf")
                    .fileUrl("https://xxx.oss-cn-beijing.aliyuncs.com/test/test_document.pdf")
                    .build();
            docsList.add(doc);

            UploadDocRequest request = UploadDocRequest.builder()
                    .workspaceId(Constant.workspaceId)
                    .docs(docsList)
                    .build();

            CompletableFuture<UploadDocResponse> future = client.uploadDoc(request);

            UploadDocResponse response = future.get();

            System.out.println("ALL***********************");
            System.out.println("Request header values for a successful request:");
            System.out.println(response.getStatusCode());
            System.out.println(response.getHeaders());
            String jsonStr = JSON.toJSONString(response.getBody());
            System.out.println(jsonStr);
        }catch (Exception ex){
            System.out.println("///////exception happen is " + ex);
        }
    }
}

Step 2: Get the uploaded document information

After uploading the document, call the GetDocInfo API to check if the document was uploaded successfully.

import com.alibaba.fastjson.JSON;
import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
import com.aliyun.sdk.gateway.pop.Configuration;
import com.aliyun.sdk.gateway.pop.auth.SignatureVersion;
import com.aliyun.sdk.service.aimiaobi20230801.models.GetDocInfoRequest;
import com.aliyun.sdk.service.aimiaobi20230801.models.GetDocInfoResponse;
import com.aliyun.sdk.service.aimiaobi20230801.AsyncClient;
import darabonba.core.client.ClientOverrideConfiguration;
import java.util.concurrent.CompletableFuture;
public class getDocInfo {
 public static void main(String[] args) {
 try{
 StaticCredentialProvider provider = StaticCredentialProvider.create(
 Credential.builder()
 .accessKeyId("")
 .accessKeySecret("")
 .build()
 );
 AsyncClient client = AsyncClient.builder()
 .region("cn-beijing") // Region ID
 .credentialsProvider(provider)
 // Service-level configuration
 .serviceConfiguration(Configuration.create()
 .setSignatureVersion(SignatureVersion.V3)
 )
 // Client-level configuration rewrite, can set Endpoint, Http request parameters, etc.
 .overrideConfiguration(
 ClientOverrideConfiguration.create()
 .setProtocol("HTTPS")
 .setEndpointOverride("aimiaobi.cn-beijing.aliyuncs.com")
 )
 .build();
 GetDocInfoRequest request = GetDocInfoRequest.builder()
 .workspaceId("llm-xxx")
 .docId("xxx")
 .build();
CompletableFuture<GetDocInfoResponse> future = client.getDocInfo(request);
 GetDocInfoResponse response = future.get();
 System.out.println("ALL***********************");
 System.out.println("Request header values for a successful request:");
 System.out.println(response.getStatusCode());
 System.out.println(response.getHeaders());
 String jsonStr = JSON.toJSONString(response.getBody());
 System.out.println(jsonStr);
 }catch (Exception ex){
 System.out.println("///////exception happen is " + ex);
             }
      }
 }

Step 3: Use assisted reading features (introduction, mind map, and Q&A)

You can use assisted reading features for a specified document. MiaoDu provides features such as document introduction, mind map, and document Q&A. The following code provides examples for these features.

RunDocIntroduction - Document Introduction

Generates an introduction for an article, video, or URL. The introduction includes a full-text summary, key points, and a chapter overview (segmentation, summary of each segment, and abstracts for each paragraph). It also supports multilingual input and output.
If you only need a full-text summary of the article, use the RunDocSummary API. For more information, see RunDocSummary.

The following code provides an example:

package com.aliyun.sdk.service.aimiaobi20230801;

import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
import com.aliyun.sdk.gateway.pop.Configuration;
import com.aliyun.sdk.gateway.pop.auth.SignatureVersion;
import com.aliyun.sdk.service.aimiaobi20230801.models.*;
import com.google.gson.Gson;
import darabonba.core.ResponseIterable;
import darabonba.core.ResponseIterator;
import darabonba.core.client.ClientOverrideConfiguration;

/**
 * packageName quanmiao
 *
 * @author zhujin
 * @version JDK 8
 * @className runDocIntroductionTest
 * @date 2024/8/15
 * @description Document introduction test
 */
public class runDocIntroductionTest {
    public static void main(String[] args) {
        try{

            StaticCredentialProvider provider = StaticCredentialProvider.create(
                    Credential.builder()
                            .accessKeyId(Constant.accessKeyId)
                            .accessKeySecret(Constant.accessKeySecret)
                            .build()
            );

            AsyncClient client = AsyncClient.builder()
                    .region("cn-beijing") // Region ID
                    .credentialsProvider(provider)
                    .serviceConfiguration(Configuration.create()
                            .setSignatureVersion(SignatureVersion.V3)
                    )
                    .overrideConfiguration(
                            ClientOverrideConfiguration.create()
                                    .setProtocol("HTTPS")
                                    .setEndpointOverride("aimiaobi.cn-beijing.aliyuncs.com")
                    )
                    .build();


            RunDocIntroductionRequest request = RunDocIntroductionRequest.builder()
                    .workspaceId(Constant.workspaceId)
                    .sessionId("sessionId_xxx")
                    .docId("xxxx-xxx-xxxx-xxx-xxxxxxx")
                    .build();

            ResponseIterable<RunDocIntroductionResponseBody> x = client.runDocIntroductionWithResponseIterable(request);

            ResponseIterator<RunDocIntroductionResponseBody> iterator = x.iterator();
            while (iterator.hasNext()) {
                System.out.println("----event----");
                RunDocIntroductionResponseBody event = iterator.next();
                System.out.println(new Gson().toJson(event));
                //System.out.println(event.getMessage());
            }

            System.out.println("ALL***********************");
            System.out.println("Request header values for a successful request:");
            System.out.println(x.getStatusCode());
            System.out.println(x.getHeaders());
        }catch (Exception ex){
            System.out.println("///////exception happen is " + ex);
        }
    }
}

RunDocBrainmap - Full-text brain map

Generates a three-level mind map for an article or book. It supports multiple languages. You can control the number of second-level nodes and the word count of leaf nodes.

The following code provides an example:

import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
import com.aliyun.sdk.gateway.pop.Configuration;
import com.aliyun.sdk.gateway.pop.auth.SignatureVersion;
import com.aliyun.sdk.service.aimiaobi20230801.AsyncClient;
import com.aliyun.sdk.service.aimiaobi20230801.models.RunDocBrainmapRequest;
import com.aliyun.sdk.service.aimiaobi20230801.models.RunDocBrainmapResponseBody;
import com.google.gson.Gson;
import darabonba.core.ResponseIterable;
import darabonba.core.ResponseIterator;
import darabonba.core.client.ClientOverrideConfiguration;

public class runDocBrainmap {
    public static void main(String[] args) {
        try {
            StaticCredentialProvider provider = StaticCredentialProvider.create(
                    Credential.builder()
                            .accessKeyId("")
                            .accessKeySecret("")
                            .build()
            );
            AsyncClient client = AsyncClient.builder()
                    .region("cn-beijing") // Region ID
                    .credentialsProvider(provider)
                    // Service-level configuration
                    .serviceConfiguration(Configuration.create()
                            .setSignatureVersion(SignatureVersion.V3)
                    )
                    // Client-level configuration rewrite, can set Endpoint, Http request parameters, etc.
                    .overrideConfiguration(
                            ClientOverrideConfiguration.create()
                                    .setProtocol("HTTPS")
                                    .setEndpointOverride("aimiaobi.cn-beijing.aliyuncs.com")
                    )
                    .build();
            RunDocBrainmapRequest request = RunDocBrainmapRequest.builder()
                    .workspaceId("llm-xxx")
                    .sessionId("sessionId_test")
                    .docId("xxxxx")
                    .build();
            ResponseIterable<RunDocBrainmapResponseBody> x = client.runDocBrainmapWithResponseIterable(request);
            ResponseIterator<RunDocBrainmapResponseBody> iterator = x.iterator();
            while (iterator.hasNext()) {
                System.out.println("----event----");
                RunDocBrainmapResponseBody event = iterator.next();
                System.out.println(new Gson().toJson(event));
                //System.out.println(event.getMessage());
            }
            System.out.println("ALL***********************");
            System.out.println("Request header values for a successful request:");
            System.out.println(x.getStatusCode());
            System.out.println(x.getHeaders());
        } catch (Exception ex) {
            System.out.println("///////exception happen is " + ex);
        }
    }
}

RunDocQa (Document Q&A/Multimodal file Q&A)

This feature answers natural language queries about specified documents and displays the source information for each answer. For articles, it provides a text answer and includes images if available. For multimodal files, the answer can include relevant images, video clips, or text.

The following code provides an example:

package com.aliyun.sdk.service.aimiaobi20230801;

import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
import com.aliyun.sdk.gateway.pop.Configuration;
import com.aliyun.sdk.gateway.pop.auth.SignatureVersion;
import com.aliyun.sdk.service.aimiaobi20230801.models.RunDocQaRequest;
import com.aliyun.sdk.service.aimiaobi20230801.models.RunDocQaResponseBody;
import com.google.gson.Gson;
import darabonba.core.ResponseIterable;
import darabonba.core.ResponseIterator;
import darabonba.core.client.ClientOverrideConfiguration;

import java.util.ArrayList;
import java.util.List;

/**
 * packageName quanmiao
 *
 * @author zhujin
 * @version JDK 8
 * @className runDocQATest
 * @date 2024/8/15
 * @description Document Q&A test
 */
public class runDocQATest {
    public static void main(String[] args) {
        try{

            StaticCredentialProvider provider = StaticCredentialProvider.create(
                    Credential.builder()
                            .accessKeyId(Constant.accessKeyId)
                            .accessKeySecret(Constant.accessKeySecret)
                            .build()
            );

            AsyncClient client = AsyncClient.builder()
                    .region("cn-beijing") // Region ID
                    .credentialsProvider(provider)
                    .serviceConfiguration(Configuration.create()
                            .setSignatureVersion(SignatureVersion.V3)
                    )
                    .overrideConfiguration(
                            ClientOverrideConfiguration.create()
                                    .setProtocol("HTTPS")
                                    .setEndpointOverride("aimiaobi.cn-beijing.aliyuncs.com")
                    )
                    .build();


            List<String> docIds = new ArrayList<>();
            docIds.add("xxx-xxxx-xxxx-xxx-xxxxxxx");

            RunDocQaRequest   request = RunDocQaRequest .builder()
                    .workspaceId(Constant.workspaceId)
                    .sessionId("sessionId_xxx")
                    .searchSource("fromDoc")
                    .query("What features does AI MiaoDu provide?")
                    .docIds(docIds)
                    .build();

            ResponseIterable<RunDocQaResponseBody> x = client.runDocQaWithResponseIterable(request); 

            ResponseIterator<RunDocQaResponseBody> iterator = x.iterator();
            while (iterator.hasNext()) {
                System.out.println("----event----");
                RunDocQaResponseBody event = iterator.next();
                System.out.println(new Gson().toJson(event));
                //System.out.println(event.getMessage());
            }

            System.out.println("ALL***********************");
            System.out.println("Request header values for a successful request:");
            System.out.println(x.getStatusCode());
            System.out.println(x.getHeaders());
        }catch (Exception ex){
            System.out.println("///////exception happen is " + ex);
        }
    }
}

FAQ about API calls

Q: After a file is successfully uploaded, why do I receive a "Failed" error with the message "file content is empty" when I immediately call the introduction or mind map API?

A: The UploadDoc API performs an asynchronous invocation. You must first call the GetDocInfo API to retrieve the actual status of the upload. You can perform operations such as generating a mind map, creating a summary, or running document Q&A only after the upload is successful.

Prerequisites

Procedure

Step 1: Upload a document to the document library

Step 2: Get the uploaded document information

Step 3: Use assisted reading features (introduction, mind map, and Q&A)

RunDocIntroduction - Document Introduction

RunDocBrainmap - Full-text brain map

RunDocQa (Document Q&A/Multimodal file Q&A)

FAQ about API calls