通义千问1.5-1.8B-Chat-GPTQ-Int4 Java开发集成SpringBoot项目实战指南最近在帮一个朋友做项目他们想在自己的Java应用里加个智能对话功能看中了通义千问1.5-1.8B-Chat-GPTQ-Int4这个模型。这模型挺有意思的体积小但能力不弱特别适合在资源有限的环境里跑。朋友那边技术栈主要是SpringBoot问我怎么把这模型服务接进去。我琢磨了一下发现网上关于Java集成的完整例子还真不多大部分都是Python的。所以今天我就把当时折腾的过程和最后跑通的方案整理出来如果你也在用SpringBoot想快速给应用加上AI对话能力这篇应该能帮上忙。咱们不聊那些复杂的模型原理就聚焦一件事怎么在一个现成的SpringBoot项目里写几行Java代码就能调用部署好的通义千问模型服务并且处理得稳定可靠。我会把用到的Maven依赖、HTTP客户端的配置、请求响应的封装、还有异常处理这些关键环节都讲清楚最后给出一套可以直接拿来用的代码。1. 准备工作与环境假设在开始写代码之前咱们得先明确几个前提。这样你对照着自己的环境就知道从哪里开始了。首先你得有一个已经部署好的通义千问1.5-1.8B-Chat-GPTQ-Int4模型服务。这个服务通常是通过一些AI框架部署的会提供一个HTTP接口。我们Java这边不需要关心模型本身是怎么跑的只需要知道这个接口的地址比如http://localhost:8000/v1/chat/completions以及它接受什么样的数据格式。一般来说这类服务都兼容OpenAI的API格式这会让我们的集成工作简单很多。其次你的开发环境应该是一个标准的SpringBoot项目我用的是SpringBoot 2.7.x 版本JDK 11。项目管理工具是Maven。如果你用的是Gradle或者更新的SpringBoot 3.x整体思路是一样的只是依赖声明和少量配置的写法可能需要调整。最后我们这次集成的核心目标是构建一个稳定、易用的Java客户端让业务代码能像调用普通服务一样简单地向模型发送问题并拿到回答。2. 项目依赖与基础配置万事开头难但配置依赖不算难。我们主要需要两个库一个用来处理HTTP请求一个用来方便地处理JSON数据。2.1 添加Maven依赖打开你的pom.xml文件在dependencies部分加入下面这些内容。我比较推荐使用OkHttp作为HTTP客户端它比Spring自带的RestTemplate更轻量、配置更灵活。JSON处理则用Jackson这是SpringBoot的默认选择用起来很顺手。dependencies !-- SpringBoot Web Starter (已经包含Jackson) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- OkHttp3 作为HTTP客户端 -- dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.11.0/version !-- 请使用当前稳定版本 -- /dependency !-- 用于OkHttp的连接池和日志拦截器可选但推荐 -- dependency groupIdcom.squareup.okhttp3/groupId artifactIdlogging-interceptor/artifactId version4.11.0/version /dependency !-- 配置属性绑定 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-configuration-processor/artifactId optionaltrue/optional /dependency /dependencies2.2 配置模型服务连接信息接下来我们把模型服务的地址、超时时间这些配置项放到application.yml(或application.properties) 文件里。这样做的好处是以后换环境或者改地址不用动代码改下配置就行。# application.yml qwen: model: # 通义千问模型服务的API地址 base-url: http://localhost:8000/v1 # 请求超时时间毫秒 connect-timeout: 10000 read-timeout: 60000 write-timeout: 10000 # 是否启用请求/响应日志调试用 logging-enabled: true然后我们创建一个配置类来读取这些属性并初始化OkHttpClient实例。这个Client会被注入到Spring容器中供其他地方使用。package com.example.ai.config; import lombok.Data; import okhttp3.OkHttpClient; import okhttp3.logging.HttpLoggingInterceptor; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import java.util.concurrent.TimeUnit; Configuration ConfigurationProperties(prefix qwen.model) Data public class QwenModelConfig { private String baseUrl; private Integer connectTimeout 10000; private Integer readTimeout 60000; private Integer writeTimeout 10000; private Boolean loggingEnabled false; Bean public OkHttpClient okHttpClient() { OkHttpClient.Builder builder new OkHttpClient.Builder() .connectTimeout(connectTimeout, TimeUnit.MILLISECONDS) .readTimeout(readTimeout, TimeUnit.MILLISECONDS) .writeTimeout(writeTimeout, TimeUnit.MILLISECONDS); // 如果需要查看详细的HTTP请求日志可以添加日志拦截器 if (Boolean.TRUE.equals(loggingEnabled)) { HttpLoggingInterceptor loggingInterceptor new HttpLoggingInterceptor(); loggingInterceptor.setLevel(HttpLoggingInterceptor.Level.BODY); builder.addInterceptor(loggingInterceptor); } return builder.build(); } }注意这里用了Lombok的Data注解来简化getter/setter如果你项目没引入Lombok需要自己生成这些方法。到这一步基础设施就搭好了。3. 定义请求与响应数据结构和模型服务对话本质上就是发送一个结构化的JSON请求然后接收一个结构化的JSON响应。我们先定义好Java类来对应这些结构。3.1 封装请求消息一次对话通常包含一个消息列表。每个消息都有角色比如“用户”或“助手”和内容。我们按照OpenAI的格式来定义。package com.example.ai.model; import com.fasterxml.jackson.annotation.JsonProperty; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor; Data Builder NoArgsConstructor AllArgsConstructor public class ChatMessage { /** * 消息角色例如 user 或 assistant */ private String role; /** * 消息内容 */ private String content; }3.2 封装完整请求体接下来是完整的请求体它包含消息列表、模型名称虽然服务端可能已经固定但传一下更规范以及其他可调参数。package com.example.ai.model; import com.fasterxml.jackson.annotation.JsonInclude; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor; import java.util.List; Data Builder NoArgsConstructor AllArgsConstructor JsonInclude(JsonInclude.Include.NON_NULL) // 序列化时忽略null字段 public class ChatCompletionRequest { /** * 模型名称例如 qwen1.5-1.8b-chat-gptq-int4 */ private String model; /** * 对话消息列表 */ private ListChatMessage messages; /** * 生成文本的最大token数 */ Builder.Default private Integer maxTokens 2048; /** * 温度参数控制随机性 (0.0 ~ 2.0) */ Builder.Default private Double temperature 0.8; /** * 是否流式输出本次我们先实现非流式 */ Builder.Default private Boolean stream false; }3.3 封装响应体最后是响应体。我们主要关心返回的消息内容以及一些元数据如token消耗。package com.example.ai.model; import com.fasterxml.jackson.annotation.JsonProperty; import lombok.Data; import java.util.List; Data public class ChatCompletionResponse { /** * 响应ID */ private String id; /** * 响应对象类型通常是 chat.completion */ private String object; /** * 创建时间戳 */ private Long created; /** * 模型名称 */ private String model; /** * 返回的选择列表通常只有一个 */ private ListChoice choices; /** * token使用情况统计 */ private Usage usage; Data public static class Choice { /** * 返回的索引 */ private Integer index; /** * 返回的消息 */ private ChatMessage message; /** * 结束原因如 stop 或 length */ JsonProperty(finish_reason) private String finishReason; } Data public static class Usage { /** * 提示词消耗的token数 */ JsonProperty(prompt_tokens) private Integer promptTokens; /** * 补全内容消耗的token数 */ JsonProperty(completion_tokens) private Integer completionTokens; /** * 总消耗token数 */ JsonProperty(total_tokens) private Integer totalTokens; } /** * 一个便捷方法快速获取第一条回复的文本内容 */ public String getFirstMessageContent() { if (choices ! null !choices.isEmpty() choices.get(0).getMessage() ! null) { return choices.get(0).getMessage().getContent(); } return null; } }数据结构定义好了就像我们和模型服务之间约好了沟通的语言。4. 实现核心服务层现在进入最核心的部分写一个服务类用我们配置好的OkHttpClient去真正地调用模型API。4.1 构建服务类与请求方法我们创建一个QwenAIService它负责组装请求、发送HTTP调用、解析响应。package com.example.ai.service; import com.example.ai.config.QwenModelConfig; import com.example.ai.model.ChatCompletionRequest; import com.example.ai.model.ChatCompletionResponse; import com.fasterxml.jackson.databind.ObjectMapper; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import okhttp3.*; import org.springframework.stereotype.Service; import java.io.IOException; Slf4j Service RequiredArgsConstructor public class QwenAIService { private static final MediaType JSON MediaType.get(application/json; charsetutf-8); private static final String CHAT_COMPLETION_PATH /chat/completions; private final OkHttpClient okHttpClient; private final QwenModelConfig modelConfig; private final ObjectMapper objectMapper; // Spring Boot会自动注入 /** * 同步调用通义千问聊天补全接口 * * param request 聊天请求体 * return 聊天响应体 * throws IOException 当网络通信或JSON解析出错时抛出 */ public ChatCompletionResponse chatCompletion(ChatCompletionRequest request) throws IOException { // 1. 构建完整的请求URL String url modelConfig.getBaseUrl() CHAT_COMPLETION_PATH; // 2. 将请求对象序列化为JSON字符串 String requestBodyJson objectMapper.writeValueAsString(request); log.debug(Sending request to Qwen AI: {}, requestBodyJson); // 3. 构建OkHttp请求 Request httpRequest new Request.Builder() .url(url) .post(RequestBody.create(requestBodyJson, JSON)) .build(); // 4. 执行同步调用 try (Response response okHttpClient.newCall(httpRequest).execute()) { if (!response.isSuccessful()) { String errorBody response.body() ! null ? response.body().string() : null; log.error(Qwen AI API call failed. Code: {}, Body: {}, response.code(), errorBody); throw new IOException(API call failed with code: response.code() , body: errorBody); } // 5. 解析响应体 if (response.body() ! null) { String responseBody response.body().string(); log.debug(Received response from Qwen AI: {}, responseBody); return objectMapper.readValue(responseBody, ChatCompletionResponse.class); } else { throw new IOException(Response body is null); } } } /** * 一个更便捷的方法直接发送用户消息并获取助手回复文本 * * param userMessage 用户消息内容 * return 助手回复的文本内容 */ public String chat(String userMessage) throws IOException { ChatCompletionRequest request ChatCompletionRequest.builder() .model(qwen1.5-1.8b-chat-gptq-int4) // 模型名称按需填写 .messages(List.of( ChatMessage.builder().role(user).content(userMessage).build() )) .build(); ChatCompletionResponse response chatCompletion(request); return response.getFirstMessageContent(); } }这个服务类提供了两个主要方法。chatCompletion方法比较通用可以传入完整的请求对象chat方法则更简单你只需要传入用户的问题字符串它就直接返回助手的回答文本。4.2 添加异步调用支持同步调用在Web场景下可能会阻塞线程影响性能。我们可以很容易地增加一个异步版本利用OkHttp自带的回调机制。/** * 异步调用通义千问聊天补全接口 * * param request 聊天请求体 * param callback 异步回调处理成功或失败结果 */ public void chatCompletionAsync(ChatCompletionRequest request, Callback callback) { String url modelConfig.getBaseUrl() CHAT_COMPLETION_PATH; try { String requestBodyJson objectMapper.writeValueAsString(request); Request httpRequest new Request.Builder() .url(url) .post(RequestBody.create(requestBodyJson, JSON)) .build(); okHttpClient.newCall(httpRequest).enqueue(callback); } catch (Exception e) { // 如果JSON序列化出错直接回调失败 callback.onFailure(null, new IOException(Failed to build request, e)); } }使用异步调用时你需要自己实现okhttp3.Callback接口来处理响应或错误。这在处理高并发请求时非常有用。5. 增强稳定性异常处理与重试机制网络请求总有可能失败可能是服务暂时不可用也可能是网络波动。为了提高集成的鲁棒性我们需要加上重试机制。这里我推荐使用Spring Retry它用注解的方式就能实现非常优雅。5.1 添加Spring Retry依赖首先在pom.xml里加上依赖。dependency groupIdorg.springframework.retry/groupId artifactIdspring-retry/artifactId /dependency dependency groupIdorg.springframework/groupId artifactIdspring-aspects/artifactId /dependency然后在你的主启动类或者一个配置类上加上EnableRetry注解来启用重试功能。SpringBootApplication EnableRetry // 启用Spring Retry public class YourApplication { public static void main(String[] args) { SpringApplication.run(YourApplication.class, args); } }5.2 在服务方法上应用重试现在我们可以修改chatCompletion方法为它加上重试逻辑。比如当发生IOException时我们重试3次每次间隔1秒。import org.springframework.retry.annotation.Backoff; import org.springframework.retry.annotation.Retryable; Retryable( value {IOException.class}, // 针对哪些异常进行重试 maxAttempts 3, // 最大重试次数包含第一次调用 backoff Backoff(delay 1000) // 重试间隔1秒 ) public ChatCompletionResponse chatCompletion(ChatCompletionRequest request) throws IOException { // ... 方法体保持不变 ... }这样一旦调用失败Spring Retry会自动帮我们重试最多3次。如果重试后仍然失败异常才会最终抛出来。你还可以配置更复杂的退避策略比如指数退避。5.3 全局异常处理建议除了重试我们最好还能在Controller层统一处理这些异常给前端返回友好的错误信息。可以创建一个全局异常处理器。package com.example.ai.controller.advice; import lombok.extern.slf4j.Slf4j; import org.springframework.http.HttpStatus; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.ResponseStatus; import org.springframework.web.bind.annotation.RestControllerAdvice; import java.io.IOException; import java.util.HashMap; import java.util.Map; Slf4j RestControllerAdvice public class GlobalExceptionHandler { ExceptionHandler(IOException.class) ResponseStatus(HttpStatus.BAD_GATEWAY) // 502 Bad Gateway public MapString, Object handleIOException(IOException e) { log.error(调用AI服务时发生IO异常, e); MapString, Object error new HashMap(); error.put(code, 502); error.put(message, AI服务暂时不可用请稍后重试); error.put(detail, e.getMessage()); return error; } // 可以添加其他异常的处理... }6. 快速测试与使用示例所有代码都写好了我们来写个简单的Controller测试一下看看整个流程能不能跑通。6.1 创建一个测试用的Controllerpackage com.example.ai.controller; import com.example.ai.model.ChatCompletionRequest; import com.example.ai.model.ChatCompletionResponse; import com.example.ai.model.ChatMessage; import com.example.ai.service.QwenAIService; import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.*; import java.io.IOException; import java.util.List; RestController RequestMapping(/api/ai) RequiredArgsConstructor public class AIChatController { private final QwenAIService qwenAIService; PostMapping(/chat) public String simpleChat(RequestParam String question) throws IOException { // 使用便捷方法 return qwenAIService.chat(question); } PostMapping(/chat/completion) public ChatCompletionResponse advancedChat(RequestBody ChatCompletionRequest request) throws IOException { // 使用完整请求方法 return qwenAIService.chatCompletion(request); } GetMapping(/test) public String test() throws IOException { // 一个快速测试接口 ChatCompletionRequest request ChatCompletionRequest.builder() .model(qwen1.5-1.8b-chat-gptq-int4) .messages(List.of( ChatMessage.builder().role(user).content(你好请介绍一下你自己。).build() )) .maxTokens(500) .temperature(0.7) .build(); ChatCompletionResponse response qwenAIService.chatCompletion(request); return response.getFirstMessageContent(); } }6.2 启动并测试确保你的通义千问模型服务已经在http://localhost:8000运行。启动你的SpringBoot应用。打开浏览器或使用Postman等工具访问GET http://localhost:8080/api/ai/test。你应该能看到模型返回的自我介绍文本。你也可以用POST http://localhost:8080/api/ai/chat?question今天天气怎么样来发送问题或者用/chat/completion端点来发送更复杂的请求体。7. 总结与后续优化思路走完这一套流程你应该已经成功在SpringBoot项目里集成了通义千问模型。整个过程其实不复杂核心就是配置一个HTTP客户端定义好数据格式然后发起调用。我比较喜欢OkHttp的简洁和灵活配合Spring的依赖注入整个服务写起来很顺畅。实际用起来有几个地方可以再打磨一下。一个是连接池OkHttpClient默认就有但你可以根据并发量调整一下参数。另一个是超时时间我给的示例值比较保守如果你的模型服务响应快或者网络环境好可以适当调短避免请求堆积。日志那块也挺有用调试阶段打开能看清每次请求和响应的具体内容上线了再关掉就行。这套代码算是一个坚实的地基。在此基础上如果你想做得更完善可以考虑加入请求结果的缓存比如用Caffeine避免重复问相同的问题或者做一个简单的熔断机制比如用Resilience4j在模型服务不稳定时快速失败保护你自己的应用。如果对话场景复杂可能还需要维护一个会话上下文的管理。但这些都属于进阶玩法了先把基础的通路跑稳再根据实际业务需求慢慢往上加会更稳妥。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。