feat(ark_bot_chat): add bot chat refs and examples

Author: luminghao-bytedance

volcengine-java-sdk-ark-runtime/src/main/java/com/volcengine/ark/runtime/model/bot/completion/chat/BotChatCompletionRequest.java

@@ -62,7 +62,11 @@ public String toString() {
                 '}';
     }
 
-    public static final class Builder {
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static final class Builder extends ChatCompletionRequest.Builder {
         private Map<String, Object> metadata;
         private String botId;
         private String model;
@@ -97,6 +101,8 @@ public Builder metadata(Map<String, Object> metadata) {
 
         public Builder botId(String botId) {
             this.botId = botId;
+            // overwrite the model.
+            this.model = botId;
             return this;
         }
 

volcengine-java-sdk-ark-runtime/src/main/java/com/volcengine/ark/runtime/model/bot/completion/chat/BotChatCompletionResult.java

@@ -2,9 +2,12 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.volcengine.ark.runtime.model.bot.completion.chat.reference.BotChatResultReference;
 import com.volcengine.ark.runtime.model.bot.completion.chat.usage.BotUsage;
+import com.volcengine.ark.runtime.model.completion.chat.ChatCompletionChoice;
 import com.volcengine.ark.runtime.model.completion.chat.ChatCompletionResult;
 
+import java.util.List;
 import java.util.Map;
 
 @JsonIgnoreProperties(ignoreUnknown = true)
@@ -20,4 +23,33 @@ public class BotChatCompletionResult extends ChatCompletionResult {
      */
     @JsonProperty("bot_usage")
     private BotUsage botUsage;
+
+    /**
+     * The references returned by Search Actions.
+     */
+    private List<BotChatResultReference> references;
+
+    public Map<String, Object> getMetadata() {
+        return metadata;
+    }
+
+    public void setMetadata(Map<String, Object> metadata) {
+        this.metadata = metadata;
+    }
+
+    public BotUsage getBotUsage() {
+        return botUsage;
+    }
+
+    public void setBotUsage(BotUsage botUsage) {
+        this.botUsage = botUsage;
+    }
+
+    public List<BotChatResultReference> getReferences() {
+        return references;
+    }
+
+    public void setReferences(List<BotChatResultReference> references) {
+        this.references = references;
+    }
 }

volcengine-java-sdk-ark-runtime/src/main/java/com/volcengine/ark/runtime/model/bot/completion/chat/reference/BotChatResultReference.java

@@ -130,4 +130,164 @@ public class BotChatResultReference {
      */
     @JsonProperty("extra")
     private Map<String, Object> extra;
+
+    public String getUrl() {
+        return url;
+    }
+
+    public void setUrl(String url) {
+        this.url = url;
+    }
+
+    public String getLogoUrl() {
+        return logoUrl;
+    }
+
+    public void setLogoUrl(String logoUrl) {
+        this.logoUrl = logoUrl;
+    }
+
+    public String getMobileUrl() {
+        return mobileUrl;
+    }
+
+    public void setMobileUrl(String mobileUrl) {
+        this.mobileUrl = mobileUrl;
+    }
+
+    public String getSiteName() {
+        return siteName;
+    }
+
+    public void setSiteName(String siteName) {
+        this.siteName = siteName;
+    }
+
+    public String getTitle() {
+        return title;
+    }
+
+    public void setTitle(String title) {
+        this.title = title;
+    }
+
+    public BotCoverImage getCoverImage() {
+        return coverImage;
+    }
+
+    public void setCoverImage(BotCoverImage coverImage) {
+        this.coverImage = coverImage;
+    }
+
+    public String getSummary() {
+        return summary;
+    }
+
+    public void setSummary(String summary) {
+        this.summary = summary;
+    }
+
+    public String getPublishTime() {
+        return publishTime;
+    }
+
+    public void setPublishTime(String publishTime) {
+        this.publishTime = publishTime;
+    }
+
+    public String getCollectionName() {
+        return collectionName;
+    }
+
+    public void setCollectionName(String collectionName) {
+        this.collectionName = collectionName;
+    }
+
+    public String getProject() {
+        return project;
+    }
+
+    public void setProject(String project) {
+        this.project = project;
+    }
+
+    public String getDocId() {
+        return docId;
+    }
+
+    public void setDocId(String docId) {
+        this.docId = docId;
+    }
+
+    public String getDocName() {
+        return docName;
+    }
+
+    public void setDocName(String docName) {
+        this.docName = docName;
+    }
+
+    public String getDocType() {
+        return docType;
+    }
+
+    public void setDocType(String docType) {
+        this.docType = docType;
+    }
+
+    public String getDocTitle() {
+        return docTitle;
+    }
+
+    public void setDocTitle(String docTitle) {
+        this.docTitle = docTitle;
+    }
+
+    public String getChunkId() {
+        return chunkId;
+    }
+
+    public void setChunkId(String chunkId) {
+        this.chunkId = chunkId;
+    }
+
+    public String getChunkTitle() {
+        return chunkTitle;
+    }
+
+    public void setChunkTitle(String chunkTitle) {
+        this.chunkTitle = chunkTitle;
+    }
+
+    public String getPageNums() {
+        return pageNums;
+    }
+
+    public void setPageNums(String pageNums) {
+        this.pageNums = pageNums;
+    }
+
+    public Integer getOriginTextTokenLen() {
+        return originTextTokenLen;
+    }
+
+    public void setOriginTextTokenLen(Integer originTextTokenLen) {
+        this.originTextTokenLen = originTextTokenLen;
+    }
+
+    public String getFileName() {
+        return fileName;
+    }
+
+    public void setFileName(String fileName) {
+        this.fileName = fileName;
+    }
+
+    public Map<String, Object> getExtra() {
+        return extra;
+    }
+
+    public void setExtra(Map<String, Object> extra) {
+        this.extra = extra;
+    }
 }

volcengine-java-sdk-ark-runtime/src/main/java/com/volcengine/ark/runtime/model/completion/chat/ChatCompletionRequest.java

@@ -1,6 +1,7 @@
 package com.volcengine.ark.runtime.model.completion.chat;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionRequest;
 
 import java.util.List;
 import java.util.Map;

volcengine-java-sdk-ark-runtime/src/main/java/com/volcengine/ark/runtime/service/ArkBaseServiceImpl.java

@@ -1,6 +1,7 @@
 package com.volcengine.ark.runtime.service;
 
 
+import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionChunk;
 import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionRequest;
 import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionResult;
 import com.volcengine.ark.runtime.model.completion.chat.ChatCompletionChunk;
@@ -17,5 +18,5 @@ public interface ArkBaseServiceImpl {
 
     BotChatCompletionResult createBotChatCompletion(BotChatCompletionRequest request);
 
-    Flowable<ChatCompletionChunk> streamBotChatCompletion(BotChatCompletionRequest request);
+    Flowable<BotChatCompletionChunk> streamBotChatCompletion(BotChatCompletionRequest request);
 }

volcengine-java-sdk-ark-runtime/src/main/java/com/volcengine/ark/runtime/service/ArkService.java

@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.PropertyNamingStrategy;
+import com.volcengine.StringUtil;
 import com.volcengine.ark.runtime.*;
 import com.volcengine.ark.runtime.exception.ArkAPIError;
 import com.volcengine.ark.runtime.exception.ArkException;
@@ -13,6 +14,7 @@
 import com.volcengine.ark.runtime.interceptor.ArkResourceStsAuthenticationInterceptor;
 import com.volcengine.ark.runtime.interceptor.RequestIdInterceptor;
 import com.volcengine.ark.runtime.interceptor.RetryInterceptor;
+import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionChunk;
 import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionRequest;
 import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionResult;
 import com.volcengine.ark.runtime.model.completion.chat.*;
@@ -25,6 +27,7 @@
 import io.reactivex.Single;
 import okhttp3.Headers;
 import okhttp3.ResponseBody;
+import org.apache.commons.lang.StringUtils;
 import retrofit2.Call;
 import retrofit2.HttpException;
 import retrofit2.adapter.rxjava2.RxJava2CallAdapterFactory;
@@ -190,9 +193,9 @@ public BotChatCompletionResult createBotChatCompletion(BotChatCompletionRequest
     }
 
     @Override
-    public Flowable<ChatCompletionChunk> streamBotChatCompletion(BotChatCompletionRequest request) {
+    public Flowable<BotChatCompletionChunk> streamBotChatCompletion(BotChatCompletionRequest request) {
         request.setStream(true);
-        return stream(api.createBotChatCompletionStream(request, request.getModel(), new HashMap<>()), ChatCompletionChunk.class);
+        return stream(api.createBotChatCompletionStream(request, request.getModel(), new HashMap<>()), BotChatCompletionChunk.class);
     }
 
     public void shutdownExecutor() {

volcengine-java-sdk-ark-runtime/test/java/com/volcengine/ark/runtime/BotChatCompletionsExample.java

@@ -0,0 +1,91 @@
+package com.volcengine.ark.runtime;
+
+
+import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionRequest;
+import com.volcengine.ark.runtime.model.bot.completion.chat.BotChatCompletionResult;
+import com.volcengine.ark.runtime.model.completion.chat.ChatCompletionRequest;
+import com.volcengine.ark.runtime.model.completion.chat.ChatMessage;
+import com.volcengine.ark.runtime.model.completion.chat.ChatMessageRole;
+import com.volcengine.ark.runtime.service.ArkService;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/*
+# pom.xml
+<dependency>
+  <groupId>com.volcengine</groupId>
+  <artifactId>volcengine-java-sdk-ark-runtime</artifactId>
+  <version>LATEST</version>
+</dependency>
+*/
+
+public class BotChatCompletionsExample {
+
+    /**
+     * Authentication
+     * 1.If you authorize your endpoint using an API key, you can set your api key to environment variable "ARK_API_KEY"
+     * String apiKey = System.getenv("ARK_API_KEY");
+     * ArkService service = new ArkService(apiKey);
+     * Note: If you use an API key, this API key will not be refreshed.
+     * To prevent the API from expiring and failing after some time, choose an API key with no expiration date.
+     *
+     * 2.If you authorize your endpoint with Volcengine Identity and Access Management（IAM), set your api key to environment variable "VOLC_ACCESSKEY", "VOLC_SECRETKEY"
+     * String ak = System.getenv("VOLC_ACCESSKEY");
+     * String sk = System.getenv("VOLC_SECRETKEY");
+     * ArkService service = new ArkService(ak, sk);
+     * To get your ak&sk, please refer to this document(https://www.volcengine.com/docs/6291/65568)
+     * For more information，please check this document（https://www.volcengine.com/docs/82379/1263279）
+     */
+    public static void main(String[] args) {
+
+        String apiKey = System.getenv("ARK_API_KEY");
+        ArkService service = new ArkService(apiKey);
+
+        System.out.println("\n----- standard request -----");
+        final List<ChatMessage> messages = new ArrayList<>();
+        final ChatMessage systemMessage = ChatMessage.builder().role(ChatMessageRole.SYSTEM).content("你是豆包，是由字节跳动开发的 AI 人工智能助手").build();
+        final ChatMessage userMessage = ChatMessage.builder().role(ChatMessageRole.USER).content("常见的十字花科植物有哪些？").build();
+        messages.add(systemMessage);
+        messages.add(userMessage);
+
+        BotChatCompletionRequest chatCompletionRequest = BotChatCompletionRequest.builder()
+                .botId("${YOUR_BOT_ID}")
+                .messages(messages)
+                .build();
+
+        BotChatCompletionResult chatCompletionResult =  service.createBotChatCompletion(chatCompletionRequest);
+        chatCompletionResult.getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));
+        // the references example
+        chatCompletionResult.getReferences().forEach(ref -> System.out.println(ref.getUrl()));
+
+        System.out.println("\n----- streaming request -----");
+        final List<ChatMessage> streamMessages = new ArrayList<>();
+        final ChatMessage streamSystemMessage = ChatMessage.builder().role(ChatMessageRole.SYSTEM).content("你是豆包，是由字节跳动开发的 AI 人工智能助手").build();
+        final ChatMessage streamUserMessage = ChatMessage.builder().role(ChatMessageRole.USER).content("常见的十字花科植物有哪些？").build();
+        streamMessages.add(streamSystemMessage);
+        streamMessages.add(streamUserMessage);
+
+        BotChatCompletionRequest streamChatCompletionRequest = BotChatCompletionRequest.builder()
+                .botId("${YOUR_BOT_ID}")
+                .messages(streamMessages)
+                .build();
+
+        service.streamBotChatCompletion(streamChatCompletionRequest)
+                .doOnError(Throwable::printStackTrace)
+                .blockingForEach(
+                        choice -> {
+                            if (choice.getReferences() != null && !choice.getReferences().isEmpty()) {
+                                choice.getReferences().forEach(ref -> System.out.println(ref.getUrl()));
+                            }
+                            if (!choice.getChoices().isEmpty()) {
+                                System.out.print(choice.getChoices().get(0).getMessage().getContent());
+                            }
+                        }
+                );
+
+        // shutdown service
+        service.shutdownExecutor();
+    }
+
+}