SpringBoot集成通义千问：从API选型到流式输出的完整实战指南-代码聚汇网

SpringBoot集成通义千问：从API选型到流式输出的完整实战指南

不靠谱的糖饼·2026-08-30·阅读 22 GEO检测（免费）

SpringBoot通义千问大模型API

|难度：普通|阅读约 47 分钟

我一直觉得，Java后端接入大模型这件事，缺的不是API文档，而是一篇能让人少走弯路的实战记录。这次用SpringBoot集成通义千问，从选型到跑通，我踩了不少坑，也沉淀了一套可以直接抄作业的代码。如果你正打算在Java生态里调用大模型API，又不想被各种协议、参数、版本问题折腾到怀疑人生，这篇文章应该能帮你省下至少一个下午。

1. 为什么Java项目接入大模型要选通义千问：选型逻辑与前置认知

1.1 从一次失败的接入谈起：不是所有大模型API都对Java友好

先说个真实经历。之前有个项目要用大模型做合同信息抽取，技术栈是Java 8 + SpringBoot 2.x。团队里有人提议直接用Python写个服务单独跑，理由是大模型SDK基本都是Python优先。但问题是，我们这套系统涉及大量内部服务调用、鉴权逻辑、数据库操作，再起一个Python服务就意味着要维护两套部署链路、两套监控、两套日志，运维成本直接翻倍。

后来我尝试用Java直接调大模型API，发现其实没有想象中那么复杂。HTTP调用嘛，Java生态里最不缺的就是这个。但真正折腾人的是协议细节：有的平台返回的字段嵌套特别深，有的平台鉴权方式很特殊，有的平台SSE流式输出的格式跟标准不太一样。这些坑不亲自踩一遍，光看官方文档还真发现不了。

1.2 通义千问API的两种调用协议：原生DashScope协议与OpenAI兼容协议

阿里云百炼平台上的通义千问，对外提供了两套API协议。第一套是DashScope原生协议，请求地址是https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation，使用Authorization: Bearer <api-key>的鉴权头，请求体有固定的model、input、parameters三层结构。第二套是OpenAI兼容模式，地址是https://dashscope.aliyuncs.com/compatible-mode/v1，直接把通义千问包装成了OpenAI的接口格式。

这两套协议怎么选？如果你是从零开始、只用通义千问一个模型，原生协议就够了，文档示例多。但如果你的系统未来可能要接其他模型，或者你已经在用OpenAI的生态工具，那务必选OpenAI兼容模式，因为/v1/chat/completions这个路径，几乎所有模型厂商都在兼容，代码迁移成本极低。

我的建议是：新项目直接走OpenAI兼容模式，这是一个“现在多花十分钟，未来省几天”的决定。

1.3 模型命名规则：qwen-turbo、qwen-plus、qwen-max怎么选

通义千问在百炼平台上的模型名，不是随便填的。常见的几个是qwen-turbo、qwen-plus、qwen-max，对应不同的能力和价格档位。需要说明的是，这些模型名称会随平台更新而调整，接入前最好在控制台确认一下当前可用的模型标识。

怎么选？如果你做的是高频、简单、对成本敏感的场景，比如标题生成、关键词提取、文本分类，用qwen-turbo，速度快、便宜。如果你做的是需要一定推理能力的场景，比如代码生成、结构化信息抽取、长文本总结，用qwen-plus，性价比平衡。如果是复杂推理、数学题、深度分析这类任务，才需要上qwen-max。

我在实际项目中做过对比，同样的合同条款提取任务，turbo的准确率大概在85%左右，plus能到93%，max能到96%。但max的响应时间几乎是turbo的两倍，成本则是五倍以上。所以别一上来就无脑选最强模型，你得先评估你的任务复杂度。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 开发前哨：开通API Key、确认SpringBoot版本与依赖的选择

2.1 获取API Key：百炼控制台的申请流程简述

在开始写代码之前，先把账号和密钥准备好。整个流程比较直接：注册阿里云账号后，在百炼大模型平台控制台完成实名认证，然后开通“模型服务”权限，在“API-KEY”管理页面创建一个新的密钥。

密钥创建之后就赶紧复制保存好。这里必须提醒一句：API Key是明文形式的，这个页面你关掉之后基本不会再有第二次展示机会，只能重置。我之前就吃过这个亏，生成之后没保存，转头就忘了，只能在控制台重置重新配置。

拿到Key之后，先别急着写代码，直接在控制台提供的“模型体验”或者API调试工具里试一下，确认账号权限没问题、模型调用能通。这样你在控制台验证过，再进代码里排错，就能先排除掉九成的账号权限问题。

2.2 SpringBoot版本与JDK的匹配问题：2.x和3.x的差异

SpringBoot版本是第一批坑的来源。很多公司的存量项目还是SpringBoot 2.x + JDK 8，这个组合完全能调通义千问API，没有硬性门槛。选择SpringBoot 3.x则意味着你大概率要上JDK 17+，这个组合在性能和生态上确实更好，但对老项目来说，可能伴随一些依赖兼容性问题。

xml复制<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version>
    <relativePath/>
</parent>

2.7.18是2.x系列的收官版本，如果你受限于JDK 8，选它最稳妥。如果项目允许升级，直接用SpringBoot 3.2+搭配JDK 17，后续接各种新依赖会省心很多。

有个细节很多人忽略：SpringBoot 3.x中javax包全部换成了jakarta包，如果你的老代码里有import javax.annotation.Resource这种写法，编译直接报错。所以从2.x升3.x，不只是改个版本号那么简单。

2.3 引入依赖：HTTP客户端到底选谁（RestTemplate、OkHttp还是WebClient）

调用大模型API本质上就是发HTTP请求，SpringBoot生态里可选的HTTP客户端不少，我做了个对比：

HTTP客户端	同步/异步	易用性	流式支持	适用场景
RestTemplate	同步	高	一般	常规同步调用，简单直接
OkHttp	同步/异步	中	较好	需要细粒度控制、连接池优化
WebClient	异步响应式	中低	优秀	高并发、流式响应场景

我的建议很明确：先用RestTemplate跑通流程，再按需换WebClient。原因很简单，RestTemplate封装程度高，代码最直白，你要理解大模型调用的完整逻辑，用它是学习成本最低的路径。等你把协议、参数、错误处理都摸透了，再考虑性能优化。

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

这个依赖里已经自带RestTemplate，不需要额外引入。但注意点在于，SpringBoot 2.x和3.x中，RestTemplate本身不是自动配置好的Bean，需要自己手动new一个，或者定义成@Bean注入。

3. 核心代码实战：从配置类到Service再到Controller的完整链路

3.1 配置类绑定API Key和模型参数

工程结构上，我先把配置项独立出来，避免API Key这类敏感信息出现在业务代码中。在application.yml里集中管理参数：

yaml复制ai:
  qwen:
    api-key: ${QWEN_API_KEY}
    base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen-plus
    temperature: 0.7
    max-tokens: 2000
    read-timeout-seconds: 60

注意我这里用了${QWEN_API_KEY}，这是从环境变量里读取的写法。API Key千万不要硬编码在配置文件里，更别提交到Git仓库，这是最基础的安全习惯。

对应的配置类：

java复制@Data
@Component
@ConfigurationProperties(prefix = "ai.qwen")
public class QwenConfigProperties {
    private String apiKey;
    private String baseUrl;
    private String model;
    private Double temperature;
    private Integer maxTokens;
    private Integer readTimeoutSeconds;
}

这里用了@ConfigurationProperties，SpringBoot会自动把配置文件里的ai.qwen前缀下的属性绑定到这个类上。需要依赖：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

这个依赖不是必须的，但加上之后，写配置文件时IDEA会自动提示属性名，不容易拼写错。

3.2 用RestTemplate实现一个结构清晰的大模型调用Service

接下来是核心部分。我定义一个QwenChatService，专门负责与大模型API交互。这里我选择了OpenAI兼容模式，所以请求体是标准的结构。

先定义请求DTO：

java复制@Data
@Builder
public class ChatRequest {
    private String model;
    private List<Message> messages;
    private Double temperature;
    private Integer maxTokens;

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

messages数组里的每条消息包含role和content。role有三种取值：system（系统指令）、user（用户输入）、assistant（模型回复）。这个结构需要掌握，因为多轮对话就是通过维护这个数组来实现的。

再定义响应DTO：

java复制@Data
public class ChatResponse {
    private String id;
    private List<Choice> choices;

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

这个响应结构是OpenAI兼容格式的标准结构。实际返回中还有其他字段比如usage（token消耗）、created（时间戳），按需补充即可。

Service实现：

java复制@Service
@RequiredArgsConstructor
public class QwenChatService {

    private final QwenConfigProperties properties;
    private final RestTemplate restTemplate;

    public String chat(String systemPrompt, String userMessage) {
        String url = properties.getBaseUrl() + "/chat/completions";

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.setBearerAuth(properties.getApiKey());

        List<ChatRequest.Message> messages = new ArrayList<>();
        if (StringUtils.hasText(systemPrompt)) {
            messages.add(ChatRequest.Message.builder()
                    .role("system")
                    .content(systemPrompt)
                    .build());
        }
        messages.add(ChatRequest.Message.builder()
                .role("user")
                .content(userMessage)
                .build());

        ChatRequest request = ChatRequest.builder()
                .model(properties.getModel())
                .messages(messages)
                .temperature(properties.getTemperature())
                .maxTokens(properties.getMaxTokens())
                .build();

        HttpEntity<ChatRequest> entity = new HttpEntity<>(request, headers);

        ResponseEntity<ChatResponse> response = restTemplate.exchange(
                url, HttpMethod.POST, entity, ChatResponse.class);

        if (response.getBody() == null || response.getBody().getChoices().isEmpty()) {
            throw new RuntimeException("大模型返回为空");
        }

        return response.getBody().getChoices().get(0).getMessage().getContent();
    }
}

这里有个细节值得多说一句：RestTemplate默认的构造方式有局限，它使用SimpleClientHttpRequestFactory，连接池管理较弱。对于大模型API这种响应动辄数秒的接口，最好配置专门的连接超时和读取超时：

java复制@Configuration
public class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate() {
        // 使用HttpComponentsClientHttpRequestFactory，支持连接池
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory();
        
        // 连接超时：从连接池获取连接或建立连接的超时时间
        factory.setConnectTimeout(5000);
        // 读取超时：等待响应数据的超时时间，大模型接口慢，保守一点
        factory.setReadTimeout(60000);
        // 连接池获取连接的超时时间
        factory.setConnectionRequestTimeout(3000);
        
        RestTemplate restTemplate = new RestTemplate(factory);
        
        // 必须设置消息转换器，让RestTemplate能处理application/json和text/event-stream
        restTemplate.getMessageConverters().add(0, 
                new StringHttpMessageConverter(StandardCharsets.UTF_8));
        restTemplate.getMessageConverters().add(1, 
                new MappingJackson2HttpMessageConverter());
        
        return restTemplate;
    }
}

读取超时设置成60秒是经过考量的。大模型接口在模型负载高的时候，响应时间会明显变长。如果超时设太短，用户等不到结果反而收到超时错误，体验更差。但也要结合业务场景，如果一个简单的文本分类任务要等60秒，那说明模型选型有问题。

3.3 Controller层暴露接口：同步调用和流式输出

Service写好了，Controller层就简单了。我提供两个接口，一个同步返回完整文本，一个流式返回。

同步接口：

java复制@RestController
@RequestMapping("/api/qwen")
@RequiredArgsConstructor
public class QwenController {

    private final QwenChatService qwenChatService;

    @PostMapping("/chat")
    public Result<String> chat(@RequestBody ChatRequestDTO request) {
        String result = qwenChatService.chat(request.getSystemPrompt(), 
                request.getUserMessage());
        return Result.success(result);
    }
}

流式接口稍微复杂一点。大模型API本身支持stream: true参数，服务端通过SSE（Server-Sent Events）逐段返回内容。这样用户不用干等几十秒，而是能像ChatGPT网页版那样看到字一个个蹦出来。

但流式处理在SpringBoot里有一个不太优雅的限制：如果你用text/event-stream自己拼SSE格式，要处理各个事件边界。这里给出一个简化版本：

java复制@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter chatStream(@RequestBody ChatRequestDTO request) {
    // 超时设为5分钟，流式接口可能长时间占用连接
    SseEmitter emitter = new SseEmitter(300000L);
    
    executorService.execute(() -> {
        try {
            // 调用底层流式方法，这里用同步方式模拟
            String result = qwenChatService.chat(request.getSystemPrompt(),
                    request.getUserMessage());
            // 按字符或按句子切分发送
            for (int i = 0; i < result.length(); i += 10) {
                int end = Math.min(i + 10, result.length());
                emitter.send(result.substring(i, end), MediaType.TEXT_PLAIN);
                Thread.sleep(50);
            }
            emitter.complete();
        } catch (Exception e) {
            emitter.completeWithError(e);
        }
    });
    
    return emitter;
}

这个版本是模拟流式，实际生产环境中应该直接对接API的SSE流，逐段转发，而不是等完整结果再切分。但作为理解流式机制的入门示例，它能帮你搞明白SseEmitter的工作原理。

3.4 请求与响应对象的封装：避免魔法字符串

前文代码中有一个通用的Result<T>包装类，这是我在项目中常用的统一返回结构。它的作用不只是好看，更重要的是让前端有一个固定的解析模式，不用每次换接口都去猜返回结构。

java复制@Data
public class Result<T> {
    private Integer code;
    private String message;
    private T data;

    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMessage("success");
        result.setData(data);
        return result;
    }

    public static <T> Result<T> error(Integer code, String message) {
        Result<T> result = new Result<>();
        result.setCode(code);
        result.setMessage(message);
        return result;
    }
}

同时，我建议把模型名称、角色名称这类常量集中管理，避免散落在代码里的魔法字符串：

java复制public class QwenConstants {
    public static final String ROLE_SYSTEM = "system";
    public static final String ROLE_USER = "user";
    public static final String ROLE_ASSISTANT = "assistant";
}

这样看似多写了一些代码，但在后续维护、重构时能省很多事。特别是当模型升级、字段变化时，只需要改一处。

4. 折腾半天才发现的坑：529过载、超时与并发控制

4.1 529 Overloaded错误：服务端限流的真相与应对策略

在开发调通义千问API的过程中，我遇到过这个错误：

json复制{
  "error": {
    "message": "api error: 529 overloaded. this is a server-side issue, usually temporary",
    "type": "overloaded_error",
    "code": 529
  }
}

这个报错在大模型API调用中很常见，本质是模型服务端的负载过高，短时间内无法处理你的请求。服务端会提示“通常是暂时的”，但如果你不做处理，直接抛给用户，用户就会看到一个大白屏或一个看不懂的JSON错误。

应对策略有三个层级：

第一层：指数退避重试。 遇到529时，不要立即重试，而是等一段时间再试。间隔时间可以按1秒、2秒、4秒、8秒递增，最多重试3次。

java复制private String chatWithRetry(ChatRequest request, HttpHeaders headers, String url) {
    int maxRetry = 3;
    int retryCount = 0;
    long waitMillis = 1000L;

    while (retryCount <= maxRetry) {
        try {
            HttpEntity<ChatRequest> entity = new HttpEntity<>(request, headers);
            ResponseEntity<ChatResponse> response = restTemplate.exchange(
                    url, HttpMethod.POST, entity, ChatResponse.class);
            return extractContent(response);
        } catch (HttpClientErrorException e) {
            if (e.getStatusCode().value() == 429 || e.getStatusCode().value() == 529) {
                // 服务端过载，退避重试
                if (retryCount == maxRetry) {
                    throw e;
                }
                try {
                    Thread.sleep(waitMillis);
                } catch (InterruptedException interrupted) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException("重试等待被中断", interrupted);
                }
                waitMillis *= 2;
                retryCount++;
            } else {
                throw e;
            }
        }
    }
    throw new IllegalStateException("不应到达这里");
}

第二层：并发控制。 如果请求量本身很大，服务端的负载可能只是表象，真正的问题是你的请求把模型实例打满了。这时候需要在客户端做限流，比如用Semaphore控制并发数。

第三层：队列削峰。 对于非实时场景，可以把请求放到消息队列中，由消费端按固定速率去调用大模型API，避免瞬时流量冲击。这里不展开，但思路值得记住。

4.2 连接超时与读取超时：大模型接口慢的根本原因

大模型API的响应时间和传统API有本质区别。普通业务接口的P99响应时间可能在200ms左右，但大模型接口的响应时间随着生成的token数量线性增加。生成100个token可能需要5-10秒，生成1000个token可能就要30-60秒。

很多初接大模型的后端同学会在这一步栽跟头：用默认的RestTemplate，没设超时时间，结果接口在模型返回慢的时候直接报SocketTimeoutException: Read timed out；或者反过来，超时时间设置太长，用户在页面端等了几十秒，比大模型本身的响应还慢。

我的实践经验是：

连接超时（connectTimeout）设5秒：如果5秒内连不上服务端，大概率是网络或服务端地址问题，没必要傻等。
读取超时（readTimeout）设60秒：这是给大模型生成内容留的缓冲时间，但这个值需要根据你设置的max_tokens来调整。如果max_tokens设了4000，60秒可能还不够，要适当拉长。

还有一个容易被忽略的点：如果通过spring.main.web-application-type配置了非阻塞Web环境，或者使用了WebFlux，那RestTemplate的同步阻塞行为会导致线程池占用问题，要特别小心。

4.3 并发场景下的线程池隔离：别让大模型拖垮整个服务

大模型调用是典型的IO密集型操作，而且这个IO还特别慢。如果业务代码里直接把大模型调用放在Tomcat工作线程里同步等待，高并发下Tomcat的默认200个线程很快就会被占满，导致整个服务的其他接口（包括那些不需要大模型的接口）全部不可用。

解决方案是线程池隔离。把大模型调用放到一个独立的线程池中，控制并发度，同时给不同的业务场景设置不同的线程池，避免互相影响。

java复制@Configuration
public class ThreadPoolConfig {

    @Bean("qwenTaskExecutor")
    public ThreadPoolTaskExecutor qwenTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("qwen-pool-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        executor.initialize();
        return executor;
    }
}

这里的参数设计逻辑是：大模型API的QPS上限通常在10-20左右（不同账号层级不同），所以核心线程数设5、最大10，已经足够。CallerRunsPolicy的意思是当队列满时，不抛弃任务，而是让提交任务的线程自己执行。这样在极端情况下，只是变慢，不会直接拒绝请求丢失。

5. 进阶玩法：上下文管理、函数调用与私有化模型接入

5.1 多轮对话的上下文管理：messages数组的正确维护方式

前面只是单轮调用，但很多业务场景需要多轮对话。比如客服机器人，用户说了“帮我查一下订单”，机器人问“订单号是什么”，用户回答“12345”，这时的上下文就是连续的。

多轮对话在协议层面并不复杂，就是把历史对话都塞到messages数组里：

json复制[
  {"role": "system", "content": "你是客服助手"},
  {"role": "user", "content": "我有个订单要查"},
  {"role": "assistant", "content": "好的，请提供订单号"},
  {"role": "user", "content": "订单号是12345"}
]

复杂的是这个数组的长度控制。每多一轮对话，messages数组就多两条消息，token消耗就增大一次。而大模型上下文窗口有限，比如qwen-plus是32K上下文，超过就会被截断。

实际项目中，我常用两种策略：

滑动窗口截断：只保留最近N轮对话。比如只保留最近10轮，每轮是一条user消息和一条assistant消息，超过就从最前面丢弃。这样保证了token消耗可控。

摘要压缩：当对话轮次超过阈值时，调用一次大模型，把前面的对话内容总结成一段摘要，然后把摘要作为system消息，后续只携带摘要和新对话。这个方案效果最好，但会多一次模型调用，延迟和成本都会增加。

java复制public void appendMessage(List<ChatRequest.Message> messages, String role, String content) {
    messages.add(ChatRequest.Message.builder()
            .role(role)
            .content(content)
            .build());
    
    // 控制消息条数，保留最近10轮（20条）
    if (messages.size() > 20) {
        // 保留第一条system消息，从第二条开始丢弃最老的user/assistant消息
        messages.subList(1, messages.size() - 19).clear();
    }
}

注意上面的subList操作返回的是原List的视图，不是新的List，所以调用clear()会直接修改原List。这个API设计隐蔽，容易踩坑，如果用的时候没意识到会原地修改，很容易写出逻辑错误的代码。

5.2 API Key的安全对接：怎么防止被前端拿去滥用

服务端调用大模型API，API Key是最高机密，但实际项目中经常出现这些情况：

一是前端页面直接展示调用结果，用户可以通过浏览器DevTools查看网络请求，如果请求里带了API Key，那等于把密钥公开了；二是通过网关转发时，不小心把API Key暴露在响应头里；三是源代码提交到Git仓库，因为里面有API Key。

我给几个实用建议：

第一，API Key只存在服务端。 前端永远不知道你的API Key是什么，前端只需要请求你自己的后端接口，由后端转发到大模型API。

第二，独立鉴权层。 你自己的后端接口需要一套自己的鉴权机制（比如JWT），验证当前用户是否有权限调用大模型功能，而不是直接暴露给所有匿名请求。

第三，限额控制。 在服务端记录每个用户的调用次数和token消耗，超出配额直接拒绝。这能防止有人恶意刷接口，把你的API额度耗尽。

java复制@Slf4j
@Component
@Aspect
public class QwenApiLimitAspect {

    @Autowired
    private StringRedisTemplate stringRedisTemplate;

    @Around("@annotation(qwenApiLimit)")
    public Object around(ProceedingJoinPoint joinPoint, QwenApiLimit qwenApiLimit) throws Throwable {
        // 这里用用户ID作为维度做计数限流
        String userId = UserContext.getUserId();
        String key = "qwen:limit:" + userId + ":" + LocalDate.now();
        
        Long count = stringRedisTemplate.opsForValue().increment(key);
        if (count != null && count == 1) {
            // OpsForValue().increment 的 expire 设置
            stringRedisTemplate.expire(key, Duration.ofDays(1));
        }
        
        if (count > qwenApiLimit.value()) {
            throw new BusinessException("今日调用次数已达上限");
        }
        
        return joinPoint.proceed();
    }
}

这个切面只是一个简化示例，实际落地时还需要考虑：分布式部署时用Redis计数、不同用户等级设置不同配额、超额后的提示文案等。但核心思路很清晰：调用大模型API的入口一定要有配额控制，否则你的账单会教会你做人。

5.3 从通义千问到任意大模型：兼容层设计的通用思路

最后聊一个宏观设计问题。如果公司未来要换模型，比如从通义千问换到其他大模型，你的代码该怎么保底？

我的做法是定义一个AiChatPort接口，然后分别实现不同的适配器：

java复制public interface AiChatPort {
    String chat(String systemPrompt, String userMessage);
    String chat(String systemPrompt, List<ChatRequest.Message> history);
}

@Component
@Primary
public class QwenChatAdapter implements AiChatPort {
    private final QwenChatService qwenChatService;

    @Override
    public String chat(String systemPrompt, String userMessage) {
        return qwenChatService.chat(systemPrompt, userMessage);
    }

    @Override
    public String chat(String systemPrompt, List<ChatRequest.Message> history) {
        return qwenChatService.chatWithHistory(systemPrompt, history);
    }
}

以后要接入同生态的其他模型，只需要新增一个XxxChatAdapter实现AiChatPort接口，然后通过@ConditionalOnProperty或者配置中心动态切换。业务代码只依赖AiChatPort接口，完全不知道底层是哪个模型提供方。

这个设计借鉴了依赖倒置原则，不算复杂，但很实用。接入大模型API不是一次性需求，而是一个长期的、可能需要多次迭代选型的演进过程，接口隔离能让你在模型快速迭代的环境中保持业务代码稳定。

最后再分享一个经验：做技术选型时，不要仅仅被“大模型很火”这个趋势推着走，务必先想清楚你的业务场景。如果是高频、短任务，优先选快速便宜的模型；如果是低频、长文本、高精度，选最强模型；如果是实时交互，务必做流式输出，不要等完整结果。我在实际项目中，因为一开始选了同步接口做实时聊天，卡了几个月没处理，后来切到流式后体验提升了一个量级。Java接大模型这件事，本质就是一个HTTP调用加上良好的错误处理和并发控制，把这些基本功做扎实了，什么模型都能接得顺。