企业官网建设流程全解析

1. 先把问题说清楚：Java和LLM之间的那道"断层"

这几年大模型火到什么程度，连Java面试题里都开始混进"你怎么理解LangChain""项目里有没有接过大模型"这类问题。可真到了工作里，大部分Java团队的处境其实很尴尬：模型研究、Prompt实验、微调脚本，清一色是Python天下；一旦要上线，业务系统是Java的，服务治理是Java的，监控链路是Java的，最后卡壳的恰恰是"怎么把模型能力接进现有Java工程"。

我接过不少这类烂摊子：有拿Python写个中转服务，再让Java去调HTTP的，结果运维要维护两套环境；有直接裸调模型API的，返回的流式数据在Java端解析成一锅粥；还有更典型的，模型接口一慢，业务线程池直接被打满，整条链路都跟着瘫痪。这些问题不是模型不行，而是缺少一层"Java原生"的适配。所谓原生，不是说框架里写了几个Java类那么简单，而是它生来就活在Java的生态里，懂Spring的Bean生命周期，懂事务、懂监控、懂线程模型，不让你awkward地把AI能力像异物一样硬塞进去。

这篇文章想聊的就是这件事的完整解法：Java生态里做LLM落地的原生框架怎么选、关键节点的工程细节怎么处理、以及一份能直接抄的实操示例。想让不同基础的读者都能对上号，我尽量把每个"为什么"都讲透——不是网上那种"加个依赖就能跑"的教程，而是跑完以后你还能跟同事解释清楚每一步的取舍。

1.1 模型在Python手里，业务在Java手里，谁去弥合

先把大环境说透。大模型训练、评估、微调这条链路，Python确实无可替代，生态和科学计算库摆在那儿，没必要嘴硬。但落到企业应用里，尤其是金融、制造、政企这类系统，核心服务十有八九跑在JVM上。这时候如果为了接AI单独养一个Python服务，等于给架构凭空添了个"二等公民"：它没有注册中心接入，没有配置中心下发，日志体系对不上，监控指标要从另一个口径去采集，出了问题排查链路直接断裂。

更麻烦的是，Java和LLM之间不是"发个HTTP请求"那么简单。一次完整的对话，背后有会话轮次管理、上下文裁剪、工具调用约束、流式响应处理、结构化结果转换、Token用量统计这一整套动作。你自己用HttpClient写一遍，一开始能跑，两周后就会在某个诡异场景里翻车——不是少传了历史消息，就是模型返回的JSON里裹了一层Markdown代码块，解析逻辑越写越厚，最后变成没人敢动的定时炸弹。

原生框架解决的正是这个"断层"：它把模型交互封装成Java开发者熟悉的编程模型，你操作的是ChatClient、Prompt、Message、Tool这些有明确语义的对象，而不是对着JSON字符串做正则。这套抽象，才是打通落地最后一公里的地基。

1.2 所谓"原生框架"，到底原生在哪

"原生"这个词这两年有点被用滥了。我的理解很朴素：真正Java原生的框架，至少要满足三点。

第一，开发模型贴合Java习惯。最好的例子是Spring AI，直接用ChatClient这种链式API，跟你写RestClient、JdbcTemplate的感觉一致。配置走application.yml，扩展走Spring机制，不需要自己造胶水层。

第二，生态组件是长在一起的。跟Spring Boot、Spring Cloud、Micrometer观测体系、GraalVM原生镜像这些Java世界的标准设施天然打通，而不是靠一堆手动集成去补。

第三，部署形态灵活。既能接SaaS模型，也能接内网部署的开源模型，还能以Native Image形式打包成小镜像快速启动。对生产环境来说，最后这一点往往比功能齐全更值钱。

反观那些"用Java调Python服务"的方案，模型逻辑在一个进程里，业务逻辑在另一个进程里，中间隔着网络和一堆自定义协议，每次改动都牵一发动全身。这不是技术问题，是架构决策问题。原生框架想做的，就是让你在Java进程里，像调用本地方法一样调用大模型能力，把两端真正焊在一起。

2. 主流Java LLM框架选型：Spring AI、LangChain4j、DJL到底怎么挑

框架不是越多越好，选错了后面返工的代价极大。我在项目里把市面上叫得出名字的Java侧AI框架都试过一遍，这里直接给结论性对比，再补上真实的选型逻辑。

2.1 Spring AI：Spring生态的嫡系选手

Spring AI从2023年起就在Spring官方孵化，2025年出了1.0.0 GA，算是正式进入稳定期。它对Spring Boot 3.x项目的侵入性最低，核心抽象是ChatClient，从简单问答到Agent式的工具调用，都在这一个API上做文章。它最突出的优势在三点：

• 配置即服务。在application.yml里声明spring.ai.openai.base-url、模型名、温度这些参数，剩下的交给自动装配。将来把模型服务从内网网关换到云端厂商，改配置就行，业务代码零改动。
• 可观测性内置。基于Micrometer的Observation API，Token用量、请求耗时、调用次数都有标准指标埋点，接Prometheus和OpenTelemetry都不用自己写。
• 工具调用做得顺。直接在Java方法上标注@Tool注解，模型就能"看到"这个方法并在合适的时机调用它，本质上把函数调用变成了Spring风格的声明式编程。

如果你团队本来就在Spring Boot上，Spring AI基本是默认答案。代价是它比较年轻，1.x版本迭代中还出现过配置项变动，升级时得留意ChangeLog。

2.2 LangChain4j：轻量、模块化、老项目也能用

LangChain4j是社区项目，口号是"给Java开发者的LangChain"。它最大的差异化是底子薄、模块拆得细，核心包只有几十KB，Java 8的老系统也能跑，这意味着大量遗留项目不需要为了接AI先升到JDK 17。它支持的模型厂商、向量库、Embedding模型适配器非常全，从OpenAI兼容接口到Ollama、vLLM、Qwen、DeepSeek都有对应模块。

它的API风格比Spring AI更贴近LangChain的思维，链式组装记忆、RAG、工具调用，逻辑很直白。如果你没有Spring Boot的包袱，或者想在非Spring项目里引入AI能力，LangChain4j是更轻的选择。它也有Spring Boot的启动器模块，所以两边其实可以互相补位。

2.3 DJL：想直接在JVM里跑推理，就看它

DJL（Deep Java Library）是AWS出品的深度学习推理框架，定位跟前面两个完全不同。它不是"调用远端模型API"的客户端，而是让你直接在Java进程里加载PyTorch、TensorFlow、ONNX格式的模型做推理。它对Embedding这类需要高频调用、又不想每次都走网络请求的场景特别合适——比如用本地Embedding模型做向量化，直接在Java里算好再写入向量库，省掉一条网络链路。

代价是DJL的学习曲线陡一些，模型转换、资源管理、推理优化都得自己上手，它面向的是"Java侧的模型推理引擎"这个赛道，而不是对话应用的便捷封装。我的建议是：做纯对话/Agent应用用它不划算，需要自己做离线推理、批处理、或向量化时再考虑。

2.4 选型对照表与实际建议

结合我的实操经验，选型可以用一句话概括：如果你在Spring Boot生态里，无脑Spring AI；如果你有一堆Java 8的遗留服务要加AI能力，LangChain4j；如果你需要Java进程内跑模型推理，DJL。项目里混用Spring AI和DJL也不冲突，比如用DJL做Embedding，用Spring AI做对话编排，各取所长，这是我在生产环境验证过的组合。

3. 落地最后一公里的六个关键节点：真正的坑都在这

很多团队在Demo阶段一切正常，一上生产就处处冒烟，问题几乎都集中在下面六个节点。每个环节单独看都不难，但串起来就是一道完整的工程题。

3.1 流式输出：别把SSE当成普通HTTP响应

大模型应用里，逐字输出（流式）是用户体验的底线。但它在Java侧有个经典陷阱：很多人用HttpClient同步等待整个响应体返回，结果首字延迟看起来还行，实际是一个长连接挂着，用户看到的是"转圈圈半天，然后一次性刷出全文"。流式的意义在于边生成边推送，Java端必须把响应流实时转发给浏览器端。

Spring AI对流式的封装是返回Flux<String>，底层走WebFlux的响应式流。如果你用的是Spring MVC，可以考虑用SseEmitter或者Controller返回text/event-stream来处理。实现思路是：后端从模型接口拿到流式Chunk，立刻通过SSE推给前端，同时做好心跳保活，因为有些模型服务在长连接上会有默认空闲超时，一旦超过几秒没内容，连接会被网关掐断。另外还要给流式接口单独设置读超时，不要用全局统一的HTTP超时配置，否则长回答大概率中途抛Read timed out。

3.2 函数调用：让模型"看见"方法，而不是让它瞎编

函数调用（Function Calling/Tool Use）是把大模型接入业务系统的灵魂。没有它，模型只能纸上谈兵，有了它，模型才能"动手做事"：查库存、下单、调内部接口、写数据库。

Spring AI 1.0的做法是定义普通Java方法，标上@Tool注解，然后在ChatClient上注册。框架会自动生成方法的JSON Schema并随请求发给模型，模型根据用户意图决定调哪个工具、填什么参数，框架再把结果回传给模型继续推理。这里最容易被忽略的是超时和幂等：模型决定调用工具后，如果工具本身是个慢接口，整个对话回合就会被拖住；如果工具操作状态变更（比如扣库存），模型的重复调用可能造成重复执行。我的做法是给所有工具方法加统一的超时兜底，并对写操作做幂等设计，宁可工具返回"操作失败，请重试"，也不能让模型在实际已经成功的情况下再执行一次。

另一个细节是工具数量别贪多，一次请求塞几十个工具的JSON Schema，既浪费Token，又容易让模型选择困难。控制在五六个以内，只暴露当前场景真正需要的。

3.3 结构化输出：从JSON泥潭里捞数据

大模型的默认输出是自然语言，但业务系统要的是POJO。很多团队第一版代码是用正则从模型回答里"抠"JSON，遇到模型回一句"好的，以下是你要的结果：```json..."就直接崩溃。原生框架普遍支持结构化输出，Spring AI提供了BeanOutputConverter，你传入目标类型，框架自动生成JSON Schema约束模型输出，并将响应反序列化成对象。

实战中有两个坑。第一是泛型嵌套类型要显式构造ParameterizedTypeReference，否则反序列化时会报类型转换异常；第二是严格模式下偶尔还会收到模型拒绝回答或绕圈子的文本，所以反序列化仍然要包一层异常处理，返回一个业务上可理解的提示，而不是直接把解析异常抛给用户。结构化输出不是万能药，但能把99%的脏活干掉。

3.4 上下文与记忆管理：Token窗口是预算不是内存

模型的上下文窗口是有限的，你不能无限往Prompt里塞历史消息。原生框架一般是靠ChatMemory管理多轮对话，比如Spring AI的MessageWindowChatMemory，它按窗口大小只保留最近N条消息，超出就丢弃。

但"丢消息"对真实业务是致命的：用户在第3轮提了一个需求，第10轮问"我刚才说的那个，你记不记得"，如果中间消息被截掉了，模型就会失忆。更稳的方案是摘要压缩：当消息超过窗口时，先前面的消息浓缩成一段摘要，再和最近消息拼接。相当于给模型配了一个"记忆压缩"功能，长期对话场景下体验好很多。同理，RAG的检索片段也要做Token预算，别一个很长的文档全塞进去，先检索再裁剪，哪个片段相关度高就留哪个。

3.5 容错、超时与限流：别让模型拖垮你的线程池

大模型服务有几个特性反直觉：延迟高、不稳定、还可能返回错误响应。生产接入时最基础的兜底有三层：

• 超时设置：连接超时、读取超时分开配，读取超时是重灾区。我自己习惯设为模型P99延迟的两倍左右，再通过重试策略兜底。
• 重试与熔断：对网络抖动和5xx做有限次重试，但重试有代价——模型接口连续失败时，重试只会加剧雪崩。所以必须配合熔断，连续失败达到阈值就快速失败，走降级文案。
• 线程池隔离与限流：调用模型接口的线程池和业务线程池必须隔离，否则模型慢响应会把核心业务的线程池占满。信号量限流也很有用，防止瞬时大流量把上游模型服务打爆，而限流策略要基于Token成本和业务优先级，不能简单粗暴一刀切。

这层设计最反直觉的地方在于：大模型接口的故障不是0和1，而是"慢"和"乱"。有时候服务没挂，但响应慢到用户无法接受。所以监控指标里一定要有"首Token延迟"和"总耗时"，而不是只看成功率和错误码。

3.6 可观测性与成本：Token用量要被"看见"

模型接口的每一次调用都在花钱，很多团队直到月底账单出来才发现成本失控。Spring AI这类框架自带Token计数的概念，ChatResponse里包含TokenUsage，可以读到本次请求的输入/输出Token数。我的做法是把它作为Tag打进Micrometer指标里，和业务维度（用户、场景、模型版本）一起记录；再定期分析Token消耗Top用户和Top场景，该做缓存的做缓存，该降级的降级。

另外，日志里不要打全量Prompt和响应，尤其是包含个人信息或业务敏感信息的对话。生产环境建议只记录脱敏后的摘要和Token统计数据，"最后一公里"不仅是功能上线，更是安全合规守得住。

4. 实操：从零搭一个Java原生LLM问答服务（Spring AI + 本地模型网关）

理论讲再多，不如亲手搭一遍。下面这套流程我按生产可复用的标准整理过，本地环境跟着做就行，整个过程大概半小时。

我做这个项目的目标是：一个Spring Boot 3应用，既完成多轮对话与流式输出，又具备工具调用和结构化抽取能力，且所有模型调用都走本地的OpenAI兼容网关，不依赖公网厂商。这样部署到内网后完全自包含，也是很多企业落地时的标准形态。

4.1 环境和依赖准备

先准备基础环境：JDK 17+、Maven 3.8+、Spring Boot 3.3+。模型这一侧，我用的是Ollama网关，它暴露的/v1兼容OpenAI协议，拉一个qwen2.5:7b就可以跑。如果你的机器有显卡（哪怕是消费级的，比如RX 6750 GRE，跑7B模型推理也够用；训练和微调则另说要更大显存），推理速度会快很多；没显卡CPU也能跑，就是慢一点。

pom.xml里需要引入Spring AI的BOM和OpenAI模块：

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-ollama</artifactId> </dependency> </dependencies>

前面说过，Ollama暴露了OpenAI兼容接口，所以真正生效的是spring-ai-openai模块，spring-ai-ollama作为备用方案，防止后端换成其他推理服务时还要改代码。

4.2 配置文件：把模型网关指对

在application.yml里配置：

spring: ai: openai: base-url: http://localhost:11434/v1 api-key: ollama # 本地网关不校验，但接口要求非空 chat: options: model: qwen2.5:7b temperature: 0.7 max-tokens: 2048 completions: stream-options: include-usage: true

这里base-url指向本地Ollama网关的OpenAI兼容路径，api-key随意填一个占位值即可，因为本地不校验。如果是接云端厂商或内网vLLM服务，把base-url换成对应地址、api-key换成真实密钥就行，业务代码完全不用动，这层抽象就是原生框架的价值所在。

4.3 写一个最小可用的对话接口

Spring AI 1.0里，最核心的入口是ChatClient。定义一个配置类，创建一个带记忆能力的ChatClient：

@Configuration public class ChatConfig { @Bean ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultSystem("你是一个严谨的Java开发助手，回答要简洁、准确，代码示例要完整。") .defaultAdvisors(MessageWindowChatMemory.builder() .maxMessages(20) .build()) .build(); } }

然后写Controller：

@RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient = chatClient; } @PostMapping("/chat") public ChatResponse chat(@RequestBody ChatRequest req) { String answer = chatClient.prompt() .user(req.message()) .call() .content(); return new ChatResponse(answer); } }

到这里，一个能记住上下文的对话接口已经通了。注意MessageWindowChatMemory配的是最近20条消息，这套记忆是服务端持有的，生产环境建议按用户维度隔离并设置过期清理策略，防止内存里攒一堆没人要的会话。

4.4 接入流式输出，体验从"转圈"变成"打字机"

把接口改成流式，核心是把结果类型从String换成Flux<String>：

@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chatStream(@RequestBody ChatRequest req) { return chatClient.prompt() .user(req.message()) .stream() .content(); }

前端用EventSource或fetch的流式读取就能消费。这里有个生产细节：要给整个流式请求设置合适的响应缓冲区，有些网关默认会缓冲响应，导致前端还是等到全部生成完才收到数据。把响应缓冲关掉，或者用WebFlux天然支持的流式返回，才能真正做到逐字推送。

4.5 把Java方法注册成模型可调用的工具

工具调用是让模型"动手"的关键。在Spring AI里，定义普通Bean方法并标注@Tool：

@Component public class OrderTool { @Tool("根据订单号查询订单状态，返回订单状态和金额") public String queryOrderStatus(String orderId) { // 这里调用真实的订单服务 if ("A1001".equals(orderId)) { return "订单状态：已发货，金额：328.00元"; } return "未找到订单"; } }

注册到ChatClient：

@Bean ChatClient chatClient(ChatClient.Builder builder, OrderTool orderTool) { return builder .defaultAdvisors(MessageWindowChatMemory.builder().maxMessages(10).build()) .defaultTools(orderTool) .build(); }

之后用户问"订单A1001到哪一步了"，模型会自主决定调用queryOrderStatus，把返回值组织成自然语言回答。需要注意，工具方法的参数描述要清晰，参数个数别太多，否则模型填参的准确率会下降；方法内要捕获所有异常并以文本方式返回，这样模型才能理解"出错"并决定下一步。

4.6 结构化输出：从"答非所问"到"稳定返回POJO"

比如我们需要从用户对话里抽取订单要素，定义一个POJO：

public record OrderInfo( @JsonProperty(required = true) String orderId, @JsonProperty(required = true) BigDecimal amount, String address ) {}

用BeanOutputConverter结合ChatClient：

var converter = new BeanOutputConverter<>(OrderInfo.class); OrderInfo info = chatClient.prompt() .user(u -> u.text("从用户的描述中抽取订单信息。\n{input}").param("input", req.message())) .options(converter.getCompatibleJsonSchemaOptions()) .call() .entity(converter);

关键在于.options(converter.getCompatibleJsonSchemaOptions())，框架会把目标类型转成JSON Schema强约束模型输出格式。如果模型返回内容无法解析，entity()会抛异常，这里要捕获并给出兜底文案或引导用户重新描述。

4.7 加一个最小RAG链路：让模型回答"私有知识"

RAG是老生常谈，但工程实现上有几个容易踩的细节。以"给模型接一份内部产品文档"为例，步骤大致是：

1. 切分文档：按段落或固定长度切块，块与块之间加适量重叠（比如200字文本留20字重叠），避免语义被切断。
2. 向量化存储：用本地Embedding模型把切块转成向量，写入向量库。我用的PGVector，Spring AI有现成集成，依赖spring-ai-pgvector-store即可，不需要额外引入重型中间件。
3. 检索召回：每次提问先向量检索最相关的几个块，加上原文片段和引用来源，一起拼进Prompt发给模型。
4. 回答与溯源：模型生成回答时要约束"只能基于给定文档回答"，文档没有的内容直说不知道，避免模型自由发挥编造。

Spring AI的RAG可以简化成几行Advisor配置，但分块质量和检索阈值才是真正的效果分水岭。我在实践中反复调过：块大小在300到500字之间回答最稳，检索TopK在3到5之间比较均衡，相关性阈值设太低会把无关内容塞进Prompt，浪费Token又干扰模型判断。

5. 常见问题与排查实录：把这些坑都提前踩平

最后整理一份实战中高频出现的问题速查表，基本覆盖了Java团队接大模型时的"翻车高发区"。

再补两个不算常见但一旦遇到就非常头疼的细节：

模型返回空响应但状态码200。这种情况常见于网关层把一些异常封装成了正常返回。排查思路是不要只盯状态码，要把响应体里的finishReason和content字段一起打日志。finishReason为length表示是被max-tokens截断，这时要么调大Token上限，要么引导模型缩短回答，而不是去重试。

工具调用进入死循环。模型会调用工具、拿到结果、再继续推理，但如果工具返回内容让它觉得"任务还没完成"，可能反复调用同一个函数。在工程上要对单次对话的工具调用轮次做上限（比如不超过5轮），超出直接中断并返回"任务复杂，需要人工介入"的提示。这个保护在生产里非常重要，没有它，一次不合理的用户输入就能消耗成百上千Token。

还有一个容易被忽视的点：本地模型网关和业务服务最好走内网专有通道。我在实操里习惯让业务服务和推理服务部署在同一内网，通过内部域名访问，避免把推理服务暴露到公网上。模型本身不具备鉴权能力，一旦裸奔到公网，任何人都能白嫖算力，甚至可能被恶意灌入大量请求。生产环境一定要加网关鉴权，至少在模型服务前面挡一层。

写在最后

我个人的体会是，Java生态做LLM落地，从来不缺"能跑的代码"，缺的是"敢上生产的架构"。原生框架的价值不在于帮你省掉几行HTTP调用，而在于它把大模型这个异质组件，驯化成了Java团队熟悉的东西：有配置、有监控、有类型约束、有容错语义。真正跑过一个完整项目之后你会发现，大部分时间不是在写AI逻辑，而是在处理工程问题——超时、限流、状态、成本、安全，这些才是"最后一公里"的真实路况。

把这个项目做完之后，我还想再往里补两块内容：一是把RAG的文档切分和检索策略做成可视化调试工具，二是给工具调用链路加上完整的追踪日志。这两块做扎实了，Java侧大模型应用的成熟度还能再上一个台阶。如果你也在做类似的落地，欢迎把踩坑经历丢过来交流，大家互相省点时间。