1. 为什么选择SpringBoot整合通义千问？

如果你正在开发一个需要“智能大脑”的应用，比如一个能自动回复用户咨询的客服系统、一个帮你写周报的办公助手，或者一个能进行多轮趣味聊天的智能机器人，那么给项目接入一个大语言模型几乎是现在的标配。在众多选择里，阿里云的通义千问模型，凭借其出色的中文理解能力、稳定的服务性能和极具竞争力的价格，成为了很多开发者的首选。

而SpringBoot，作为Java领域最主流的快速开发框架，以其“约定大于配置”的理念，极大地简化了项目的搭建和部署过程。把这两者结合起来，就像是给一辆性能出色的跑车（SpringBoot应用）装上了一颗顶尖的AI引擎（通义千问），能让你用最熟悉的Java技术栈，快速跑通智能对话功能，把想法变成可落地的产品。

我自己的团队在几个内部工具和客户项目中都采用了这个组合。实测下来，从零开始到第一个对话接口跑通，顺利的话半小时内就能搞定。整个过程非常清晰，主要就是四步：去阿里云开通服务拿钥匙（API-KEY）、在SpringBoot项目里引入官方SDK、进行简单的配置、最后写一个控制器来处理对话请求。下面，我就把这套经过实战检验的“组合拳”详细拆解给你看，保证每一步都有手把手的代码和配置，哪怕你之前没接触过AI模型接入，也能跟着做出来。

2. 第一步：获取通行证——开通DashScope并创建API-KEY

任何第三方服务的集成，第一步永远是身份认证。对于通义千问来说，这个“通行证”就是阿里云灵积平台（DashScope）的API-KEY。你可以把DashScope理解为一个AI模型超市，而通义千问是里面一个非常受欢迎的商品，API-KEY就是你在这个超市的会员卡和支付凭证。

首先，你需要有一个阿里云账号。如果没有，去阿里云官网用手机号注册一个，这个过程和注册普通网站没什么区别。登录之后，在控制台首页的搜索框里直接输入“DashScope”或者“灵积”，就能找到入口。点击进入灵积（DashScope）的管理控制台。

第一次进入，系统可能会提示你开通服务。这个开通是免费的，主要是同意一些服务协议，并不会立即产生费用。阿里云为新用户提供了相当慷慨的免费额度，足够你进行大量的测试和初步体验。开通成功后，页面会跳转到控制台总览。

接下来就是生成API-KEY了。通常在控制台左侧菜单栏能找到“API-KEY管理”或类似的选项。点击“创建API-KEY”，系统会生成一串以“sk-”开头的密钥字符串。这里有个非常重要的注意事项：这串密钥只会显示一次！ 你必须立刻把它复制并保存到安全的地方，比如本地电脑的加密文档或者专业的密码管理工具里。关闭页面后，你就再也看不到完整的密钥了，只能重新创建新的。我建议你直接为这个密钥起个名字，比如“SpringBoot测试专用”，方便后续管理。

拿到这串“sk-”开头的密钥后，前期准备工作就完成了。你可以先把它保存在记事本里，我们马上就会在SpringBoot项目里用到它。

3. 第二步：搭建舞台——创建SpringBoot项目并引入SDK

有了通行证，接下来我们得准备一个“舞台”来使用它。这里我假设你已经有基本的SpringBoot开发环境（JDK 8+、Maven或Gradle、以及IDEA或Eclipse等IDE）。如果还没有，网上搜索“SpringBoot快速启动”会有大量教程，十分钟就能搭好。

打开你的IDE，创建一个新的SpringBoot项目。在通过Spring Initializr创建时，选择常用的依赖就行，比如Spring Web（我们要写Web接口）、Lombok（简化代码，可选但推荐）。项目创建好后，我们打开最重要的pom.xml文件，来添加阿里云DashScope的官方SDK依赖。

官方SDK的Maven坐标很容易找到。在你的pom.xml文件的<dependencies>部分，加入下面这段依赖声明。我写这篇文章时最新的稳定版本是2.14.0，你可以去Maven中央仓库确认一下是否有更新。

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

添加依赖后，IDE通常会提示你重新加载Maven项目。点击加载，确保依赖被成功下载到本地仓库，没有出现红色的报错。这一步相当于给我们的项目安装了与通义千问模型“对话”的官方语言包，所有复杂的网络通信、数据封装逻辑，SDK都帮我们封装好了。

4. 第三步：配置密钥——安全地管理你的API-KEY

直接把API-KEY硬编码在Java代码里是绝对不推荐的坏习惯，既不利于安全（代码泄露即密钥泄露），也不利于维护（更换密钥需要重新编译）。SpringBoot给我们提供了优雅的配置管理方式，通常我们会把这类敏感信息放在application.yml或application.properties配置文件中。

我更喜欢用application.yml，因为结构更清晰。在项目的src/main/resources/目录下，找到或创建application.yml文件，添加如下配置：

# 通义千问配置
ai:
  api-key: sk-你的真实API密钥在这里

注意，这里的ai.api-key是我自定义的配置项路径，你可以根据自己项目的规范来命名，比如dashscope.api-key也行。关键是要把sk-开头的那个密钥字符串替换进去。再次强调，这个配置文件如果会上传到Git等版本控制系统，务必将其添加到.gitignore文件中，或者使用环境变量来注入密钥，防止敏感信息泄露。 一种更专业的做法是：

ai:
  api-key: ${AI_API_KEY:sk-defaultKey} # 优先从环境变量AI_API_KEY读取，没有则使用默认值（仅用于本地测试）

这样，在生产环境中，你可以在服务器上设置AI_API_KEY这个环境变量，而无需在配置文件中写明真实密钥。

接下来，我们需要创建一个配置类（@Configuration），来告诉Spring如何将SDK的核心对象Generation纳入容器管理，并注入我们配置好的API-KEY。新建一个类，例如AliAiConfig：

package com.yourproject.config;

import com.alibaba.dashscope.aigc.generation.Generation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AliAiConfig {

    @Value("${ai.api-key}")
    private String apiKey;

    @Bean
    public Generation generation() {
        // 通常情况下，Generation实例本身是无状态的，API-KEY会在每次调用时通过参数传入。
        // 这里我们简单地创建一个实例交给Spring管理即可。
        return new Generation();
    }
}

这个配置类的作用是，当SpringBoot应用启动时，它会自动创建一个Generation类型的Bean（你可以把它想象成SDK提供的一个对话工具），并放在Spring的“工具箱”里，这样我们在任何需要的地方都能直接拿来用。而@Value("${ai.api-key}")这行代码，就是Spring的“魔法”，它会自动从我们刚才写的application.yml里，把对应的密钥值取出来，赋值给apiKey这个变量。虽然在这个简单的配置里我们没有直接用它初始化Generation，但我们可以随时在别处注入这个值。

5. 第四步：编写核心对话接口

舞台和工具都准备好了，现在我们来编写最核心的部分——接收用户问题、调用通义千问模型、并返回智能回复的Web接口。我们会在Controller层实现这个功能。

首先，我们来规划一下这个接口。它应该是一个POST请求，因为我们需要向服务器发送一段文本（用户的问题）。请求路径可以定为/ai/chat。接收的参数就是用户输入的字符串。返回的结果也是模型生成的文本字符串。下面我们来看具体的代码实现，我会逐段加上详细的注释。

package com.yourproject.controller;

import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.Arrays;

@RestController
@RequestMapping("/ai")
public class AiChatController {

    // 注入配置文件中的API-KEY
    @Value("${ai.api-key}")
    private String apiKey;

    // 注入Spring容器中我们配置好的Generation工具
    @Resource
    private Generation generation;

    @PostMapping("/chat")
    public String chatWithQwen(@RequestBody String userInput) throws NoApiKeyException, InputRequiredException {
        // 1. 构建用户消息
        // Message对象代表对话中的一条消息，需要指定角色（Role）和内容（Content）
        // Role.USER 代表这条消息来自用户
        Message userMessage = Message.builder()
                .role(Role.USER.getValue()) // 角色设为“用户”
                .content(userInput)         // 内容就是前端传过来的用户输入
                .build();

        // 2. 构建调用模型的参数
        GenerationParam param = GenerationParam.builder()
                .model("qwen-turbo") // 指定使用通义千问的Turbo模型，响应速度快，性价比高
                .messages(Arrays.asList(userMessage)) // 将用户消息放入消息列表。这里只放了一条，实际可放多轮对话历史
                .topP(0.8) // 核采样参数，影响生成文本的随机性。值越大（越接近1），回答越多样、有创意；值越小，回答越确定、保守。0.8是个常用值。
                .apiKey(apiKey) // 最关键的一步：传入我们的API-KEY进行鉴权
                .build();

        // 3. 调用模型并获取结果
        GenerationResult result = generation.call(param);

        // 4. 从结果中提取模型返回的文本内容
        // 返回结果结构较复杂，我们需要层层取出最终的回复文本
        String aiReply = result.getOutput()
                .getChoices()
                .get(0)          // 获取第一个（通常也是唯一一个）回复选择
                .getMessage()    // 获取该选择中的消息对象
                .getContent();   // 最终获取消息的文本内容

        return aiReply;
    }
}

这段代码虽然不长，但包含了完整的交互逻辑。我解释几个关键点：GenerationParam是调用请求的“配置单”，model字段指定你要用哪个模型，除了qwen-turbo，DashScope还提供了qwen-plus（能力更强）、qwen-max（最新最强）等，你可以根据需求更换。topP参数是控制生成文本“创意度”的旋钮，如果你希望回答更严谨、少些天马行空，可以把它调低，比如0.5。

5.1 进阶功能：让对话拥有记忆

上面的例子是一个简单的单轮对话。但真正的智能对话往往需要上下文记忆，比如你问“李白是谁？”，接着问“他写过哪些诗？”，模型需要记住前文提到的“李白”才能正确回答第二个问题。实现多轮对话也很简单，核心就是维护一个Message列表，而不仅仅是最后一条用户消息。

我们可以稍微改造一下Controller，假设我们通过一个简单的会话ID来在服务端内存中维护对话历史（生产环境建议用Redis等持久化存储）：

// 引入一个线程安全的Map来临时存储对话历史（仅为示例，生产环境需优化）
import java.util.concurrent.ConcurrentHashMap;

public class AiChatController {
    // ... 省略之前的注入字段 ...

    private ConcurrentHashMap<String, List<Message>> sessionHistory = new ConcurrentHashMap<>();

    @PostMapping("/chatWithHistory")
    public String chatWithHistory(@RequestParam String sessionId, @RequestBody String userInput) throws NoApiKeyException, InputRequiredException {
        // 获取或创建该会话的历史记录
        List<Message> history = sessionHistory.getOrDefault(sessionId, new ArrayList<>());

        // 将新的用户消息加入历史
        Message userMessage = Message.builder().role(Role.USER.getValue()).content(userInput).build();
        history.add(userMessage);

        // 构建参数时，传入整个历史消息列表，而不仅仅是最后一条
        GenerationParam param = GenerationParam.builder()
                .model("qwen-turbo")
                .messages(history) // 关键变化：传入整个历史列表
                .topP(0.8)
                .apiKey(apiKey)
                .build();

        GenerationResult result = generation.call(param);
        String aiReply = result.getOutput().getChoices().get(0).getMessage().getContent();

        // 将模型的回复也加入历史，为下一轮对话做准备
        Message assistantMessage = Message.builder().role(Role.ASSISTANT.getValue()).content(aiReply).build();
        history.add(assistantMessage);

        // 更新会话历史
        sessionHistory.put(sessionId, history);

        return aiReply;
    }
}

这样，只要前端在每次请求时传递同一个sessionId，模型就能根据之前的所有对话内容进行回复，实现有记忆的连续聊天。当然，历史列表不能无限增长，通常需要设定一个最大轮次或最大token数，避免超出模型上下文长度限制和增加不必要的费用。

6. 第五步：运行与测试——见证智能时刻

代码写完了，最后一步就是启动项目并进行测试。在IDE中找到你的主启动类（通常带有@SpringBootApplication注解），直接运行它。看到控制台输出熟悉的Spring Boot图案和端口号（默认8080）信息，没有报错，就说明启动成功了。

测试接口我最喜欢用Postman，当然你用Curl命令行或者直接写个前端页面来调用也行。打开Postman，创建一个新的POST请求，地址填http://localhost:8080/ai/chat。在Body标签页选择raw，格式选JSON，然后输入：

"你好，请介绍一下你自己"

点击发送。如果一切配置正确，你应该能在几秒内收到来自通义千问模型的回复，内容可能是：“你好！我是通义千问，由阿里云开发的大语言模型……” 恭喜你，你的第一个智能对话接口已经成功跑通了！

如果遇到错误，别慌，这是学习过程的一部分。最常见的错误是401或403，这几乎肯定是API-KEY有问题：可能是没复制全、包含了空格、或者还没在阿里云控制台开通服务。请回头仔细检查第一步。如果是连接超时，检查一下网络环境。SDK的异常信息通常比较明确，根据提示排查即可。

7. 参数调优与生产环境考量

基础功能跑通后，为了获得更好的效果和更稳定的服务，我们还需要关注一些重要的参数和工程化实践。

模型选择：qwen-turbo适合对响应速度要求高、成本敏感的场景。如果你的应用需要更强的推理、创作或复杂指令跟随能力，可以尝试切换到qwen-plus或qwen-max，只需修改GenerationParam中的model参数即可。不同模型的计费标准也不同，可以在DashScope控制台的定价页面查看。

生成参数调优：除了topP，另一个关键参数是temperature（在SDK中可能通过其他方式设置，具体查看最新文档），它同样控制随机性。简单理解，temperature越高，输出越随机、有创意；越低，输出越聚焦、可预测。对于客服、知识问答这类需要准确性的场景，建议设低一些（如0.1-0.3）；对于创意写作、头脑风暴，可以设高一些（如0.7-0.9）。

启用联网搜索：通义千问模型支持在调用时联网搜索最新信息。这在GenerationParam中可以通过.enableSearch(true)来开启。开启后，模型在回答某些问题时（尤其是实时性强的，如“今天天气如何”），会尝试参考网络搜索结果。但要注意，模型会自行判断是否使用以及如何使用搜索结果，且此功能可能会增加调用耗时和成本。

生产环境部署：

1. 密钥安全：务必使用环境变量或配置中心（如Nacos、Apollo）来管理API-KEY，绝不能提交到代码仓库。
2. 超时与重试：网络调用总有不稳定的时候。在服务间调用时，务必设置合理的连接超时和读取超时时间，并考虑增加重试机制（注意对非幂等操作要谨慎）。
3. 限流与降级：你的应用可能会面临突发流量。一方面，要关注DashScope服务本身的速率限制；另一方面，在你的SpringBoot应用层面，也要考虑使用Sentinel等工具对AI接口做限流，并在服务不可用时（如额度耗尽、API故障）有降级方案，比如返回一个友好的提示，而不是让整个功能崩溃。
4. 日志与监控：记录每一次调用的请求、响应（注意脱敏，不要记录完整的问答内容）、耗时和状态。这不仅能帮助排查问题，还能分析使用情况，优化成本。

踩过几次坑之后，我的经验是，在正式上线前，最好用一批涵盖各种场景的测试问题对接口进行一轮完整的测试，观察回复质量和稳定性。同时，在代码中做好异常捕获，给前端返回结构化的错误信息，而不是一堆Java异常栈，用户体验会好很多。SpringBoot整合通义千问，入门确实简单，但要想做得稳健、好用，在这些细节上多花点心思是非常值得的。