DashScope Java SDK 调用通义千问实现文生文

DashScope Java SDK 调用通义千问实现文生文 | 极客日志

DashScope SDK

介绍

DashScope SDK 是阿里云推出的 AI 模型服务平台的官方开发工具包，通过它能轻松调用阿里云的通义千问（QWen）等一系列大语言模型。其相比于 OpenAI SDK 来说对中文的理解更优，因此这里选择使用 DashScope 来调用通义千问模型 API 来进行对话生成文本。

准备工作

使用阿里云百炼的大模型或应用前，需要先开通阿里云百炼，并获取 API Key 作为鉴权凭证。

可将 API Key 配置到环境变量，从而避免在代码里显式地配置 API Key，降低泄漏风险。

引入依赖

在项目中添加 DashScope Java SDK 依赖，并将版本号替换为最新的版本号。

<!-- dashscope-sdk-java -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>2.22.4</version>
</dependency>

使用示例

使用通义千问模型进行对话，根据文档的文生文的请求示例如下：

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        Generation gen = new Generation();
        Message systemMsg = Message.builder().role(Role.SYSTEM.getValue()).content("You are a helpful assistant.").build();
        Message userMsg = Message.builder().role(Role.USER.getValue()).content("你是谁？").build();
        GenerationParam param = GenerationParam.builder()
                // 若没有配置环境变量，请用百炼 API Key 将下行替换为：.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 此处以 qwen-plus 为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models
                .model("qwen-plus")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();
        return gen.call(param);
    }

    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(JsonUtils.toJson(result));
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // 使用日志框架记录异常信息
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
        System.exit(0);
    }
}

可知模型调用的基础流程如下：

初始化请求 Generation。
构建请求体 GenerationParam。
调用大模型获得结果 gen.call(param)。

请求体构建

因此调用大模型的重点在于如何构建请求体，根据文档中请求体参数有如下，加粗为必选参数，否则为可选参数：

model(String)（必须）

必须传入需要调用大模型的模型名称，模型列表：全部模型规格参数价格总览 - 大模型服务平台百炼 - 阿里云

message(Array)（必须）

必须传递给大模型的上下文，按对话顺序排列，数组中可传入：

System Message(Object)：系统消息，用于设定大模型的角色、语气、任务目标或约束条件等。一般放在 messages 数组的第一位。其有如下属性：
- content(String)：消息的内容
- role(String)：系统消息角色，固定为 system，通过 Role.SYSTEM.getValue() 获得。
User Message(object)：用户消息，用于向模型传递问题、指令或上下文等，有如下属性：
- role(String)：用户消息角色，固定为 user，通过 Role.USER.getValue() 获得。
Assistant Message(Object)：模型的回复，通常用于在多轮对话中作为上下文传给模型。通过将将模型的回复设置进 assistant 中就可以让模型具有'记忆功能'，同时会增加 token 的消耗，因此最好设置最好每次只传一部分的历史信息防止 token 超限，其有以下属性：
- content(String)：模型回复的文本内容。包含 tool_calls 时，content 可以为空。
- role(String)：助手消息的角色，固定为 assistant，通过 Role.ASSISTANT.getValue() 获得。
- partial(boolean)：是否开启前缀续写，默认为 false。开启后需要在 content 中传入需要续写的内容，模型会根据该内容进行续写，可适用于代码补全、文本续写等场景。
- tool_calls(Array)：发起工具调用后，返回的工具与入参信息，包含一个或多个对象。由上一轮模型响应的 tool_calls 字段获得。主要用于续写中断的对话、预构建工具调用流程场景。
Tool Message(Object)：工具的输出信息。当模型在生成回复时需要调用外部工具（如数据库查询、API 接口等），它会先生成一个包含 "tool_calls" 的 Assistant Message；工具执行完毕后，其输出结果需通过 Tool Message 传递回模型，以便模型基于这些结果生成最终回复。
- content(String)：工具函数的输出内容，必须为字符串格式。
- role(String)：固定为 tool，通过 Role.TOOL.getValue() 获得
- tool_call_id(String)：发起工具调用后返回的 id，可以通过 response.output.choices[0].message.tool_calls[$index]["id"] 获取，用于标记 Tool Message 对应的工具。

content(String 或 Array)：消息内容。若输入只有文本，则为 string 类型；若输入包含图像等多模态数据，或启用显式缓存，则为 array 类型，其有如下属性，这里只需要进行文生文操作，因此只需要指定对话的文本字符串 text 即可。

temperature(float)（可选）

采样温度，控制模型生成文本的多样性。temperature 越高，生成的文本更多样，反之，生成的文本更确定。发挥模型的创造性，温度过高可能会导致模型自由发挥'胡言乱语'；越低模型越稳定也越枯燥'照本宣科'，不会创新导致内容大差不差。取值范围：[0,2)

temperature=0.1（确定性高）： "一只猫是毛茸茸的宠物动物，有四条腿和一条尾巴。"
temperature=1.0（平衡）： "猫咪是一种可爱的家养动物，通常有柔软的毛发、灵敏的耳朵和明亮的眼睛。"
temperature=2.0（创造性高）： "月光下，一只银灰色的小精灵轻盈地跃过围墙，它的眼睛像两颗绿宝石在黑暗中闪烁..."

top_p(float)（可选）

核采样的概率阈值，控制模型生成文本的多样性。top_p 越高，生成的文本更多样。反之，生成的文本更确定。控制模型回答时选词的多样性，过低时模型只会选取高概率出现的词，描述一件事物时越'常见'；过高所有的词都会用表达过丰富可能'不常见'；取值范围：(0,1.0]

top_p=0.3（只选高概率词）： "猫是哺乳动物，是常见的宠物。"
top_p=0.9（多样选择）： "猫咪这种毛茸茸的小生物，时而高冷时而黏人，给家庭带来欢乐。"
top_p=1.0（所有词都可能）： "喵星人这种神秘的存在，用它的肉垫征服了人类的心..."（可能包含不常见表达）

top_k(Integer)（可选）

生成过程中采样候选集的大小。例如，取值为 50 时，仅将单次生成中得分最高的 50 个 Token 组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为 None 或当 top_k 大于 100 时，表示不启用 top_k 策略，此时仅有 top_p 策略生效。取值需要大于或等于 0。

enable_thinking(boolean)（可选）

使用混合思考模型时，是否开启思考模式。深度思考模型在生成回复前会先进行推理，以提升模型在逻辑推理与数值计算等复杂任务中的准确性。适用于 Qwen3、Qwen3-VL 模型。开启后，思考内容将通过 reasoning_content 字段返回。true：开启；false：关闭

thinking_budget(Integer)（可选）

思考过程的最大长度。适用于 Qwen3-VL、Qwen3 的商业版与开源版模型。深度思考模型有时会生成冗长的推理过程，这会增加等待时间并消耗较多 Token。通过 thinking_budget 参数可限制推理过程的最大 Token 数，超过该限制时，模型会立即生成回复。

enable_code_interpreter(boolean)（可选）

是否开启代码解释器功能。仅适用于思考模式下的 qwen3-max-preview。默认为 false。不支持 Java SDK。

repetition_penalty(float)（可选）

模型生成时连续序列中的重复度。提高 repetition_penalty 时可以降低模型生成的重复度，1.0 表示不做惩罚。防止重复相同的词造成'口吃'现象。没有严格的取值范围，只要大于 0 即可

presence_penalty(float)（可选）

控制模型生成文本时的内容重复度。取值范围 [-2.0，2.0]。正值降低重复度，负值增加重复度。鼓励使用新词汇，防止'词汇缺乏'现象。在创意写作或头脑风暴等需要多样性、趣味性或创造力的场景中建议提高该值；在技术文档或正式文本等强调一致性与术语准确性的场景中建议调低该值

vl_high_resolution_images(boolean)（可选）

是否将输入图像的像素上限提升至 16384Token 对应的像素值。通义千问 VL API 对单张图像编码后的视觉 Token 数量设有限制，默认配置下，高分辨率图像会被压缩，可能丢失细节，影响理解准确性。启用 vl_high_resolution_images 或调整 max_pixels 可增加视觉 Token 数量，从而保留更多图像细节，提升理解效果。默认为 false。

true：使用固定分辨率策略，忽略 max_pixels 设置，超过此分辨率时会将图像总像素缩小至此上限内；false：像素上限由 max_pixels 决定，输入图像的像素超过 max_pixels 会将图像缩小至 max_pixels 内。各模型的默认像素上限即 max_pixels 的默认值。

vl_enable_image_hw_output(boolean)（可选）

是否返回图像缩放后的尺寸。模型会对输入的图像进行缩放处理，配置为 True 时会返回图像缩放后的高度和宽度，开启流式输出时，该信息在最后一个数据块（chunk）中返回。支持 Qwen-VL 模型。默认为 false。

max_tokens(Integer)（可选）

用于限制模型输出的最大 Token 数。若生成内容超过此值，生成将提前停止，且返回的 finish_reason 为 length。适用于需控制输出长度的场景，如生成摘要、关键词，或用于降低成本、缩短响应时间。默认值与最大值均为模型的最大输出长度。

seed(Integer)（可选）

随机数种子。用于确保在相同输入和参数下生成结果可复现。若调用时传入相同的 seed 且其他参数不变，模型将尽可能返回相同结果。取值范围：[0,2^31−1]。

stream(boolean)（可选）

是否流式输出回复。false：生成完所有内容后一次性返回结果，因此可能会比较慢；true：边生成边输出，适合想要生成一点看一点。

incremental_output(boolean)（可选）

在流式输出模式下是否开启增量输出。默认为 false。

response_format(Object)（可选）

返回内容的格式。可选值 {"type": "text"}：输出文字回复（默认值）、{"type":"json_object"}：输出标准格式的 JSON 字符串、{"type":"json_schema","json_schema":{"..."} }：输出指定格式的 JSON 字符串

result_format(String)（可选）

返回数据的格式。推荐优先设置为 message，可以更方便地进行多轮对话。默认为 text，以下是格式分别为 message 和 text 时生成结果的异同：

// message GenerationResult(requestId=a7311c9d-8f53-42f5-91de-ea43b2606eee, usage=GenerationUsage(inputTokens=33, outputTokens=4, totalTokens=37, outputTokensDetails=null, promptTokensDetails=GenerationUsage.PromptTokensDetails(cacheType=null, cachedTokens=0, cacheCreationInputTokens=null, cacheCreation=null)), output=GenerationOutput(text=null, finishReason=null, choices=[GenerationOutput.Choice(finishReason=stop, index=null, mLessage=Message(role=assistant, content=翠湖雅居, toolCalls=null, toolCallId=null, name=null, contents=null, reasoningContent=null, partial=null), logprobs=null)], searchInfo=null, modelName=null), statusCode=200, code=, message=) 
// text GenerationResult(requestId=927195a6-c63f-45bc-b43f-9d4452326f52, usage=GenerationUsage(inputTokens=33, outputTokens=4, totalTokens=37, outputTokensDetails=null, promptTokensDetails=GenerationUsage.PromptTokensDetails(cacheType=null, cachedTokens=0, cacheCreationInputTokens=null, cacheCreation=null)), output=GenerationOutput(text=翠湖雅居, finishReason=stop, choices=null, searchInfo=null, modelName=null), statusCode=200, code=, message=)

logprobs(boolean)（可选）

是否返回输出 Token 的对数概率。默认值为 false。

top_logprobs(Integer)（可选）

指定在每一步生成时，返回模型最大概率的候选 Token 个数。默认为 0，取值范围：[0,5]。

n(Integer)（可选）

生成响应的个数，取值范围是 1-4。对于需要生成多个响应的场景（如创意写作、广告文案等），可以设置较大的 n 值。设置较大的 n 值不会增加输入 Token 消耗，会增加输出 Token 的消耗。当前仅支持 qwen-plus、Qwen3 (非思考模式）、qwen-plus-character 模型，且在传入 tools 参数时固定为 1。

stop(String 或 Array)（可选）

用于指定停止词。当模型生成的文本中出现 stop 指定的字符串或 token_id 时，生成将立即终止。可传入敏感词以控制模型的输出。

tools(Array)（可选）

包含一个或多个工具对象的数组，以供模型在外部工具调用中调用。可用于调用自定义工具，相关文档：Function Calling。使用 tools 时，必须将 result_format 设为 message。发起 Function Calling，或提交工具执行结果时，都必须设置 tools 参数。

tool_choice(String 或 Object)（可选）

工具选择策略。若需对某类问题强制指定工具调用方式（例如始终使用某工具或禁用所有工具），可设置此参数。默认为 auto。

parallel_tool_calls(boolean)（可选）

是否开启并行工具调用。true：开启；默认为 false。

enable_search(boolean)（可选）

模型在生成文本时是否使用互联网搜索结果进行参考。true：启用互联网搜索，模型会将搜索结果作为文本生成过程中的参考信息，但模型会基于其内部逻辑判断是否使用互联网搜索结果。默认为 false。

search_options(Object)（可选）

联网搜索的策略。仅当 enable_search 为 true 时生效，其属性有如下：

enable_search_extension(boolean)（可选）

是否开启特定领域增强。true：开启，默认为 false。

prepend_search_result(boolean)（可选）

在流式输出且 enable_source 为 true 时，可通过 prepend_search_result 配置第一个返回的数据包是否只包含搜索来源信息。可选值：true：只包含搜索来源信息；false：包含搜索来源信息与大模型回复信息，默认值。不支持 Java SDK。

X-DashScope-DataInspection(String)（可选）

在通义千问 API 的内容安全能力基础上，是否进一步识别输入输出内容的违规信息。不支持通过 Java SDK 设置。

响应示例

{
  "status_code": 200,
  "request_id": "902fee3b-f7f0-9a8c-96a1-6b4ea25af114",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "我是阿里云开发的一款超大规模语言模型，我叫通义千问。"
        }
      }
    ]
  },
  "usage": {
    "input_tokens":

响应对象

属性加粗代表该属性还具有子属性：

status_code(String)

本次请求的状态码。200 表示请求成功，否则表示请求失败。Java SDK 不会返回该参数。调用失败会抛出异常，异常信息为 status_code 和 message 的内容。

request_id(String)

本次调用的唯一标识符。Java SDK 返回参数为 requestld。

code(String)

错误码，调用成功时为空值。只有 Python SDK 返回该参数。

output(Object)

调用结果信息。

text(String)：模型生成的回复。当设置输入参数 result_format 为 text 时将回复内容返回到该字段。
choices(Array)：模型的输出信息。当 result_format 为 message 时返回 choices 参数。
- finish_reason(String)：与上述一致。
- message(Object)：模型输出的消息对象。
  - role(String)：输出消息的角色，固定为 assistant。
  - content(String 或 Array)：输出消息的内容。当使用 qwen-vl 或 qwen-audio 系列模型时为 array，其余情况为 string。如果发起 Function Calling，则该值为空。
    - text(String)：当使用 qwen-vl 或 qwen-audio 系列模型时，输出消息的内容。
    - image_hw(Array)：当 Qwen-VL 系列模型启用 vl_enable_image_hw_output 参数时，有两种情况：图像输入：返回图像的高度和宽度（像素）；视频输入：返回空数组。
  - reasoning_content(String)：模型的深度思考内容。
  - tool_calls(Array)：若模型需要调用工具，则会生成 tool_calls 参数。
    - function(Object)：调用工具的名称，以及输入参数。
      - name(String)：调用工具的名称。
      - arguments(String)：需要输入到工具中的参数，为 JSON 字符串。
    - index(Integer)：当前 tool_calls 对象在 tool_calls 数组中的索引。
    - id(String)：本次工具的响应 ID。
    - type(String)：工具类型，固定为 function。
search_info(Object)：联网搜索到的信息，在设置 search_options 参数后会返回该参数。

usage(Map)：本次 chat 请求使用的 Token 信息。太长了写不下去了，使用时再查。

extra_tool_info(Array)：开启 enable_search_extension 参数后返回的领域增强信息。有以下属性：

search_results(Array)：联网搜索到的信息，在设置 search_options 参数后会返回该参数。有以下属性：

finish_reason(String)：当设置输入参数 result_format 为 text 时该参数不为空。有四种情况：

调用大模型 API 实现文生文

无记忆

在构造用户消息时将需要询问大模型的消息设置入 content 中，在发送请求时选择返回结果的格式为 message 格式，不同格式下返回的结果也不同，如果返回结果格式为 text，则需要在 text 中获取返回结果的内容。这种方法调用比较简单，大模型不会联系上下文进行回答，比较适合只需要进行单次回答的场景。

public static GenerationResult singleTest(String userInput) throws NoApiKeyException, InputRequiredException {
    Generation gen = new Generation();
    Message systemMsg = Message.builder().role(Role.SYSTEM.getValue()).content("你是一个助手，现在开始根据我的需要生成一段连续的内容并且不要生成其他无关内容").build();
    Message userMsg = Message.builder().role(Role.USER.getValue()).content(userInput).build();
    GenerationParam param = GenerationParam.builder()
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model("qwen-plus")
            .messages(Arrays.asList(systemMsg, userMsg))
            .resultFormat(GenerationParam.ResultFormat.MESSAGE)
            .build();
    return gen.call(param);
}

如果进行多次连续的对话，模型不会根据上次生成的内容来进行回答，根据两次回答可知他们之间没有联系：

@Test
void test() throws NoApiKeyException, InputRequiredException {
    // 第一次对话
    System.out.println("=== 第一次对话 ===");
    GenerationResult result1 = singleTest("把大象放进冰箱需要几步？");
    System.out.println("AI 回复 1: " + result1.getOutput().getChoices().get(0).getMessage().getContent());
    System.out.println("消耗 token：" + result1.getUsage().getTotalTokens());
    // 第二次对话
    System.out.println("\n=== 第二次对话 ===");
    GenerationResult result2 = singleTest("长颈鹿呢？");
    System.out.println("AI 回复 2: " + result2.getOutput().getChoices().get(0).getMessage().getContent());
    System.out.println("消耗 token：" + result2.getUsage().getTotalTokens());
}

可记忆

如果需要大模型可以联系上下文进行回答，这句需要在每次让模型生成前给模型传入**'历史记录'，这样模型才会可以根据历史内容进行回答，token 的消耗也会更多。首先需要维护一个历史记录列表 conversationHistory，其中存放的是模型之前回答的记录，同时为避免上下文过长导致 token 消耗过多，这里最多只选取十条最近的历史记录，在构建消息时需要将系统消息 (System Message)**+用户消息 (User Message)+**模型回复 (Assistant Message)**传入。同时在获取模型返回结果后，需要将该结果加入历史信息列表中，其中 role 设置为 assistant，最后再截取最近的十条记录防止超限，这样就能够做到模型的记忆功能：

// 历史记录
List<Message> conversationHistory = new ArrayList<>();
// 上下文最大长度
int maxHistoryLength = 10;

@Test
GenerationResult continuousTest(String input) throws NoApiKeyException, InputRequiredException {
    // 1、初始化请求
    Generation gen = new Generation();
    // 2、构建系统消息
    Message systemMsg = Message.builder().role(Role.SYSTEM.getValue()).content("你是一个助手，现在开始根据我的需要生成一段连续的内容并且不要生成其他无关内容").build();
    // 3、构建用户消息
    Message userMsg = Message.builder().role(Role.USER.getValue()).content(input).build();
    // 4、构建完整的消息列表（系统消息 + 历史记录 + 当前消息）
    List<Message> allMessages = new ArrayList<>();
    allMessages.add(systemMsg);
    allMessages.addAll(conversationHistory);
    allMessages.add(userMsg);
    // 5. 发送请求并接收结果
    GenerationResult generationResult = gen.call(
            GenerationParam.builder()
                    .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                    .messages(allMessages)
                    .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                    .model("qwen-plus")
                    .build()
    );
    // 6、将回复内容添加到历史记录
    conversationHistory.add(Message.builder().role(Role.ASSISTANT.getValue()).content(generationResult.getOutput().getChoices().get(0).getMessage().getContent()).build());
    // 7. 删除多余的历史记录，防止超出 token 限制
    if (conversationHistory.size() > maxHistoryLength) {
        conversationHistory.subList(conversationHistory.size() - maxHistoryLength, conversationHistory.size());
    }
     generationResult;
}

这样的话，在问连续的问题时模型就能够正确地联系上文进行回答了：

如果需要开发一个智能客服 AI，不同的用户需要结合不同的历史记录；或是类似 deepseek，不同的对话需要结合不同的历史记录。这里就需要维护一个 Map：Map<String, List<Message>> conversationHistory。其中 key 为sessionId表示会话 id，value 为历史记录列表，通过一个会话 id 维护一段历史记录，不同的会话 id 就代表着不同的记录。在每次使用时首先传入对应的会话 id，根据 id 找到对应记录，然后再根据这段记录进行回答，这样就实现了不同会话的功能。