文档

Java SDK(旧版)

更新时间:
一键部署

本文主要描述通过Java SDK调用阿里云百炼云服务的使用方式。Java SDK支持JDK1.8以上版本.

重要

本文档适用于使用Java SDK 1.2.0及以下的旧版本,最新版本请参照文档安装SDK

1. 获取SDK

在项目工程中添加maven依赖

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>broadscope-bailian-sdk-java</artifactId>
  <version>1.2.0</version>
</dependency>

2. 接口说明

2.1 公共参数

所有接口调用需要设置公共参数Acess Key Id、Access Secret Key和Agent Key, 请参考Completion API文档(旧版)方式获取。

2.2 生成文本

文本生成接口输入对应的参数后,阿里云百炼处理所有的逻辑,将最终的结果返回。

ApplicationClient client = ApplicationClient.builder()
                .token(token)
                .build();

CompletionsRequest request = new CompletionsRequest();
...
CompletionsResponse response = client.completions(request);
...

2.2.1 请求参数说明

CompletionsRequest, 文本生成请求参数。

参数

类型

必填

描述

requestId

String

请求唯一标识。

sessionId

String

上下文唯一标识。

appId

String

阿里云百炼应用标识。

prompt

String

提示词。

topP

Double

生成过程中核采样方法概率阈值,例如,取值为0.8时,仅保留概率加起来大于等于0.8的最可能token的最小集合作为候选集。取值范围为(0,1.0),取值越大,生成的随机性越高;取值越低,生成的确定性越高。默认是0.2。

stream

Boolean

是否流式输出。

hasThoughts

Boolean

是否输出模型推理过程。

bizParams

JSONObject

插件使用的业务参数,调用api插件会直接透传。

docReferenceType

String

启用文档检索后,文档引用类型, 取值包括: simple | indexed。

simple: 返回文档引用信息,但文本中不包含文档角标的索引位置。

indexed: 返回文档引用信息,文本中包含文档角标的索引位置。

history

List<CompletionsRequest.ChatQaPair>

对话历史记录

parameters

Parameter

模型参数

docTagIds

List<Long>

文档标签id

CompletionsRequest.ChatQaPair

user

String

对话历史的用户消息

bot

String

对话历史的大模型消息

Parameter

topK

Integer

生成时,采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。默认不传递该参数,取值为None或当top_k大于100时,表示不启用top_k策略,此时,仅有top_p策略生效。

seed

Integer

生成时,随机数的种子,用于控制模型生成的随机性。如果使用相同的种子,每次运行生成的结果都将相同;当需要复现模型的生成结果时,可以使用相同的种子。seed参数支持无符号64位整数类型。默认值 1234

useRawPrompt

Boolean

是否使用原始prompt

temperature

Double

采样温度在0到2之间。较高的值(如0.8)将使输出更加随机,而较低的值(如0.2)将使输出更加集中和确定。我们通常建议修改temperature或top_p,但不建议两者都修改。

maxTokens

Integer

模型生成的token的最大数量。输入token数量和生成token数量的总长度受模型上下文长度的限制。

2.2.2 响应结果说明

CompletionsResponse: 文本生成的响应结果。

字段名

字段类型

说明

success

boolean

请求是否成功, true: 是, false: 否

code

String

失败错误码

message

String

失败错误消息,仅当失败时有错误消息

requestId

String

请求的唯一标识

data

CompletionsResponse.Data

文本生成结果

CompletionsResponse.Data: 文本生成的内容。

字段名

字段类型

说明

responseId

String

响应唯一标识

sessionId

String

上下文唯一标识

text

String

文本生成结果

thoughts

List<Thought>

模型推理过程

docReferences

List<DocReference>

文档引用数据

usage

List<Usage>

应用级别的token消耗

CompletionsResponse.Thought: 推理过程数据格式定义

字段名

字段类型

说明

thought

String

LLM思考结果

actionType

String

llm返回的执行步骤类型, api: 执行api插件, response: 返回最终结果

actionName

String

执行的action名称, 如文档检索

action

String

执行的步骤

actionInputStream

String

入参的流式结果

actionInput

String

插件的输入参数

response

String

LLM返回的最终结果

observation

String

插件的返回结果

CompletionsResponse.DocReference: 文档引用数据

字段名

字段类型

说明

indexId

string

引用的角标索引

title

string

引用的文档标题

docId

string

引用的文档Id

docName

string

引用的文档名

docUrl

string

文档下载地址

text

string

引用的文档内容

bizId

string

业务方原始文件id

CompletionsResponse.Usage: 用量数据格式定义

参数

类型

描述

inputTokens

Integer

输出文本消耗的token

outputTokens

Integer

输出文本消耗的token

2.2.3 代码示例

import com.alibaba.fastjson.JSON;
import com.aliyun.broadscope.bailian.sdk.AccessTokenClient;
import com.aliyun.broadscope.bailian.sdk.ApplicationClient;
import com.aliyun.broadscope.bailian.sdk.models.CompletionsRequest;
import com.aliyun.broadscope.bailian.sdk.models.CompletionsResponse;    

public void testCompletions() {
        String accessKeyId = System.getenv("ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ACCESS_KEY_SECRET");

        String agentKey = System.getenv("AGENT_KEY");
        String appId = System.getenv("APP_ID");

        AccessTokenClient accessTokenClient = new AccessTokenClient(accessKeyId, accessKeySecret, agentKey);
        String token = accessTokenClient.getToken();
        ApplicationClient client = ApplicationClient.builder()
                .token(token)
                .build();

        String prompt = "帮我生成一篇200字的文章,描述一下春秋战国的政治、军事和经济";
        CompletionsRequest request = new CompletionsRequest()
                .setAppId(appId)
                .setPrompt(prompt);

        CompletionsResponse response = client.completions(request);

        if (!response.isSuccess()) {
            System.out.printf("failed to create completion, requestId: %s, code: %s, message: %s\n",
                    response.getRequestId(), response.getCode(), response.getMessage());
            return;
        }

        System.out.printf("requestId: %s, text: %s, ", response.getRequestId(), response.getData().getText());
        if (response.getData().getUsage() != null && response.getData().getUsage().size() > 0) {
            CompletionsResponse.Usage usage = response.getData().getUsage().get(0);
            System.out.printf("input tokens: %d, output tokens: %d\n", usage.getInputTokens(), usage.getOutputTokens());
        }
    }

其他参数使用示例:

public void testCompletionsWithParams() {
        String accessKeyId = System.getenv("ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ACCESS_KEY_SECRET");

        String agentKey = System.getenv("AGENT_KEY");
        String appId = System.getenv("APP_ID");

        AccessTokenClient accessTokenClient = new AccessTokenClient(accessKeyId, accessKeySecret, agentKey);
        String token = accessTokenClient.getToken();

        ApplicationClient client = ApplicationClient.builder()
                .token(token)
                .connectOptions(new ConnectOptions(30000, 60000, 60000))
                .build();

        String prompt = "云南近五年GNP总和是多少";

        CompletionsRequest request = new CompletionsRequest();
        request.setAppId(appId);
        request.setPrompt(prompt);

        //设置模型参数topP的值
        request.setTopP(0.2);

        //开启历史上下文, sessionId需要采用uuid保证唯一性, 后续传入相同sessionId,百炼平台将自动维护历史上下文
        String sessionId = UUIDGenerator.generate();
        request.setSessionId(sessionId);

        //设置历史上下文, 由调用侧维护历史上下文, 如果同时传入sessionId和history, 优先使用调用者管理的对话上下文
        List<CompletionsRequest.ChatQaPair> history = new ArrayList<>();
        CompletionsRequest.ChatQaPair chatQaPair = new CompletionsRequest.ChatQaPair("我想去北京", "北京的天气很不错");
        CompletionsRequest.ChatQaPair chatQaPair2 = new CompletionsRequest.ChatQaPair("北京有哪些景点", "北京有故宫、长城等");
        history.add(chatQaPair);
        history.add(chatQaPair2);
        request.setHistory(history);

        //设置模型参数topK,seed, temperature和max tokens
        CompletionsRequest.Parameter modelParameter = new CompletionsRequest.Parameter()
                .setTopK(50)
                .setSeed(2222)
                .setUseRawPrompt(true)
                .setTemperature(0.3)
                .setMaxTokens(20);
        request.setParameters(modelParameter);

        //设置文档标签tagId,设置后,文档检索召回时,仅从tagIds对应的文档范围进行召回
        request.setDocTagIds(Arrays.asList(100L, 101L));

        //返回文档检索的文档引用数据
        request.setDocReferenceType(DocReferenceTypeEnum.SIMPLE.getType());

        String sqlSchema = "{" +
                "    sqlInput: {" +
                "      \"synonym_infos\": \"国民生产总值: GNP|Gross National Product\"," +
                "      \"schema_infos\": [" +
                "        {" +
                "          \"columns\": [" +
                "            {" +
                "              \"col_caption\": \"地区\"," +
                "              \"col_name\": \"region\"" +
                "            }," +
                "            {" +
                "              \"col_caption\": \"年份\"," +
                "              \"col_name\": \"year\"" +
                "            }," +
                "            {" +
                "              \"col_caption\": \"国民生产总值\"," +
                "              \"col_name\": \"gross_national_product\"" +
                "            }" +
                "          ]," +
                "          \"table_id\": \"t_gross_national_product_1\"," +
                "          \"table_desc\": \"国民生产总值表\"" +
                "        }" +
                "      ]" +
                "    }" +
                "  }";
        request.setBizParams(JSON.parseObject(sqlSchema));

        CompletionsResponse response = client.completions(request);
        if (!response.isSuccess()) {
            System.out.printf("failed to create completion, requestId: %s, code: %s, message: %s",
                    response.getRequestId(), response.getCode(), response.getMessage());
            return;
        }

        System.out.printf("requestId: %s, text: %s\n", response.getRequestId(), response.getData().getText());
    }

注:您可以在百炼控制台测试窗使用“表模式”来编辑数据库Schme信息,然后单击“Code模式”生成JSON格式数据,然后将内容替换到sqlInput中。

image.png

流式响应代码示例:

public void testCompletionsWithStream() {
        String accessKeyId = System.getenv("ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ACCESS_KEY_SECRET");

        String agentKey = System.getenv("AGENT_KEY");
        String appId = System.getenv("APP_ID");

        AccessTokenClient accessTokenClient = new AccessTokenClient(accessKeyId, accessKeySecret, agentKey);
        String token = accessTokenClient.getToken();
        ApplicationClient client = ApplicationClient.builder()
                .token(token)
                .build();

        String prompt = "帮我生成一篇200字的文章,描述一下春秋战国的政治、军事和经济";
        CompletionsRequest request = new CompletionsRequest()
                .setAppId(appId)
                .setPrompt(prompt);

        CountDownLatch latch = new CountDownLatch(1);
        Flux<CompletionsResponse> response = client.streamCompletions(request);
        response.subscribe(
                data -> {
                    if (data.isSuccess()) {
                        System.out.printf("requestId: %s, text: %s\n", data.getRequestId(), data.getData().getText());
                    } else {
                        System.out.printf("failed to create completion, requestId: %s, code: %s, message: %s\n",
                                data.getRequestId(), data.getCode(), data.getMessage());
                    }
                },
                err -> {
                    System.out.printf("failed to create completion, err: %s\n", ExceptionUtils.getStackTrace(err));
                    latch.countDown();
                },
                () -> {
                    System.out.println("create completion completely");
                    latch.countDown();
                }
        );

        try {
            latch.await(30, TimeUnit.SECONDS);
        } catch (InterruptedException e) {
            throw new BaiLianSdkException(e);
        }
    }

2.3 创建文本向量

通过阿里云百炼,将文本内容转换为向量数据。

2.3.1 请求参数说明

生成文本向量请求参数。

参数

类型

必填

描述

input

List<String>

文本内容数组

textType

String

向量化类型,包括query和document。

query: 用来检索召回

document: 用来聚类、分类

2.3.2 响应结果说明

生成文本向量的响应参数。

参数

类型

描述

success

boolean

请求是否成功, true: 是, false: 否

code

int

失败错误码,0表示成功,其他值则表示调用出错

message

String

失败错误消息,仅当失败是有错误消息

requestId

String

请求的唯一标识

data

Data

文本生成结果

Data

embeddings

List<Embeddings>

embeddings列表

Embeddings

embedding

List<Double>

向量数据

textIndex

int

向量数据的索引

2.3.3 代码示例

public void testCreateTextEmbeddings() {
        String accessKeyId = System.getenv("ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ACCESS_KEY_SECRET");

        String agentKey = System.getenv("AGENT_KEY");

        Config config = new Config()
                .setAccessKeyId(accessKeyId)
                .setAccessKeySecret(accessKeySecret)
                .setEndpoint(ConfigConsts.POP_ENDPOINT);

        try {
            Client client = new Client(config);

            List<String> input = new ArrayList<>();
            input.add("今天天气怎么样");

            CreateTextEmbeddingsRequest request = new CreateTextEmbeddingsRequest()
                    .setAgentKey(agentKey)
                    .setInput(input)
                    .setTextType(EmbeddingTextTypeEnum.QUERY.getType());

            CreateTextEmbeddingsResponse response = client.createTextEmbeddings(request);
            CreateTextEmbeddingsResponseBody body = response.getBody();
            if (body == null || !body.success) {
                String error = body == null ? "create token error" : body.message;
                throw new BaiLianSdkException(error);
            }

            CreateTextEmbeddingsResponseBody.CreateTextEmbeddingsResponseBodyData data = body.getData();
            List<CreateTextEmbeddingsResponseBody.CreateTextEmbeddingsResponseBodyDataEmbeddings> embeddings = data.getEmbeddings();
            for (CreateTextEmbeddingsResponseBody.CreateTextEmbeddingsResponseBodyDataEmbeddings embedding : embeddings) {
                Integer textIndex = embedding.getTextIndex();
                List<Double> embeddingsArray = embedding.getEmbedding();

                System.out.printf("textIndex: %d, embedding: %s\n", textIndex, embeddingsArray);
            }
        } catch (BaiLianSdkException e) {
            throw e;
        } catch (Exception e) {
            throw new BaiLianSdkException(e);
        }
    }

  • 本页导读 (0)
文档反馈