通义千问1.5-1.8B-Chat-GPTQ-Int4 Java集成指南：SpringBoot微服务调用实战

最近在做一个内部知识库问答系统，后端用的是SpringBoot，需要集成一个轻量级的AI模型来处理一些简单的文本生成和对话任务。通义千问1.5-1.8B-Chat-GPTQ-Int4这个版本，模型小、推理快，还做了量化，对资源要求不高，感觉特别适合塞进微服务里。折腾了一圈，把整个集成流程跑通了，今天就来聊聊怎么把它平滑地整合到你的SpringBoot项目里，重点是做成一个高可用、易维护的微服务组件。

1. 项目准备与环境搭建

在开始写代码之前，得先把环境和依赖准备好。这里假设你已经有一个基础的SpringBoot项目了，如果没有，用Spring Initializr生成一个也很方便。

1.1 核心依赖引入

首先，打开你的 pom.xml 文件，把下面这些依赖加进去。除了SpringBoot Web Starter用来提供REST API，我们还需要一个HTTP客户端来调用模型服务，以及一些工具库。

<dependencies>
    <!-- SpringBoot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- HTTP客户端 - 这里用OkHttp，你也可以用RestTemplate或WebClient -->
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>okhttp</artifactId>
        <version>4.12.0</version>
    </dependency>
    
    <!-- JSON处理 -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
    
    <!-- 配置属性绑定 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
    
    <!-- 测试 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

1.2 模型服务端准备

我们集成的目标是调用通义千问模型。你需要先确保模型服务已经启动并对外提供了HTTP API。通常，这类模型服务会部署在某个服务器上，提供一个类似 http://your-model-server:port/v1/chat/completions 的端点。

为了本地测试，你可以用Docker快速拉起一个服务。这里假设模型服务运行在 http://localhost:8000。你需要知道它的具体请求格式和响应格式，一般都会提供OpenAPI文档。我们接下来会按照常见的Chat Completion格式来封装。

2. 核心服务层封装

这一层是集成的核心，负责和远端的模型API打交道。我们的目标是封装得友好一点，让业务代码调用起来简单，同时还要考虑网络异常、超时这些烦人的问题。

2.1 定义配置与请求响应体

首先，把模型服务的地址、超时时间这些配置项放到 application.yml 里，方便管理。

# application.yml
qwen:
  model:
    base-url: http://localhost:8000
    api-key: dummy-key # 如果服务端需要鉴权的话
    timeout: 30000 # 超时时间，单位毫秒

然后，创建一个配置类来读取这些属性。

// src/main/java/com/yourproject/config/QwenModelProperties.java
package com.yourproject.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Data
@Component
@ConfigurationProperties(prefix = "qwen.model")
public class QwenModelProperties {
    private String baseUrl;
    private String apiKey;
    private Integer timeout;
}

接着，定义调用模型API时需要的请求体和响应体。这得根据模型服务实际的接口文档来，下面是一个通用格式的例子。

// src/main/java/com/yourproject/model/dto/QwenChatRequest.java
package com.yourproject.model.dto;

import lombok.Data;
import java.util.List;

@Data
public class QwenChatRequest {
    private String model = "Qwen-1.8B-Chat-Int4"; // 指定模型名称
    private List<Message> messages;
    private Double temperature = 0.7; // 控制随机性
    private Integer maxTokens = 512; // 生成的最大token数

    @Data
    public static class Message {
        private String role; // "system", "user", "assistant"
        private String content;
    }
}

// src/main/java/com/yourproject/model/dto/QwenChatResponse.java
package com.yourproject.model.dto;

import lombok.Data;
import java.util.List;

@Data
public class QwenChatResponse {
    private String id;
    private String object;
    private Long created;
    private String model;
    private List<Choice> choices;
    private Usage usage;

    @Data
    public static class Choice {
        private Integer index;
        private Message message;
        private String finishReason;
    }

    @Data
    public static class Message {
        private String role;
        private String content;
    }

    @Data
    public static class Usage {
        private Integer promptTokens;
        private Integer completionTokens;
        private Integer totalTokens;
    }
}

2.2 实现模型调用服务

现在来实现真正干活的Service。这里我们用OkHttpClient，并配置连接池、超时和重试策略。

// src/main/java/com/yourproject/service/impl/QwenModelServiceImpl.java
package com.yourproject.service.impl;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.yourproject.config.QwenModelProperties;
import com.yourproject.model.dto.QwenChatRequest;
import com.yourproject.model.dto.QwenChatResponse;
import com.yourproject.service.QwenModelService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import okhttp3.*;
import org.springframework.stereotype.Service;
import javax.annotation.PostConstruct;
import java.io.IOException;
import java.util.concurrent.TimeUnit;

@Slf4j
@Service
@RequiredArgsConstructor
public class QwenModelServiceImpl implements QwenModelService {

    private final QwenModelProperties properties;
    private final ObjectMapper objectMapper;
    
    private OkHttpClient httpClient;

    @PostConstruct
    public void init() {
        // 配置HTTP客户端，重点是超时和重试
        this.httpClient = new OkHttpClient.Builder()
                .connectTimeout(10, TimeUnit.SECONDS)
                .writeTimeout(30, TimeUnit.SECONDS)
                .readTimeout(30, TimeUnit.SECONDS)
                .retryOnConnectionFailure(true) // 自动重试
                .build();
    }

    @Override
    public String chatCompletion(String userMessage) throws IOException {
        // 1. 构建请求体
        QwenChatRequest request = new QwenChatRequest();
        QwenChatRequest.Message message = new QwenChatRequest.Message();
        message.setRole("user");
        message.setContent(userMessage);
        request.setMessages(List.of(message));

        String requestBody = objectMapper.writeValueAsString(request);

        // 2. 构建HTTP请求
        Request httpRequest = new Request.Builder()
                .url(properties.getBaseUrl() + "/v1/chat/completions")
                .post(RequestBody.create(requestBody, MediaType.get("application/json")))
                .addHeader("Authorization", "Bearer " + properties.getApiKey())
                .addHeader("Content-Type", "application/json")
                .build();

        // 3. 发送请求并处理响应
        try (Response response = httpClient.newCall(httpRequest).execute()) {
            if (!response.isSuccessful()) {
                log.error("模型服务调用失败，状态码: {}, 响应体: {}", response.code(), response.body() != null ? response.body().string() : "空");
                throw new IOException("模型服务响应异常: " + response.code());
            }

            String responseBody = response.body().string();
            QwenChatResponse chatResponse = objectMapper.readValue(responseBody, QwenChatResponse.class);

            // 4. 提取返回的文本内容
            if (chatResponse.getChoices() != null && !chatResponse.getChoices().isEmpty()) {
                return chatResponse.getChoices().get(0).getMessage().getContent();
            } else {
                throw new IOException("模型响应中未包含有效内容");
            }
        }
    }
}

为了让调用更灵活，我们再定义一个Service接口。

// src/main/java/com/yourproject/service/QwenModelService.java
package com.yourproject.service;

import java.io.IOException;

public interface QwenModelService {
    String chatCompletion(String userMessage) throws IOException;
}

3. 异步调用与性能优化

直接同步调用，如果模型推理慢，会阻塞整个HTTP线程，影响微服务吞吐量。所以，异步化是必须的。

3.1 使用CompletableFuture实现异步

我们可以利用Spring的 @Async 注解和 CompletableFuture 来轻松实现异步调用。

首先，在启动类或配置类上开启异步支持。

// src/main/java/com/yourproject/YourApplication.java
package com.yourproject;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;

@SpringBootApplication
@EnableAsync // 开启异步支持
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

然后，在Service里增加一个异步方法。

// 在 QwenModelServiceImpl 类中添加
import org.springframework.scheduling.annotation.Async;
import java.util.concurrent.CompletableFuture;

@Service
public class QwenModelServiceImpl implements QwenModelService {
    // ... 其他代码 ...

    @Async // 标记为异步方法
    @Override
    public CompletableFuture<String> chatCompletionAsync(String userMessage) {
        try {
            String result = this.chatCompletion(userMessage);
            return CompletableFuture.completedFuture(result);
        } catch (IOException e) {
            log.error("异步调用模型服务失败", e);
            return CompletableFuture.failedFuture(e);
        }
    }
}

记得在接口里也加上这个异步方法声明。

3.2 配置专属线程池

直接用 @Async 会用默认的线程池，为了更好控制，我们可以配置一个专用的。

// src/main/java/com/yourproject/config/AsyncConfig.java
package com.yourproject.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import java.util.concurrent.Executor;

@Configuration
@EnableAsync
public class AsyncConfig {

    @Bean(name = "modelTaskExecutor")
    public Executor modelTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        // 核心线程数，根据你的模型并发需求和服务器资源来定
        executor.setCorePoolSize(5);
        // 最大线程数
        executor.setMaxPoolSize(10);
        // 队列容量
        executor.setQueueCapacity(50);
        // 线程名前缀
        executor.setThreadNamePrefix("model-call-");
        executor.initialize();
        return executor;
    }
}

然后在异步方法上指定使用这个线程池。

    @Async("modelTaskExecutor") // 指定线程池
    public CompletableFuture<String> chatCompletionAsync(String userMessage) {
        // ...
    }

4. 服务熔断与降级策略

模型服务是外部依赖，网络抖动、服务重启都可能导致调用失败。我们不能让一个外部服务的故障拖垮自己的应用，这就需要熔断和降级。

4.1 使用Resilience4j实现熔断

Resilience4j比Hystrix更轻量，和SpringBoot集成也方便。先加依赖。

<!-- resilience4j -->
<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot2</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

然后，在配置文件中定义熔断器规则。

# application.yml
resilience4j:
  circuitbreaker:
    instances:
      qwenModelService:
        register-health-indicator: true
        sliding-window-size: 10 # 滑动窗口大小
        minimum-number-of-calls: 5 # 最小调用次数，低于此数不开启熔断计算
        permitted-number-of-calls-in-half-open-state: 3 # 半开状态允许的调用次数
        automatic-transition-from-open-to-half-open-enabled: true
        wait-duration-in-open-state: 10s # 熔断开启后，等待多久进入半开状态
        failure-rate-threshold: 50 # 失败率阈值，超过则开启熔断
        event-consumer-buffer-size: 10

接下来，在Service层的方法上添加 @CircuitBreaker 注解。

// 在 QwenModelServiceImpl 的 chatCompletion 方法上添加
import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;

@Service
public class QwenModelServiceImpl implements QwenModelService {
    
    @CircuitBreaker(name = "qwenModelService", fallbackMethod = "chatCompletionFallback")
    @Override
    public String chatCompletion(String userMessage) throws IOException {
        // ... 原有的同步调用逻辑 ...
    }

    // 熔断降级方法
    public String chatCompletionFallback(String userMessage, Exception e) {
        log.warn("模型服务熔断降级被触发，用户问题: {}, 异常: {}", userMessage, e.getMessage());
        // 返回一个友好的默认回复，或者从缓存中获取旧答案
        return "抱歉，AI助手暂时无法处理您的请求，请稍后再试。";
    }
}

4.2 结合缓存实现降级

对于某些常见问题，我们可以缓存答案，当模型服务不可用时，返回缓存内容，提升用户体验。这里用Spring Cache简单演示。

// 在 QwenModelServiceImpl 中修改
import org.springframework.cache.annotation.Cacheable;

@Service
public class QwenModelServiceImpl implements QwenModelService {
    
    @CircuitBreaker(name = "qwenModelService", fallbackMethod = "chatCompletionFallback")
    @Cacheable(value = "qwenResponses", key = "#userMessage", unless = "#result == null")
    @Override
    public String chatCompletion(String userMessage) throws IOException {
        // ... 原有的调用逻辑 ...
        // 只有当模型调用成功时，结果才会被缓存
        return result;
    }

    public String chatCompletionFallback(String userMessage, Exception e) {
        log.warn("模型服务熔断降级被触发，尝试从缓存获取答案。问题: {}", userMessage);
        // 这里可以尝试从缓存中获取，但注意 @Cacheable 在降级方法中不生效
        // 一个更健壮的做法是使用 CacheManager 手动查询缓存
        // 为了简化，我们先返回固定降级回复
        return "系统繁忙，您的问题已记录，稍后将为您处理。";
    }
}

记得在启动类上加上 @EnableCaching 注解来启用缓存。

5. 构建RESTful API控制器

最后，我们暴露一个简单的HTTP接口给前端或其他服务调用。

// src/main/java/com/yourproject/controller/QwenChatController.java
package com.yourproject.controller;

import com.yourproject.service.QwenModelService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.concurrent.CompletableFuture;

@Slf4j
@RestController
@RequestMapping("/api/v1/chat")
@RequiredArgsConstructor
public class QwenChatController {

    private final QwenModelService qwenModelService;

    @PostMapping("/completions")
    public ResponseEntity<String> chat(@RequestBody ChatRequest request) {
        try {
            String response = qwenModelService.chatCompletion(request.getMessage());
            return ResponseEntity.ok(response);
        } catch (Exception e) {
            log.error("处理聊天请求失败", e);
            return ResponseEntity.internalServerError().body("请求处理失败: " + e.getMessage());
        }
    }

    @PostMapping("/completions/async")
    public CompletableFuture<ResponseEntity<String>> chatAsync(@RequestBody ChatRequest request) {
        return qwenModelService.chatCompletionAsync(request.getMessage())
                .thenApply(ResponseEntity::ok)
                .exceptionally(e -> {
                    log.error("异步处理聊天请求失败", e);
                    return ResponseEntity.internalServerError().body("异步请求处理失败: " + e.getMessage());
                });
    }

    @Data
    public static class ChatRequest {
        private String message;
    }
}

这样，一个基本的、具备异步能力和初步熔断降级能力的模型服务集成模块就完成了。你可以通过 POST /api/v1/chat/completions 来同步调用，或者用 POST /api/v1/chat/completions/async 来异步调用。

6. 总结与后续优化建议

整个集成过程走下来，感觉最关键的不是调通API，而是怎么把它做得稳定、好用。SpringBoot的生态确实帮了大忙，像异步、熔断这些功能都有现成的轮子。

用下来，这个1.8B的Int4版本在轻量级任务上响应速度不错，放在微服务里资源压力也不大。不过在实际项目里，还有些地方可以继续打磨。比如，现在的错误处理还比较基础，可以针对不同的异常（网络超时、模型内部错误、限流等）设计更精细的降级策略。日志监控也得跟上，最好能把每次调用的耗时、token使用量、成功失败情况都记录下来，方便后续做容量规划和问题排查。

如果请求量再大点，可以考虑引入消息队列，把模型调用请求异步化得更彻底，前端轮询或者用WebSocket来取结果，体验会更好。缓存策略也可以更智能点，不是所有回答都值得缓存，可以根据问题的类型、模型返回的置信度来决定。

总之，把AI模型集成到企业级应用里，技术选型和架构设计得跟着实际业务需求走。今天分享的这个方案算是一个起点，你可以根据自己的场景往里加东西，比如用户会话管理、多轮对话上下文保持、敏感词过滤等等。希望这些代码和思路能帮你少踩点坑。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。