导读前面章节我们搭建了基础 SpringAI 工程体验了基础对话能力。实际开发场景里原生 OpenAI 存在网络代理、延迟高、访问不稳定等问题并不适配国内业务。本章基于固定环境JDK21 Gradle8.8 SpringBoot3.5.14 SpringAI1.1.7手把手完成阿里云通义千问接入。本章采用阿里云官方 OpenAI 兼容协议适配。 额外配套配置打印校验功能直观查看加载的接口地址、模型名称不再盲目猜测配置是否生效零基础也能一次运行成功。一、版本适配环境清单JDK21Gradle8.8SpringBoot3.5.14SpringAI1.1.7IDEA2023社区版二、build.gradle 完整依赖配置直接覆盖项目原有 build.gradle 文件plugins { id java id org.springframework.boot version 3.5.14 id io.spring.dependency-management version 1.1.7 } group com.example version 0.0.1-SNAPSHOT java { toolchain { languageVersion JavaLanguageVersion.of(21) } } repositories { maven { url https://maven.aliyun.com/nexus/content/groups/public } maven { url https://maven.aliyun.com/repository/google } mavenCentral() // Spring AI 官方仓库 maven { url https://repo.spring.io/release } maven { url https://repo.spring.io/milestone } } dependencies { // 基础Web服务 implementation org.springframework.boot:spring-boot-starter-web // 1.OpenAI 驱动包对接GPT系列模型,兼容通义 implementation org.springframework.ai:spring-ai-starter-model-openai:1.1.7 testImplementation org.springframework.boot:spring-boot-starter-test testRuntimeOnly org.junit.platform:junit-platform-launcher } tasks.named(test) { useJUnitPlatform() }修改完毕后点击 IDEA 右侧 Gradle 面板Reload All Gradle Projects等待依赖自动下载。三、application.yml 通义千问专属配置文件路径src/main/resources/application.ymlspring: ai: openai: # 替换为你在阿里云百炼平台获取的真实 API Key api-key: sk-xxxxxxxxxxxxxxxxxxxx # 关键配置DashScope 的 OpenAI 兼容模式 endpoint base-url: https://dashscope.aliyuncs.com/compatible-mode chat: options: # 指定使用 qwen-turbo 模型 model: qwen-turbo # 控制输出的随机性对话类应用建议 0.7 temperature: 0.7 # 限制最大生成 Token 数防止回复过长 max-tokens: 1024避坑我这个版本base-url不能用否则要报错误o.s.a.r.a.SpringAiRetryAutoConfiguration : Retry error. Retry count: 1,Exception: HTTP 404 - No response body available四、业务 Controller 代码带配置打印校验package com.example.demo; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.openai.OpenAiChatProperties; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/ai) public class ChatController { private final ChatClient chatClient; // 配置读取类获取yml真实加载参数 private final OpenAiChatProperties aiProperties; public ChatController(ChatClient.Builder builder, OpenAiChatProperties aiProperties) { this.chatClient builder.build(); this.aiProperties aiProperties; // 项目启动自动打印配置校验是否加载成功 System.out.println( 模型配置加载信息 ); System.out.println(请求Base地址 aiProperties.getBaseUrl()); System.out.println(当前使用模型 aiProperties.getOptions().getModel()); System.out.println(Temperature值 aiProperties.getOptions().getTemperature()); System.out.println(); } /** * 通用对话接口 * param message 用户提问内容 * return AI返回文本结果 */ GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.prompt(message) .call() .content(); } }五、启动校验与接口测试1、启动控制台校验输出正常启动无报错控制台打印如下内容即代表通义千问配置完全生效 模型配置加载信息 请求Base地址https://dashscope.aliyuncs.com/compatible-mode/v1当前使用模型qwen-turboTemperature值0.72、浏览器访问测试接口访问地址http://localhost:8080/ai/chat?message简单介绍SpringAI框架页面正常返回通义千问生成的回答文本对接完成。六、核心底层原理讲解配置自动绑定SpringAI 自动扫描 yml 内 ai.openai 配置注入至 OpenAiChatProperties全程无需手动读取配置文件兼容协议适配通义千问对外暴露和 OpenAI 一模一样的请求体、返回体结构OpenAI 驱动可直接转发请求ChatClient 统一抽象不管底层对接哪家兼容模型上层调用三段式代码prompt()-call()-content()永久不变真实配置校验OpenAiChatProperties 读取的是程序实际运行加载的值区别于本地 yml 文本可规避缓存、多配置文件覆盖问题七、高频问题排错调用接口超时无响应 排查核对 base-url 地址拼写、api-key 密钥是否有效、账号调用额度是否耗尽返回模型名称不存在报错 排查严格复制阿里云官方模型标识不能简写、自定义别名上一篇SpringAI 入门 06官方核心概念全解析Models/Prompt/Embedding/RAG/Tool Calling