Skip to main content

MiaoDu best practices

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

Prerequisites

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.
  1. 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);
        }
    }
}
  1. 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);
        }
    }
}
  1. 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.
Agent Development
Agent Context
Agent Governance & Evolution
Store
Application Marketplace
Use Cases
Support