Spring AI 模型 API 使用指南：从版本选择到聊天模型实战

阅读 Spring 英文 AI 文档 和 中文文档基于官方文档与学习资料整理了一份AI 模型 API的使用指南带你从零上手 Spring AI。1. 版本选择Spring AI 版本Spring Boot 版本Java 版本Spring AI 1.1.xSpring Boot 3.5.xJava 17版本阶段排序SNAPSHOT开发快照→ M1、M2……里程碑→ RC1……候选→ 1.0.0GA 正式版。spring-ai-bom-1.1.x-SNAPSHOT为快照版本Maven 每次拉取的内容可能都不一样今天能跑明天可能就编译失败。spring-ai-bom-1.1.x-M3.pom为里程碑版本定期发布、相对稳定一些但也存在定时更新的问题。spring-ai-bom-1.1.x已经正式 GA 发布建议使用正式版。查看更多 spring-ai-bom 版本请点击链接2. POM 文件?xml version1.0 encodingUTF-8?projectxmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsdmodelVersion4.0.0/modelVersionparentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion3.5.3/versionrelativePath/!-- lookup parent from repository --/parentgroupIdcom.example/groupIdartifactIdSpringAIStart/artifactIdversion0.0.1-SNAPSHOT/versionnameSpringAIStart/namedescriptionSpringStart/descriptionpropertiesjava.version17/java.version/properties!-- 导入 Spring AI BOM用于统一管理 Spring AI 依赖的版本 引用每个 Spring AI 模块时不用再写 version只要依赖什么模块 Mavens 自动使用 BOM 推荐的版本 --dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion1.1.8/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement/project若快照版本还未发布到正式库还需要声明快照仓库此处使用 1.1.8 版本已经发布到正式仓库因此无需声明快照仓库。!-- 声明仓库 用于获取 Spring AI 以及相关预发布版本--repositoriesrepositoryidspring-snapshots/idnameSpring Snapshots/nameurlhttps://repo.spring.io/snapshot/urlreleasesenabledfalse/enabled/releases/repositoryrepositorynameCentral Portal Snapshots/nameidcentral-portal-snapshots/idurlhttps://central.sonatype.com/repository/maven-snapshots//urlreleasesenabledfalse/enabled/releasessnapshotsenabledtrue/enabled/snapshots/repository/repositories智谱 AI 依赖包dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-zhipuai/artifactId/dependencyDeepSeek 依赖包dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-deepseek/artifactId/dependency3. 聊天模型3.1 编写 application.properties首先设置关于模型的全局默认参数。# 配置 Deepseek URL、API Key、模型 spring.ai.deepseek.base-urlhttps://api.deepseek.com spring.ai.deepseek.api-key spring.ai.deepseek.chat.options.modeldeepseek-flash # 配置温度范围 0-22 发散 spring.ai.deepseek.chat.options.temperature0.8 # 配置日志 logging.pattern.console %-5level %logger - %msg%n接下来设置关于模型的运行时参数。如下图所示DeepSeekChatModel 支持在运行时动态调整模型参数灵活应对不同场景的需求。3.2 核心APISpring AI 的 ChatModel 提供一套统一接口方便开发者在应用中集成 AI 聊天完成功能。它支持切换不同模型供应商的聊天模型如 OpenAI、Anthropic、Google Gemini、Amazon Bedrock、Ollama 等多数实现支持流式输出和函数调用等功能。Autowired// DeepSeekChatModel 为 ChatModel接口的实现类privateDeepSeekChatModelchatModel;/**Flux 是一个“可以异步地、陆续发出多个数据”的容器。 可以把它想成一条水管 - 普通 ListString所有数据一次性给你。 - FluxString数据像水流一样一个一个地流过来可能分很多次到达。 一个会陆续收到多个 ChatResponse的流。 调用模型时不是一次性返回完整回答而是一段一段地返回。每次模型吐出一点内容就产生一个 ChatResponse。 **/FluxChatResponsestreamchatModel.stream(prompt);FluxStringrespstream.map(chatResponse-chatResponse.getResult().getOutput().getText());3.3 几个主流模型供应商的差异Anthropic 与 OpenAI 的区别Anthropic 由 OpenAI 的前核心成员创立其主打产品是 Claude 系列大模型。两者最大的区别在于核心哲学OpenAI 追求更强大的通用能力和自主性而 Anthropic 则将安全、可控和可解释性置于首位。OpenAIGPT 系列如 GPT-5.4、GPT-6 Astra 等以强大的通用推理和编程能力著称。AnthropicClaude 系列如 Claude Opus 5、Claude Fable 5.1 等在编程、复杂任务分解和安全性方面表现突出。DeepSeek 与智谱DeepSeek 和智谱代表了中国 AI 力量的两极一个用开源和极致效率挑战技术霸权另一个用全面商业化和国产化生态构建产业壁垒。4. 向量模型文档会先被切成若干个 chunk。由于 Embedding 模型有最大 token 限制例如一次只能处理 8192 个 token所以长文本必须切成多个 chunk每个 chunk 送入 embedding 模型后会得到一个对应的向量并作为一行存入向量数据库因此一个 chunk 对应数据库里的一行。用户提问时问题也会被送入 embedding 模型变成一个 query 向量然后拿这 1 个 query 向量去和数据库里每一行的 chunk 向量计算相似度比如余弦相似度也就是 1 个 query 向量 vs N 个 chunk 向量。最后按相似度排序取出最相似的 top-k 个 chunk作为上下文交给大模型。4.1 编写 application.properties## 智谱 AI 相关配置 spring.ai.zhipuai.base-urlhttps://open.bigmodel.cn/api/paas spring.ai.zhipuai.api-keyyour_api_key # Embedding 模型配置 spring.ai.zhipuai.embedding.options.modelembedding-2 # chat 模型配置 spring.ai.zhipuai.chat.options.modelGLM-4-Flash4.2 核心API!-- spring-ai-client-chat 中包括 TokenTextSplitter、TextReader、Document 等工具 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-client-chat/artifactIdversion1.0.0/version/dependencySpring AI 通过其 EmbeddingModel 接口提供一套统一、简单、可替换的访问方式支持多种底层模型如 OpenAI、Titan、Azure、Ollama、智谱等这样可以统一接口切换模型仅需要改配置不改调用逻辑。privateEmbeddingModelembeddingModel;privatefinalListfloat[]docVectors;//准备知识库文本内容privatefinalListStringdocsList.of(美食非常美味服务员也很友好,这部电影既刺激又令人兴奋,阅读书籍是扩展知识的好方法);/** * 根据用户输入的 query从已向量化的文档中找出最相似的一条文本 * * param query 用户输入的查询文本 * return 与 query 最相似的文档原文若无文档则返回 null */publicStringqueryBestMatch(Stringquery){// 0. 边界检查文档为空直接返回 null避免后面 bestIdx 一直为 -1 导致越界if(docVectorsnull||docVectors.isEmpty()){returnnull;}// 1. 对用户传入的 query 进行向量化float[]queryVecembeddingModel.embed(query);// 1.1 提前计算 query 向量的模长避免在循环里重复计算doublequeryNormnorm(queryVec);// 用于记录当前最大相似度和对应的下标doublebestSim-1;intbestIdx-1;// 2. 遍历所有文档向量逐个计算余弦相似度找出最相似的一个for(inti0;idocVectors.size();i){float[]docVecdocVectors.get(i);// 计算 query 与该文档向量的余弦相似度doublesimcosineSimilarity(queryVec,queryNorm,docVec);// 更新最大值if(simbestSim){bestSimsim;bestIdxi;}}// 3. 返回最相似文档的原文returndocs.get(bestIdx);}/** * 计算两个向量的余弦相似度 * * param a 向量 a * param normA 向量 a 的模长提前算好避免重复计算 * param b 向量 b * return 余弦相似度范围 [-1, 1]若任一向量模长为 0 则返回 0 */privatedoublecosineSimilarity(float[]a,doublenormA,float[]b){// 先算 b 的模长doublenormBnorm(b);// 防止除零任一向量为零向量时认为相似度为 0if(normA0||normB0){return0;}// 计算点积doubledot0;for(inti0;ia.length;i){dota[i]*b[i];}// 余弦相似度 点积 / (模长a * 模长b)returndot/(normA*normB);}/** * 计算向量的模长L2 范数 */privatedoublenorm(float[]v){doublesum0;for(floatx:v){sumx*x;}returnMath.sqrt(sum);}float[] queryVec embeddingModel.embed(query); 这行代码返回的float[]是一个普通的 Java 数组它被存储在当前应用程序的内存中即 JVM 的堆内存里。它只是一个临时变量一旦方法结束这个数组就可能被垃圾回收不会自动被存入任何数据库。4.3 几个主流向量数据库的比较阶段这个阶段在干什么推荐方案核心理由关键提醒个人学习跑通 RAG 基本流程文档 → chunk → embedding → 向量库 → 检索 → 交给大模型Chroma安装最简单支持内存模式几行代码就能跑教程多和 LangChain 等集成成熟是理解 RAG 的最佳起点适合本地实验和小数据量不要用于大规模或生产原型验证快速做一个小样验证想法、技术路线、检索效果是否可行Qdrant 或 pgvectorQdrant性能好、元数据过滤强、单个 Docker 就能跑pgvector已有 PostgreSQL 时最省事数据量小可直接用 SQL 统一管理原型验证不是“测试环境里的正式应用”它追求快和验证最好用真实业务数据子集测试别只看玩具数据生产环境正式上线要考虑规模、稳定、运维、合规、成本Milvus / Pinecone / pgvectorMilvus大规模、私有化部署、功能全面Pinecone全托管 SaaS免运维pgvector小规模或已有 PostgreSQL成本低、架构简单必须做压测、监控、备份、权限和成本评估根据数据规模、团队运维能力和合规要求权衡