简介这是一套面向计算机、电子信息工程及数学等专业本科生的毕业设计与课程实践参考项目基于Spring Boot构建了具备多模型接入能力的人工智能交互机器人系统有效解决学生在AI应用开发中模型对接复杂、后端集成困难、前后端协同不畅等典型问题。资源包共1157个文件涵盖584个Java核心业务与控制器类、104个Vue前端组件、108个JavaScript逻辑脚本、73个XML配置及149个PNG界面资源辅以YML配置、SQL建表、Dockerfile容器化支持等完整呈现企业级AI应用的分层架构与工程规范压缩包大小为26.84MB。目前已有1235人学习下载可直接用于期末大作业或毕设开题提供从大模型API统一调度、多模态响应文本AI绘图、前后端分离部署到主流国产/国际模型GPT-3.5/4.0、Kimi、文心一言、Stable Diffusion、Midjourney的全链路实现参考。1. 这不是又一个“调 API 的 Spring Boot 项目”它把大模型交互拆成了可插拔、可审计、可回滚的模块毕业设计答辩时导师盯着看了三分钟你肯定见过那种“Spring Boot OpenAI Key 一行 RestTemplate 调用”的机器人 demo——跑得通但一问“如果模型返回乱码怎么定位”“用户发了敏感词谁来拦截”“换 Qwen 不改代码行不行”当场哑火。这个项目不一样它把大模型交互抽象成ModelProvider 接口 Strategy 路由 MessageChain 消息链三层结构OpenAI、Azure、Ollama、本地 GGUF 全部走同一套注入逻辑所有请求/响应自动落库含 token 统计、耗时、错误堆栈甚至支持按会话 ID 回溯完整对话树。某高校毕业设计组用它做“智能教务问答系统”答辩时导师没问技术栈而是翻着message_log表问“这条超时请求为什么没触发熔断你们的 fallback 策略在哪实现的”——答案就在FallbackModelProvider类里。适合需要真实交付感、可演示细节、能讲清设计权衡的毕业设计或内部 PoC。2. 项目结构与核心依赖从 Maven 依赖到包结构看清它为什么“不裸奔”2.1 依赖选型为什么不用 Spring AI为什么坚持手写 ModelProvider项目没引入 Spring AI原因很实际Spring AI 0.8.x 对 Ollama 和本地 GGUF 支持弱且其ChatClient抽象层强制要求所有模型返回ResponseChatResponse而 Azure OpenAI 的 streaming 响应格式和本地 llama.cpp 的 JSON-RPC 返回结构差异太大硬套会导致大量instanceof判断和类型转换异常。本项目选择自己定义ModelProvider接口public interface ModelProvider { /** * 同步调用返回完整响应适合小模型/低频场景 * param request 请求体已包含 model name、messages、temperature 等 * return 标准化响应含 content、usage、finishReason */ ModelResponse syncCall(ModelRequest request); /** * 流式调用通过 Consumer 推送 chunk必须支持否则前端打字效果失效 * param request 同上 * param chunkConsumer 每收到一个 token 就调用一次 */ void streamCall(ModelRequest request, ConsumerModelChunk chunkConsumer); }提示ModelRequest和ModelResponse是项目自定义 DTO字段完全对齐 OpenAI v1 API 规范messages,model,temperature,max_tokens但额外增加了sessionId、traceId、source标识是 web / api / cli 调用字段为后续审计埋点。关键依赖清单pom.xml 片段!-- 必须Web 层 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 必须数据库审计日志 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency !-- 必须HTTP 客户端比 RestTemplate 更可控 -- dependency groupIdio.github.openfeign/groupId artifactIdfeign-core/artifactId version12.5/version /dependency dependency groupIdio.github.openfeign/groupId artifactIdfeign-jackson/artifactId version12.5/version /dependency !-- 可选但强烈建议配置中心化 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-configuration-processor/artifactId optionaltrue/optional /dependency2.2 包结构ai.model是心脏ai.audit是骨架ai.web是皮肤src/main/java/com/example/ai/ ├── AiApplication.java // 主启动类EnableJpaAuditing ├── ai/ │ ├── audit/ // 审计核心 │ │ ├── entity/MessageLog.java // 主表id, session_id, trace_id, model_name, ... │ │ ├── repository/MessageLogRepository.java │ │ └── aspect/AuditAspect.java // Around(execution(* ai.service..*.*(..))) 自动记录 │ │ │ ├── model/ // 大模型能力中枢重点 │ │ ├── dto/ // ModelRequest / ModelResponse / ModelChunk │ │ ├── provider/ // 所有实现类在此 │ │ │ ├── openai/OpenAiProvider.java // OpenAI 官方 API │ │ │ ├── azure/AzureOpenAiProvider.java // Azure 部署版需 endpoint api-key deployment-name │ │ │ ├── ollama/OllamaProvider.java // 本地 Ollamahttp://localhost:11434/api/chat │ │ │ └── fallback/FallbackModelProvider.java // 熔断降级返回预设话术 or 转人工 │ │ ├── strategy/ // 路由策略 │ │ │ ├── LoadBalanceStrategy.java // 权重轮询给不同模型配权重 │ │ │ └── RuleBasedStrategy.java // 基于 sessionId 或 userRole 路由 │ │ └── service/ModelService.java // 门面聚合 provider strategy audit │ │ │ ├── web/ // Web 层 │ │ ├── controller/ChatController.java // /api/chat POST主入口 │ │ ├── dto/ChatRequest.java // { sessionId: ..., messages: [...] } │ │ └── config/WebMvcConfig.java // 配置 StreamingResponseBody 支持 SSE │ │ │ └── config/ // 配置类 │ ├── ModelProviderConfig.java // Configuration ConditionalOnProperty 控制启用哪些 provider │ └── AuditConfig.java // JPA Auditing 配置这个结构意味着你要换模型只改provider/下一个类要加审计字段只改MessageLog.java和AuditAspect要改路由逻辑只碰strategy/。没有“改一处八处报错”的玄学耦合。3. 核心模块拆解OpenAiProvider与OllamaProvider的实现差异与统一抽象3.1OpenAiProvider如何处理 OpenAI 的 streaming 响应SSE并转成标准ModelChunkOpenAI 的/v1/chat/completionsstreaming 响应是 Server-Sent EventsSSE格式每行以data:开头末尾双换行。直接用RestTemplate解析极容易丢 chunk 或阻塞。本项目用 Feign 自定义 Decoder// openai/OpenAiProvider.java Override public void streamCall(ModelRequest request, ConsumerModelChunk chunkConsumer) { // 1. 构建 Feign Client复用已配置的 OkHttpClient OpenAiFeignClient client Feign.builder() .decoder(new OpenAiSseDecoder(chunkConsumer)) // 关键自定义解码器 .target(OpenAiFeignClient.class, https://api.openai.com/v1); // 2. 构建请求体注意OpenAI 要求 messages 是 ListMapString, String MapString, Object body new HashMap(); body.put(model, request.getModel()); body.put(messages, toOpenAiMessages(request.getMessages())); body.put(stream, true); body.put(temperature, request.getTemperature()); // 3. 发起流式调用 client.streamChat(body); } // 自定义 SSE 解码器核心逻辑 static class OpenAiSseDecoder implements Decoder { private final ConsumerModelChunk chunkConsumer; OpenAiSseDecoder(ConsumerModelChunk chunkConsumer) { this.chunkConsumer chunkConsumer; } Override public Object decode(Response response, Type type) throws IOException { try (BufferedReader reader new BufferedReader( new InputStreamReader(response.body().asInputStream()))) { String line; while ((line reader.readLine()) ! null) { if (line.startsWith(data: )) { String json line.substring(6).trim(); if (!json.equals([DONE])) { // 解析 OpenAI 的 chunk JSON JsonNode node objectMapper.readTree(json); String content ; if (node.has(choices) node.get(choices).size() 0) { JsonNode delta node.get(choices).get(0).get(delta); if (delta.has(content)) { content delta.get(content).asText(); } } // 转成标准 ModelChunk ModelChunk chunk new ModelChunk(); chunk.setContent(content); chunk.setFinishReason(node.has(choices) node.get(choices).get(0).has(finish_reason) ? node.get(choices).get(0).get(finish_reason).asText() : null); chunkConsumer.accept(chunk); // 推送给前端 } } } } return null; } }参数说明toOpenAiMessages()方法将通用ListMessage转为 OpenAI 要求的ListMapString,String其中role必须是system/user/assistantcontent不能为空字符串OpenAI 会报错。这是血泪经验曾因传入导致 400 错误日志里只显示Bad Request最后抓包才发现是 content 字段问题。3.2OllamaProvider如何兼容 Ollama 的 JSON-RPC 风格 API 并保持接口一致Ollama 的/api/chat接口是同步 JSON-RPC 风格但本项目要求streamCall必须支持流式——解决方案是用OkHttpClient的 EventSourceSSE客户端伪装成流式。Ollama 实际返回的是普通 JSON但项目在OllamaProvider内部做了“流式包装”// ollama/OllamaProvider.java Override public void streamCall(ModelRequest request, ConsumerModelChunk chunkConsumer) { // 1. 构建 Ollama 请求体注意Ollama 用 model 字段不是 model_name MapString, Object body new HashMap(); body.put(model, request.getModel()); // 如 qwen:7b body.put(messages, toOllamaMessages(request.getMessages())); // role 映射user-user, assistant-assistant body.put(stream, true); // 关键告诉 Ollama 返回流式 // 2. 用 OkHttp 直接发起 POST不走 Feign因 Ollama 无标准 REST Request okRequest new Request.Builder() .url(http://localhost:11434/api/chat) .post(RequestBody.create( objectMapper.writeValueAsBytes(body), MediaType.parse(application/json))) .build(); try (Response response okHttpClient.newCall(okRequest).execute()) { if (!response.isSuccessful()) throw new RuntimeException(Ollama call failed: response.code()); // 3. 逐行读取 Ollama 的流式 JSON每行一个 JSON object try (BufferedReader reader new BufferedReader( new InputStreamReader(response.body().byteStream()))) { String line; while ((line reader.readLine()) ! null) { if (line.trim().isEmpty()) continue; JsonNode node objectMapper.readTree(line); // Ollama chunk 结构{message:{role:assistant,content:...},done:false} if (node.has(message) node.get(message).has(content)) { ModelChunk chunk new ModelChunk(); chunk.setContent(node.get(message).get(content).asText()); chunk.setFinishReason(node.has(done) node.get(done).asBoolean() ? stop : null); chunkConsumer.accept(chunk); } } } } catch (Exception e) { log.error(Ollama stream error, e); throw new RuntimeException(e); } }关键差异点OpenAI 的messages中role必须小写userOllama 同样要求小写但某些旧版 Ollama 文档写成User会导致 400Ollama 的model字段值是ollama list输出的名称如llama3:8b不是 OpenAI 的gpt-4-turboOllama 默认不返回usage字段所以ModelResponse.usage在 Ollama 路径下为null前端需兼容。3.3FallbackModelProvider熔断不是摆设它是可配置、可测试的兜底逻辑当所有模型 provider 都超时或返回 5xx 时FallbackModelProvider被触发。它不是简单返回“服务器忙”而是支持三种策略策略类型配置方式行为说明STATICfallback.typestaticfallback.message请稍后再试返回固定文本RULE_BASEDfallback.typerulefallback.rules[0].pattern.*密码.*fallback.rules[0].response请勿在对话中输入密码正则匹配敏感词后返回定制回复HUMAN_TRANSFERfallback.typehumanfallback.humanUrlhttps://your-crm.com/ticket?msg{message}生成工单链接并返回// fallback/FallbackModelProvider.java Override public ModelResponse syncCall(ModelRequest request) { String userInput request.getMessages().get(request.getMessages().size() - 1).getContent(); // 1. 检查是否命中敏感规则 for (FallbackRule rule : fallbackRules) { if (Pattern.compile(rule.getPattern()).matcher(userInput).find()) { return buildResponse(rule.getResponse(), request.getSessionId()); } } // 2. 否则走 human transfer String ticketUrl fallbackConfig.getHumanUrl().replace({message}, URLEncoder.encode(userInput, StandardCharsets.UTF_8)); return buildResponse(已为您创建服务工单 ticketUrl, request.getSessionId()); } private ModelResponse buildResponse(String content, String sessionId) { ModelResponse resp new ModelResponse(); resp.setContent(content); resp.setFinishReason(stop); resp.setUsage(new ModelUsage(0, 0, 0)); // 占位 // 记录到 audit 表 auditService.logFallback(sessionId, content); return resp; }注意auditService.logFallback()会插入一条MessageLogmodel_name字段为FALLBACKerror_message字段存原始异常如果有的话方便后期统计“降级率”。4. 运行与调试从零启动到看到第一个流式响应避坑指南4.1 启动前必做的 3 件事确认 JDK 版本项目基于 Spring Boot 3.2必须使用 JDK 17 或 JDK 21。用 JDK 8 或 JDK 11 会报java.lang.UnsupportedClassVersionError且record类型无法编译。配置application.yml中的模型凭证ai: providers: openai: enabled: true api-key: sk-xxx # 替换为你自己的 key base-url: https://api.openai.com/v1 ollama: enabled: true base-url: http://localhost:11434 # 确保 Ollama 已运行ollama serve提示base-url末尾不要加/否则 Feign 会拼出https://api.openai.com/v1//chat/completions导致 404。初始化 H2 数据库项目默认用 H2 内存库启动时自动建表。若想看日志表访问http://localhost:8080/h2-console填入JDBC URL:jdbc:h2:mem:testdbUser Name:saPassword: 空然后执行SELECT * FROM message_log;查看审计记录。4.2 第一个请求curl 测试流式接口别急着打开网页先用 curl 验证底层通路# 发送流式请求注意 -N 参数禁用缓冲 curl -N -X POST http://localhost:8080/api/chat \ -H Content-Type: application/json \ -d { sessionId: test-123, messages: [ {role: user, content: 你好请用中文介绍你自己} ] }预期输出逐行打印data: {content:我是,finishReason:null} data: {content:一个,finishReason:null} data: {content:基,finishReason:null} data: {content:于,finishReason:null} data: {content:Sp,finishReason:null} ... data: {content:。,finishReason:stop}如果卡住不动检查OpenAiProvider中Feign.builder().decoder(...)是否被正确注入检查网络curl -v https://api.openai.com/v1/models是否返回 200检查日志grep streamCall logs/app.log看是否有Entering streamCall日志。4.3 常见问题排查5 条真实踩坑记录现象 1前端页面显示“连接已关闭”但后端日志无报错原因Spring Boot 默认server.tomcat.connection-timeout2000020秒而大模型响应慢尤其本地 Ollama 7B 模型Tomcat 主动断开连接。解决在application.yml中增加server: tomcat: connection-timeout: 60000 # 60秒现象 2Ollama 返回{error:model not found}但ollama list显示模型存在原因Ollama 模型名区分大小写ollama run qwen:7b启动后模型名是qwen:7b但代码里写了Qwen:7b。解决检查application.yml中ai.providers.ollama.model-name值确保与ollama list输出完全一致包括冒号和版本号。现象 3审计表message_log中request_body字段为空原因AuditAspect使用Before切面但ModelRequest是方法参数未被序列化。原代码用JSON.toJSONString(joinPoint.getArgs())会丢失泛型信息导致空字符串。解决改用 Jackson 序列化ObjectMapper mapper new ObjectMapper(); String requestBody mapper.writeValueAsString(joinPoint.getArgs()[0]); // 假设第一个参数是 ModelRequest现象 4切换模型后FallbackModelProvider仍被调用原因ModelService中的getProvider()方法用了Cacheable但缓存 key 未包含request.getModel()导致第一次失败后后续所有请求都走 fallback。解决修改缓存 keyCacheable(value modelProviders, key #model _ #sessionId) public ModelProvider getProvider(String model, String sessionId) { ... }现象 5本地运行时IDEA 控制台中文乱码显示为?原因Windows 系统默认编码是 GBK而项目用 UTF-8。解决在 IDEA → Settings → Editor → File Encodings → Global Encoding 和 Project Encoding 全部设为UTF-8并在Run Configuration→VM Options加-Dfile.encodingUTF-8。5. 二次开发实战如何接入千问 QwenQwen2-7B-Instruct并支持函数调用Function Calling5.1 接入 Qwen2-7B-Instruct只需新增一个 Provider 类Qwen2 的 API 兼容 OpenAI 格式感谢魔搭社区所以无需重写streamCall只需继承OpenAiProvider并覆盖基础 URL 和认证// qwen/Qwen2Provider.java Component ConditionalOnProperty(name ai.providers.qwen.enabled, havingValue true) public class Qwen2Provider extends OpenAiProvider { // 重写父类的 baseUrl 和 apiKey 获取逻辑 Override protected String getBaseUrl() { return https://dashscope.aliyuncs.com/compatible-mode/v1; // 阿里云 DashScope 兼容地址 } Override protected String getApiKey() { return qwenConfig.getApiKey(); // 从配置读取 } // Qwen2 要求 model 字段为 qwen2-7b-instruct且需加 qwen/ 前缀 Override public ModelResponse syncCall(ModelRequest request) { ModelRequest wrapped new ModelRequest(); wrapped.setMessages(request.getMessages()); wrapped.setModel(qwen/qwen2-7b-instruct); // 注意前缀 wrapped.setTemperature(request.getTemperature()); wrapped.setMaxTokens(request.getMaxTokens()); return super.syncCall(wrapped); } }配置application.ymlai: providers: qwen: enabled: true api-key: sk-xxx-from-dashscope注意DashScope 的免费额度有限生产环境需替换为自部署的 Qwen2用ollama run qwen2:7b此时Qwen2Provider应继承OllamaProvider并覆盖getBaseUrl()为http://localhost:11434。5.2 支持 Function Calling扩展ModelRequest并改造OpenAiProviderOpenAI 的 function calling 要求请求体包含functions和function_call字段。本项目将其作为可选能力扩展ModelRequestDTOpublic class ModelRequest { private ListMessage messages; private String model; // ... 其他字段 private ListFunctionSpec functions; // 新增函数列表 private String functionCall; // 新增auto | none | function_name }在OpenAiProvider的buildRequestBody()中加入函数字段private MapString, Object buildRequestBody(ModelRequest request) { MapString, Object body new HashMap(); body.put(model, request.getModel()); body.put(messages, toOpenAiMessages(request.getMessages())); if (request.getFunctions() ! null !request.getFunctions().isEmpty()) { body.put(functions, request.getFunctions()); // 直接序列化 body.put(function_call, request.getFunctionCall() ! null ? request.getFunctionCall() : auto); } return body; }解析 function call 响应OpenAI 返回的finish_reason为function_call时message.content为空message.function_call字段存在。在OpenAiSseDecoder中增强解析逻辑if (node.has(choices) node.get(choices).size() 0) { JsonNode choice node.get(choices).get(0); if (choice.has(finish_reason) function_call.equals(choice.get(finish_reason).asText())) { JsonNode funcCall choice.get(message).get(function_call); if (funcCall ! null) { chunk.setFunctionName(funcCall.get(name).asText()); chunk.setFunctionArguments(funcCall.get(arguments).asText()); } } }这样前端就可以发送带函数定义的请求并在收到function_call事件后调用对应后端服务如查天气、查订单再把结果塞回messages继续对话。5.3 验证函数调用一个完整的 curl 测试链# 1. 定义函数查天气 curl -X POST http://localhost:8080/api/chat \ -H Content-Type: application/json \ -d { sessionId: func-test, messages: [{role:user,content:北京今天天气怎么样}], functions: [{ name: get_weather, description: 获取指定城市的天气, parameters: { type: object, properties: {city: {type: string, description: 城市名}} } }], functionCall: auto }预期响应流中会出现data: {functionName:get_weather,functionArguments:{\city\:\北京\},finishReason:function_call}然后你的业务代码捕获该 chunk调用WeatherService.get(北京)得到结果后构造新消息{ role: function, name: get_weather, content: {\temperature\:25,\condition\:\晴\} }再发一次/api/chat请求即可获得最终回答“北京今天 25 度晴。”从那以后我每次接入新模型都强制走一遍这三步用 curl 测通syncCall用 curl -N 测通streamCall用 Postman 发送带functions的请求验证function_call解析。漏掉任何一步上线后都会在凌晨三点被报警电话叫醒。希望帮到你。本文还有配套的精品资源点击获取
