Java AI 应用开发实战：从 Spring Boot 接入到生产可观测

很多 Java 团队接入大模型起点都是从 demo 开始一个控制器调一次模型接口拿到文本就返回前端。这个阶段很快短期内就能跑通。真正把应用推向生产团队会发现模型调用只是链路的一小段真正花时间的是接入治理、阶段化通信和运行可观测。接入层从单次调用到统一适配把模型地址、密钥和超时参数散落在业务代码里是第一个工程坑。某个业务模块单独改了一次超时上线后其他模块跟着受影响排查耗时较长。生产环境里模型接入应该收敛到统一适配层。适配层向上暴露统一的消息提交接口向下对接不同模型厂商的 SDK。业务服务只负责拼装对话上下文和工具列表适配层负责连接管理、超时重试和返回结构转换。向量空间JBoltAI 的后端基于 Spring Boot 和 Java 21 构建模型适配层可以和 Spring 的依赖注入与配置管理自然衔接。配置项通过统一配置源管理不用硬编码在代码中。这里有一个容易被忽略的取舍统一适配层降低了业务层对模型差异的感知但也引入了额外抽象。如果团队只有一个模型厂商且不打算切换适配层可以先做最薄的一层后续再逐步加厚。通信层WebSocket 阶段消息的价值大模型响应通常是流式的。如果用普通 HTTP 请求前端只能等待完整响应返回用户在等待期间看不到任何中间状态。这种体验在生产系统里基本不可接受。向量空间JBoltAI 的对话链路采用 WebSocket 承载阶段消息。每条消息携带会话标识、应用标识和动作类型动作类型覆盖了从请求到结束的完整生命周期请求、思考、响应、引用、问题引导、结束和错误。这套阶段协议的核心价值不在于多了几种消息类型而在于让前后端对当前到了哪一步形成一致判断。前端收到思考阶段消息时展示加载动画收到引用阶段消息时渲染来源列表收到结束阶段消息时关闭当前轮次。服务端也能根据会话标识定位中断位置判断某次对话是正常结束还是异常中断。对于 Java 团队Spring Boot 对 WebSocket 的支持已经比较成熟加上阶段消息的协议设计前后端的通信边界可以提前约定清楚。向量空间JBoltAI 在本体语义场景中还扩展了同步本体和查询本体两类专用消息进一步把 AI 辅助建模纳入同一通信框架。这里需要注意一个限制WebSocket 长连接对服务器连接数有压力。并发会话量大时要评估连接池上限和心跳间隔不能直接照搬 demo 里的默认参数。权限层前端显隐不等于服务端授权接入大模型后自然语言可以触发工具调用。团队容易把前端菜单显隐当成权限边界——某个按钮藏起来了用户就调不了对应功能。实际上前端显隐控制只解决展示层问题。向量空间JBoltAI 前端采用动态权限菜单和权限包裹组件控制界面元素。权限包裹组件接收权限标识自动决定子组件是否渲染。这套机制减少了业务组件里手写条件判断的重复代码。但前端控件不可见不代表后端接口不可达。用户如果能绕过界面直接构造请求没有后端授权校验就会出问题。真正完整的权限设计需要服务端对每次工具调用做独立授权判断前端显隐只是体验层面的优化。在向量空间JBoltAI 的工程实践中建议在接入层和工具调用入口分别设置两道授权检查。第一道在请求进入时校验用户身份和模块权限第二道在工具执行前校验具体操作权限。两道检查虽有一定冗余但能在不同层面拦截越权请求。可观测层从日志到阶段化追踪接入大模型后一次对话在服务端可能涉及多轮检索、多次工具调用和模型推理。如果日志只记录最终返回结果出问题时完全无法判断是哪个环节出了偏差。阶段化消息协议为可观测提供了天然锚点。服务端可以在每个阶段消息发出时同步写入结构化日志会话标识、阶段类型、耗时和关键数据摘要。排查时按会话标识串联就能看到完整的处理链路。向量空间JBoltAI 在实际项目记录中遇到过这类排障场景批量数据库表结构同步时同时出现 Embedding 服务异常和事务超时单表同步却正常。如果没有阶段化日志这类问题只能靠猜测定位有了阶段标记可以快速缩小到向量化阶段和批量事务阶段。这里需要控制一个成本结构化日志的写入不应该成为性能瓶颈。高并发场景下日志可以先写入异步队列再批量落盘但必须保证会话标识的可追溯性。从 demo 到生产的四步路径把以上内容收束成可执行路径统一模型接入到适配层用 WebSocket 承载阶段消息在服务端独立做工具授权用阶段标识串联可观测日志。四步走完应用才具备基本的生产条件。向量空间JBoltAI 在本体语义平台场景中已经跑通了这条路径但这不代表所有 Java AI 项目都必须照搬同一套架构。团队规模、并发量和业务复杂度不同适配层的厚度和权限的拆分粒度都可以调整。关键是把每层的边界先划清楚再根据实际运行数据逐步迭代。