Spring Boot 集成硅基流动免费Qwen大模型实战——从零搭建支持多轮对话的网页应用

大模型应用正快速走进日常开发，但对很多同学来说，『如何在一个普通 Spring Boot 项目里真正调通一个大模型接口』依然是第一步的门槛。本文以硅基流动（SiliconFlow）平台的免费模型 Qwen/Qwen2.5-7B-Instruct 为例，手把手带你从零搭建一个支持多轮会话的网页对话应用，所有代码均可直接复制运行。

读完本文你将掌握：如何用 Spring Boot 调用 OpenAI 兼容接口、如何设计多轮对话的上下文管理、以及如何用 Thymeleaf 快速做出可用的聊天界面。

一、为什么选择硅基流动

硅基流动是国内一家提供大模型推理 API 的云平台，对开发者非常友好：

免费额度：新用户注册即送额度，Qwen2.5-7B-Instruct 等模型可免费试用，适合学习与做 Demo，如果只是想验证大模型的能力，并不想直接部署一个大模型或者真的去购买千问的或最新Kimi的最新能力，那么我们完全可以使用公开部署的免费模型；

OpenAI 兼容：接口与 OpenAI 的 /v1/chat/completions 完全一致，代码可直接复用，迁移成本低；
模型丰富：除 Qwen 系列外，还提供 DeepSeek、GLM、Llama 等多种开源模型，按需切换即可；

国内访问稳定：无需科学上网，延迟低，文档与控制台均为中文。

二、如何申请账号

如果不想自己搭建本地大模型，也不想只体验一种大模型，那么完全可以使用硅基流动这种私有化了很多种常见大模型的网站平台，助力你的AI应用。本节将来介绍一下如何注册申请账号以及申请key。

1、注册账号

硅基流动的网页地址如下：硅基流动注册地址，输入地址后，在相应的页面中输入必要的信息完整注册即可。

2、实名认证

注册成功后，在系统中需要进行实名认证，界面如下：

按照网站的要求进行认证即可。

3、分配秘钥

与OpenAI一样，要想在外部平台集成硅基流动中的模型，也需要分配key，然后在自己的应用程序中进行配置使用。管理界面如下：

输入信息描述之后，点击新建就可以完成信key的创建，一定要注意的是，这里创建的key一定妥善保管，不要泄露给第三方。经过以上的步骤后就可以进入下一步，调用硅基流动中的大模型了。

三、环境准备

JDK 17 及以上（本文基于 Java 17）
Maven 3.6 及以上
一个硅基流动 API Key
任意 IDE（IntelliJ IDEA / Eclipse）或者AI编辑器，比如CodeBuddy或者Trae都可以。

1、创建项目与引入依赖

新建一个 Maven 项目，只需要 Web、Thymeleaf 两个起步依赖即可。核心 pom.xml 如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>siliconflow-qwen-demo</artifactId>
    <version>1.0.0</version>
    <name>siliconflow-qwen-demo</name>
    <description>Spring Boot + Thymeleaf demo for SiliconFlow Qwen2.5-7B-Instruct chat</description>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

这里无需额外引入 OKHttp 或 OpenAI 的 SDK，我们直接使用Spring 自带的 RestClient 已经足够好用。

2、配置 application.yml

接下来把模型名、接口地址和密钥放到配置文件中，密钥建议用环境变量注入，避免硬编码进代码仓库，这里为了演示简单，直接将密钥拷贝到配置文件中：

server:
  port: 8080

spring:
  application:
    name: siliconflow-qwen-demo
  thymeleaf:
    cache: false
    encoding: UTF-8
    mode: HTML

# 硅基流动配置
siliconflow:
  # 在 https://cloud.siliconflow.cn 注册后，于“API密钥”页面生成
  api:
    #key: 在此填入你的SiliconFlow_API_Key
    key: your_key
    url: https://api.siliconflow.cn/v1/chat/completions
  # 使用的模型
  model: Qwen/Qwen2.5-7B-Instruct
  temperature: 0.7
  max-tokens: 2048

3、定义数据模型

硅基流动的请求/响应是标准的 OpenAI 格式，我们先定义三个实体类。

3.1. 消息实体 ChatMessage

public class ChatMessage {
    private String role;    // user / assistant / system
    private String content;
    // 省略构造方法、getter/setter
}

3.2. 请求体 ChatRequest

public class ChatRequest {
    private String model;
    private List<ChatMessage> messages;
    private Double temperature;
    private Integer max_tokens;
    private Boolean stream;
    // 省略构造方法、getter/setter
}

3.3. 响应体 ChatResponse

public class ChatResponse {
    private List<Choice> choices;
    public static class Choice {
        private ChatMessage message;
        // getter/setter
    }
    // getter/setter
}

四、封装调用服务

本节将重点介绍如何进行服务调用以及如何实现控制器和多轮会话的管理。核心逻辑：把完整对话历史组装成请求，POST 到硅基流动接口，取回模型回复。其中 @Value 注入的 temperature 和 maxTokens 即为采样参数。

@Service
public class SiliconFlowService {
    private final RestClient restClient = RestClient.create();
    @Value("${siliconflow.api.key}")
    private String apiKey;
    @Value("${siliconflow.api.url}")
    private String apiUrl;
    @Value("${siliconflow.model}")
    private String model;
    @Value("${siliconflow.temperature:0.7}")
    private Double temperature;
    @Value("${siliconflow.max-tokens:2048}")
    private Integer maxTokens;
    public String chat(List<ChatMessage> messages) {
        ChatRequest request = new ChatRequest(model, messages, temperature, maxTokens, false);
        ChatResponse response = restClient.post()
                .uri(apiUrl)
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .body(request)
                .retrieve()
                .body(ChatResponse.class);
        return response.getChoices().get(0).getMessage().getContent();
    }
}

1、控制器与多轮会话管理

多轮对话的关键，是把『历史消息』保存下来。最简单稳妥的做法是用 HttpSession：每个浏览器会话独立保存一份消息列表，每次请求都带着完整历史发给模型，模型便能『记住』上下文。

@RestController
@RequestMapping("/api")
public class ChatController {
    private static final String HISTORY_KEY = "chatHistory";
    private static final String SYSTEM_PROMPT = "你是一个有帮助的、友好的中文智能助手。";
    @PostMapping("/chat")
    public ResponseEntity<Map<String, Object>> chat(@RequestBody ChatInput input, HttpSession session) {
        List<ChatMessage> history = getOrInitHistory(session);   // 取出历史
        history.add(new ChatMessage("user", input.message()));  // 追加用户消息
        String reply = siliconFlowService.chat(history);        // 调用模型
        history.add(new ChatMessage("assistant", reply));       // 追加助手回复
        return ResponseEntity.ok(Map.of("reply", reply));
    }

    @PostMapping("/reset")
    public ResponseEntity<Map<String, String>> reset(HttpSession session) {
        // 清空历史，仅保留 system 提示词
        session.setAttribute(HISTORY_KEY, List.of(new ChatMessage("system", SYSTEM_PROMPT)));
        return ResponseEntity.ok(Map.of("status", "ok"));
    }
}

多轮原理一句话总结：用户消息 → 进历史 → 调模型（带全量历史）→ 助手回复进历史 → 下一轮继续。会话历史在服务端，前端无需关心。

2、Thymeleaf 聊天页面

页面用纯 JavaScript 通过 fetch 调用 /api/chat，拿到回复后动态追加到对话区，无需任何前端框架：

async function sendMessage() {
  const text = inputEl.value.trim();
  if (!text) return;
  appendMessage("user", text);
  inputEl.value = "";
  const typing = appendMessage("assistant", "正在思考...");
  const resp = await fetch("/api/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message: text })
  });
  const data = await resp.json();
  typing.textContent = data.reply;
}

完整的 HTML/CSS 已包含在示例工程中（templates/chat.html），含消息气泡样式、Enter 发送、清空会话按钮等。

3、运行与测试

方式一：编辑 application.yml 填入真实 API Key；
方式二（推荐）：用环境变量覆盖，避免密钥入库 —— Windows(PowerShell): $env:SILICONFLOW_API_KEY="你的Key"
启动：mvn spring-boot:run
浏览器打开 http://localhost:8080 即可多轮对话

完整演示录屏如下：

SpringBoot集成硅基流动Qwen2.5-7B大模型

4、temperature 与 max_tokens 参数详解

这两个是调用大模型时最高频、也最影响效果的两个参数，结合本项目代码重点说明：

参数	控制什么	调小效果	调大效果
temperature	输出随机性/创造性	更确定、保守、可复现（适合代码/事实问答）	更发散、有创意、易出错（适合闲聊/写作）
max_tokens	单次回复最大长度	回答更短、可能被截断	可输出更长、占更多资源

补充说明：

temperature 常用区间 0~1.2，本项目默认 0.7，兼顾稳定与灵动；
max_tokens 是『输出』上限，而非上下文总窗口（Qwen2.5-7B 上下文约 32K），长对话要预留输入余量；
硅基流动接口中 temperature 与 top_p 通常二选一调整，不要同时大幅改动。

5、生产环境进阶建议

上下文截断：当前示例把全量历史发给模型，轮次多了会超出窗口。可按 token 预算保留最近 N 轮或摘要旧消息；
流式输出：将 stream 设为 true，用 SSE/WebFlux 逐字返回，体验更接近官方聊天；
密钥安全：密钥务必走环境变量或配置中心，禁止提交到 Git；
容错与重试：对接口超时、限流（429）增加重试与降级提示；
多用户隔离：HttpSession 已按会话隔离，集群部署需配合 Spring Session + Redis。

五、总结

通过本文我们就已经实现用 Spring Boot + Thymeleaf 完整跑通了硅基流动的免费 Qwen 模型，并实现了服务端维护历史的多轮对话。核心只有三步：定义 OpenAI 兼容的数据模型、用 RestClient 封装一次接口调用、用 HttpSession 保存多轮上下文。在此基础上，流式输出、上下文管理、多模型切换都可以平滑扩展。行文仓促，定有不足之处，欢迎各位朋友在评论区批评指正，不胜感激。

亚马逊云科技技术品牌专区

更多推荐

百万Token不是数字游戏：Kimi K3完整吞下10万行代码库后，我测出了它的真实理解力

亚马逊云科技技术品牌专区

洛雪音乐音源终极指南：免费获取全网无损音乐的完整方案

洛雪音乐音源项目为音乐爱好者提供了一个强大的开源解决方案，通过社区维护的多样化音源配置，让用户能够免费获取QQ音乐、网易云、酷狗、酷我、咪咕五大平台的音乐资源。这个项目不仅支持跨平台音乐聚合，还提供了无损音乐配置方案，确保用户能够享受到高品质的音频体验。## 🎯 为什么选择洛雪音乐音源？**核心优势解析**洛雪音乐音源项目经过多次测试和迭代，已经成为目前最稳定、最全面的开源音乐聚合方

亚马逊云科技技术品牌专区

为什么选择Warcraft Font Merger？轻量、快速、多功能的字体工具解析

Warcraft Font Merger是一款专为魔兽世界玩家打造的字体合并与补全工具，它能够帮助玩家轻松解决游戏中的字体显示问题，让游戏界面更加美观、易读。无论是中文显示乱码，还是特殊符号缺失，这款工具都能提供高效的解决方案。## 一、轻量级设计，不占用过多系统资源Warcraft Font Merger采用轻量级架构，整个工具包体积小巧，不会占用过多的硬盘空间和系统内存。这意味着即使在