企业官网建设流程全解析

1. 为什么Java开发者需要一个像样的LLM编排层

1.1 Python工具链在Java世界里有多拧巴

我见过太多Java后端同学，看完Python那边的LangChain教程之后，动手写Java时第一反应都是：“这玩意儿到底有没有Java版？”

有，当然有，就是标题里写的那位——LangChain4j。但在聊它之前，我想先把问题说清楚：为什么Java开发者做LLM应用，一直这么别扭？

你先想想我们平时做个带大模型的功能，最原始的姿势是什么：拿HTTP工具POST一个请求到模型服务的接口，把Prompt塞进JSON的某个字段里，然后接收返回的JSON字符串，再自己写解析逻辑剥出来。听起来不难，但只要功能稍微复杂一点，你马上会遇到这几件事：

• 多轮对话要把历史消息一遍遍拼进请求体，谁来替你维护？
• 模型返回的格式经常带点Markdown标记或者额外描述，谁来帮你统一解析成Java对象？
• 要接企业内部的文档做知识库问答，文本切块、向量化、语义检索，这些重复劳动做不做？
• 想让模型调用你现有的业务方法（查库存、下单、查天气），要处理函数定义序列化、参数提取、结果回传，这串逻辑每个接口写一遍？

这些问题单独看都能硬写，写一个月也能跑，但项目一多你就发现：整个团队都在重复造轮子，而且每个轮子形状还不一样。

1.2 LangChain4j到底解决的是哪几件事

LangChain4j本质上是把“跟大模型打交道”这整条链路的样板代码收走。如果拿Spring生态来类比，它更像一个针对LLM调用链路的“Spring Data”：模型是数据源，消息是实体，工具调用是Repository方法，你只管定义业务接口，剩下的序列化、会话、解析、检索他们都替你兜底。

具体来说，它替你扛了这几件事：

• 统一模型抽象。不管是接在线模型API，还是本地跑的开源模型，在你代码里都是同一个ChatModel对象，换个实现类就行，业务层基本不动。
• 消息与记忆管理。把多轮对话的历史消息建模成Message对象，用ChatMemory统一存取，不用你手动拼JSON数组。
• 输出结构化。你定义好Java的record或者POJO，它负责让模型按这个结构返回，再帮你解析成对象。思路跟写MyBatis的ResultMap有点像，只是这里不用写XML。
• RAG组件。文本切块、Embedding、向量存储、相似度检索都有现成接口，生产环境可以替换成各种向量数据库实现。
• 工具调用（Tool/Function Calling）。你用注解标记一个普通Java方法，模型基于对话内容决定要不要调用它，框架自动处理调用的参数填充和结果回传。

我自己的体会是，学习LangChain4j真正值钱的部分不是那几个类怎么用，而是它帮你把“一个大模型应用到底由哪些环节组成”这件事逼着你想清楚。每个组件都有清晰的边界，这也是我为什么推荐Java团队直接拿它做内部脚手架。

1.3 从依赖坐标认识项目结构

先把依赖拉进来，感受一下它的模块划分。核心包是langchain4j，里面是模型接口、消息模型、记忆、输出解析、工具调用这些基础抽象。不同模型提供方是独立模块，比如langchain4j-open-ai不仅能连主流在线模型服务，也兼容很多使用同样API协议的网关和本地服务；langchain4j-ollama是本地模型专用模块。这种拆分方式跟Spring Boot Starter的哲学一致：用到哪个模型，就引哪个依赖。

一个常见的Maven依赖长这样：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>1.0.0</version> </dependency>

注意两个version必须保持一致，否则运行期很大概率冒出NoSuchMethodError。这个坑我在第7章会展开讲。拉到依赖之后，新建一个类写main方法就能跑，不用急着接Spring Boot，先把链路跑通比什么都重要。

2. 环境准备：第一处容易翻车的地方

2.1 版本匹配是头等大事

去年有个朋友在群里发了一段异常日志，问为什么调model.generate()直接NoSuchMethodError。我看了下他pom.xml：langchain4j用的一个版本，langchain4j-open-ai用的另一个版本，两个模块的接口签名对不上，编译能过，运行期一调用就翻车。

所以环境准备的第一步，我建议你先确定JDK和Spring Boot的基线。当前主流版本要求JDK 17及以上，Spring Boot 3.x项目可以直接集成。然后打开Maven中央仓库，查一下langchain4j的最新稳定版，让所有dev.langchain4j开头依赖都用同一个版本。不要图省事让版本号飘在后面，这种问题排查起来非常浪费时间。

还有个版本相关的细节：网上很多教程还在用ChatLanguageModel这个类名，你在1.x版本的框架里看到它时不要慌，那是旧命名，新版本统一叫ChatModel。功能是一样的，就是换个马甲。做教程代码复刻的时候，优先看官方文档里的最新写法，别拿半年前的文章硬套新版API。

2.2 配置API密钥的三条路线

模型服务的API Key这类敏感信息，最忌讳写死在代码里。我见过直接把Key塞进application.yml然后整个仓库推上Git的惨案，第二天Key就被别人刷爆了。说说我常用的三种方式：

第一种，环境变量。在启动脚本或者IDE的Environment variables里配好，代码里用System.getenv("LLM_API_KEY")读取。优点是与部署环境解耦，适合本地开发快速切换。

第二种，Spring Boot的application.yml配合${}占位符。例如：

langchain4j: open-ai: base-url: ${LLM_BASE_URL:https://api.example.com} api-key: ${LLM_API_KEY:} chat-model: model-name: ${LLM_MODEL_NAME:gpt-4o-mini} temperature: 0.7

这样配置的好处是，团队里每个人只需要配自己的环境变量，配置文件模板可以正常提交。这里我故意用了https://api.example.com这种泛指的地址，因为不同模型服务的接入地址差异很大，你按自己实际买的服务填就行。

第三种，如果你只是快速写个Demo验证，直接在构造器里临时塞进去也可以，但是记住一条红线：代码能跑通之后，立刻改成环境变量方式，别留着技术债过年。

2.3 最小验证：把入门案例拆到只剩骨头

配完依赖和Key之后，别急着上Spring Boot，先写一个最小验证类，确认整条链路是通的。这个最小Demo我建议不要超过20行，越简单越容易定位问题：

import dev.langchain4j.model.chat.ChatModel; import dev.langchain4j.model.openai.OpenAiChatModel; public class QuickStart { public static void main(String[] args) { ChatModel model = OpenAiChatModel.builder() .apiKey(System.getenv("LLM_API_KEY")) .baseUrl(System.getenv("LLM_BASE_URL")) .modelName(System.getenv("LLM_MODEL_NAME")) .build(); String answer = model.generate("用一句话介绍你自己，不超过30个字"); System.out.println(answer); } }

跑一下，控制台能正常打印出模型回复，说明你的网络、密钥、模型名都是对的。如果这里就报错，先别怀疑框架，排查顺序应该是：网络到模型服务通不通、API Key是否有效、modelName是不是你购买的服务正好支持的那个标识。很多新手在这步卡住，十有八九是模型名填错了，或者base-url多了一个斜杠少了一个路径段。

3. 手写第一个带记忆的对话：理解核心抽象

3.1 ChatModel：一切能力的入口

老版本教程里你可能看到ChatLanguageModel，新版本叫ChatModel，无论如何，它是你发送对话请求的主入口。它干的事情很简单：接收用户消息，返回模型生成结果。但简单背后有一个关键认知必须建立——模型本身是没有记忆的。

你可以把大模型想象成一个极其聪明但患有严重“短期失忆”的同事。你每次把问题甩给它，它根本不记得上次你们聊了什么。所谓“多轮对话的记忆”，其实是一个笨功夫：把历史对话记录整理好，每次请求时把整段历史一起发给模型。就像你跟这位同事开会之前，先打印一份聊天纪要放到他桌上。

所以ChatModel.generate()这个方法的参数设计就很直白：它接收的是String或者Message列表。当你传String的时候，底层会包装成一条用户消息；当你传List<Message>的时候，就是在告诉它：这是我们要讨论的完整上下文。

3.2 消息历史与ChatMemory：记忆的第一种实现

知道模型无记忆之后，你就明白为什么需要ChatMemory了。它是专门用来存对话历史的组件，最常见的是MessageWindowChatMemory——一个滑动窗口，只保留最近N条消息。窗口设得越小，越省Token，但模型“忘得越快”；窗口设得大，上下文丰富，但单次请求体积大、费用高。对于一般客服助手，10到20条是比较合理的区间。

在LangChain4j里，把记忆挂到业务接口上非常顺滑。先定义一个你的业务接口，然后通过AiServices生成代理实现：

import dev.langchain4j.memory.ChatMemory; import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.service.AiServices; interface ChatAssistant { String chat(String message); } ChatModel model = OpenAiChatModel.builder() .apiKey(System.getenv("LLM_API_KEY")) .baseUrl(System.getenv("LLM_BASE_URL")) .modelName(System.getenv("LLM_MODEL_NAME")) .build(); ChatMemory memory = MessageWindowChatMemory.withMaxMessages(20); ChatAssistant assistant = AiServices.builder(ChatAssistant.class) .chatModel(model) .chatMemory(memory) .build(); // 连续调用，模型能记住前文 System.out.println(assistant.chat("我叫小明，请记住这个名字")); System.out.println(assistant.chat("我叫什么名字？"));

第二次输出能正确回答“小明”，说明记忆生效了。在使用AiServices之后，你写的接口方法就变成了业务入口，框架自动做消息拼装、记忆存取、结果返回，你把心智放在接口定义上就行。

这里我说一个新手容易误解的点：MessageWindowChatMemory不是数据库，它是进程内内存对象。应用一重启，记忆就清空了；多实例部署时，各个实例之间的记忆也不共享。真实项目里要做持久化或分布式会话存储，需要自己实现ChatMemory接口，或者把用户会话ID和内存实例做映射管理。Demo阶段没问题，上生产前一定要想清楚。

3.3 模型参数与“温度”的直觉理解

配置ChatModel时，你一定会碰到temperature这个参数。官方解释是“控制随机性”，但初学者听着还是云里雾里。我习惯这么类比：温度越高，模型越“敢说”，思维跳跃、用词花哨；温度越低，模型越“老实”，紧着最稳妥的答案说。取值为0时，同样的输入大概率给出同样的输出；取到1以上，每次回答可能都不一样。

参数的选用取决于任务类型。做信息抽取、分类、翻译这些只要是标准化的活，温度直接设0，追求稳定可复现；做文案创作、头脑风暴这种创意类的，温度可以调到0.7到0.9。这个经验在实战里非常重要，很多人发现测试时结果飘忽不定，怀疑模型不行，其实是温度没调对。

除此之外，还有maxTokens或maxOutputTokens之类的参数限制回复长度。别设太短，否则回答容易在中间被截断；也别设太长，白花钱。一个稳妥做法是：先按你的平均业务回复长度估算，再加30%到50%的余量。

4. 结构化输出：别让模型返回的JSON把你逼疯

4.1 为什么说别急着解析JSON字符串

很多Java开发者拿到模型返回的第一反应是：String result = model.generate("......");，然后找Jackson把result反序列化成对象。如果是纯练习倒无所谓，但到业务场景你会非常痛苦——因为大模型返回的字符串非常“随性”。

它可能老老实实返回一个干净的JSON，也可能好心给你加一句“好的，这是你要的信息：{...}”，还可能把JSON包在Markdown的代码块里。更难受的是，字段缺失或者返回了额外字段，你的解析代码得写一堆容错。这不是模型“笨”，是它天生以自然语言的方式思考，JSON只是它模仿出来的格式，而不是它的母语。

解决思路不是去压模型让它“闭嘴”，而是换一种交互方式：你把希望的输出结构通过类型定义告诉框架，框架负责在背后做结构化约束。在LangChain4j里，这个能力非常自然——接口方法的返回类型直接定义输出结构。

4.2 模型约束与数据类定义实战

假设我要做一个从长篇文本里自动提取图书信息的功能，输出需要包含书名、作者、页数、摘要。可以先定义一个record：

import dev.langchain4j.service.UserMessage; import dev.langchain4j.service.V; record BookInfo( String title, String author, Integer pages, String summary ) {}

然后定义带@UserMessage的接口方法。@V("text")表示把方法入参注入到Prompt模板的变量里：

interface BookExtractor { @UserMessage("从以下文本中提取图书信息：{{text}}") BookInfo extract(@V("text") String text); }

构建时同样走AiServices的流程：

BookExtractor extractor = AiServices.builder(BookExtractor.class) .chatModel(model) .build(); String article = "《三体》是刘慈欣创作的长篇科幻小说，全书约300页，讲述了地球文明与三体文明的信息交流、生死搏杀及两个文明在宇宙中的兴衰历程。"; BookInfo info = extractor.extract(article); System.out.println(info.title());

跑起来之后你会发现，框架已经在底层把“必须返回一个包含title、author、pages、summary四个字段的JSON对象”这个约束传达给模型了，并且模型返回的内容会被自动解析成BookInfo。本质上是“类型即契约”，类型定义越清楚，模型返回越规矩。

这个能力落地到业务里非常有用。比方说我维护的内部工单系统，用户提交的文本五花八门，靠人工拆字段累死人。用这套方法定义好“客户、产品、问题类型、紧急程度”这个结构，丢给模型抽一遍再进流程，准确率相当可以。

4.3 不同模型的结构化输出差异

在线模型的指令遵循能力通常比较强，你定义好record之后，它们返回的JSON基本是规范的，很少带多余前缀。但本地跑的开源小尺寸模型就不一定了，7B级别左右的模型有时会在JSON外面包一圈解释性文字，或者字段名跟你的record对不上。

遇到这种情况，我的处理经验是从三处下功夫：第一，@UserMessage的提示语写得更明确，把“只输出JSON，不要任何解释”写死；第二，temperature设到0，减少自由发挥；第三，将record字段命名得跟模型常用语义一致，别用拼音缩写。做完这三步，大部分本地模型也能稳定输出。

如果做完还是偶尔失败，最后的兜底方案是捕捉解析异常，提示用户重新生成一次。别小看“重试”这个方案，在处理非确定系统时它是性价比极高的容错手段。

5. 企业应用绕不开的RAG：简易落地路径

5.1 没有RAG的LLM应用在企业会卡在哪里

使用预训练模型做企业问答，一个尴尬的现状是：模型的知识截止到训练数据，你问它你们公司内部的审批流程、产品规格参数，它要么一本正经编一个，要么说不知道。企业内部知识库属于私有数据，不可能出现在公开训练集里。

RAG（检索增强生成）就是把这个缺口补上的标准姿势：先到知识库里检索出跟问题最相关的片段，再把问题连同片段一起丢给模型生成答案。模型不需要“记住”你的文档，它只需要“阅读”你即时提供的那几段材料，就能给出有依据的回答。你用的时候可以理解为“开卷考试”：模型拿着你给的资料作答，而不是凭空瞎写。

对于Java团队做RAG，我强烈建议第一版不要过度设计。别一上来就上分布式向量库、异步管道、权限过滤，先用LangChain4j提供的嵌入模型和内存向量存储，把链路跑通，再考虑生产化替换。

5.2 三段式流程的落地拆解

RAG的完整流程就三步：把文档切成小块，每块转成向量存起来；用户提问时，把问题也转成向量，在库里找最相似的一批文本块；把问题和文本块一起送给ChatModel生成回答。

第一步先引入langchain4j-embeddings（或者用你在线模型服务配套的embedding模块），创建EmbeddingModel。向量化和对话是两个不同的模型接口，这一点要注意，很多在线模型服务是分别提供chat模型和embedding模型的，配置时别混用。

import dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.openai.OpenAiEmbeddingModel; import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder() .apiKey(System.getenv("LLM_API_KEY")) .baseUrl(System.getenv("LLM_BASE_URL")) .build(); EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); String chunk1 = "报销流程：员工填写报销单，部门主管审批，财务复核后打款。"; TextSegment segment1 = TextSegment.from(chunk1); Embedding embedding1 = embeddingModel.embed(segment1).content(); store.add(embedding1, segment1);

检索时，使用EmbeddingStoreRetriever：

import dev.langchain4j.rag.Retriever; import dev.langchain4j.rag.content.retriever.EmbeddingStoreRetriever; Retriever retriever = EmbeddingStoreRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(3) .build();

每天上线新文档时，你写一个定时任务，把文档读取、切块、向量化、入库这套逻辑跑一遍。等真正问答时，把用户问题交给AiServices，框架内部会把检索结果自动注入Prompt上下文。

5.3 能跑和能用的差距：召回质量与切块策略

链路跑通不代表效果能用，这里面差距最大的环节，一个是切块策略，一个是召回数量。

很多人在第一步就随意定一个“每500字一块”就开干，带来的问题是：一个完整的知识点被切到两个块里，检索时只召回了一半，模型给出的答案自然残缺。我建议优先按标题和段落边界切，一段为一个基本单位，太长的段再按句子边界切。切块大小通常控制在两三百到五百个Token之间，同时让相邻块之间保留一点重叠，防止边界切断语义。如果你的文档是Markdown或者HTML，保留结构信息一起存入，检索效果会更好。

maxResults这个参数同样关键。设置太少，答案信息量不够；设置太多，无关上下文混入，模型容易被带偏。我实践下来，绝大多数场景3到5个结果比较平衡。另外，别只按向量相似度排完就结束，很多企业内部文档带有更新时间、作者、部门等属性，可以在检索阶段顺带做一次过滤，只返回有效范围内的内容，这个在RAG架构里叫过滤检索，LangChain4j有专门接口支持。

InMemoryEmbeddingStore作为内存实现，数据量大了之后查询慢且重启即失，生产环境要换成独立的向量数据库，比如各种支持向量检索的数据库。好在接口是统一的，替换实现类即可，业务代码不怎么动。

6. 工具调用：让模型主动请求“执行”

6.1 Function Calling在Java侧的注册方式

初次接触Function Calling（函数调用）的人，常会把它理解成“模型直接执行代码”，这是个误解。实际流程是：模型在生成回复时，决定“我需要调用某个工具”，然后返回一个格式化指令；框架收到指令后，在你这边的Java代码里调用对应方法；调用结果再作为上下文回传给模型，模型据此生成最终回复。整个调用过程中，模型始终没有真的“动手”，它只是在决策和编排。

LangChain4j的做法极其简单——你在一个普通类里定义方法，打上@Tool注解，然后把实例传给AiServices：

import dev.langchain4j.tool.Tool; import dev.langchain4j.tool.P; class WeatherTools { @Tool("查询指定城市的当前天气") String getWeather(@P("city") String city) { return "city=" + city + ", weather=晴, temperature=25"; } } interface CustomerAssistant { String chat(String message); } CustomerAssistant assistant = AiServices.builder(CustomerAssistant.class) .chatModel(model) .tools(new WeatherTools()) .build(); System.out.println(assistant.chat("北京今天适合出门吗？"));

模型看到你说北京，就会触发工具方法的调用，框架把city这个参数用“北京”填充，执行完方法后，把返回结果带回模型做下一步生成。上面的对话最终输出会类似“北京今天天气晴，气温25摄氏度，适合出门”。

6.2 参数解析与真实业务调用的衔接

工具方法不一定放的是模拟数据，真实场景里它可以直接调用你现有的Service层、FeignClient、Mapper方法。这正是LangChain4j在企业落地中最有价值的地方：模型因此从“只能聊天”变成了“能调用业务系统”。

写工具方法时有几个细节值得注意。首先是方法签名，参数名和描述越清晰越好，因为模型是根据方法名、参数名、@P描述来生成调用参数的，描述含糊会让模型填错参。其次是返回值，建议返回字符串或者能被JSON序列化的对象，不要返回一些奇怪的数据结构，模型的上下文通道只认文本。第三个坑是超时，模型等待工具返回时是有耐心的，如果你的业务方法内部调用了外部接口且耗时很长，一定要做好超时和降级，否则整个对话会挂着。

还有一点要提醒：工具方法的权限和校验不能省。你在DEMO里让模型调一个查天气的接口无所谓，但如果哪天让模型调用“作废订单”这类危险操作，一定要在方法内部加上权限判断、二次确认、操作日志。大模型的Prompt注入攻击在工具场景下是真实存在的风险，测试时多试着在对话里诱导它“调用你没说要调的方法”。

7. 新手最容易踩到的坑位清单

7.1 版本不一致导致的运行期异常

我在第2章提过版本问题，这里再深化一下。LangChain4j的模块拆得很细，除了核心包，模型厂商对应一个包，工具和RAG又有各自的扩展包。新手常常今天引用一个教程里的版本号，明天引用另一个教程里的版本号，两个包版本不一致，编译期偶尔能过，但只要碰到接口签名变化就直接NoSuchMethodError或者ClassNotFoundException。

解决思路只有一个：所有dev.langchain4j开头的依赖，版本号必须完全一致。你可以在Maven的<dependencyManagement>里统一声明版本，由BOM统一管理。我个人的习惯是直接去官方文档的“Getting Started”页面复制版本号，而不是临时问AI或者抄一段博客里的依赖，这样最省时间。

7.2 ChatMemory作用域与用户串线问题

用AiServices构建服务时，如果你把单个ChatMemory实例注册成一个单例Bean，那所有用户都会共享这一份聊天记录，出现在生产环境会是严重的事故。用户A问“我的订单号是什么”，用户B随后问“刚才那个订单付款了吗”，模型很可能把A的订单当成B的，想想都后背发凉。

正确做法是：要么每个用户会话都创建独立的ChatMemory，要么做一个按用户ID维度路由的ChatMemory实现。我这边的一个项目因为早期偷懒踩过这个坑，最后重构时专门写了一个基于用户ID的ThreadLocal仓库来隔离记忆。你不需要照抄我这个方案，但一定要从设计上意识到：记忆是有归属的，存储必须按会话或者用户做隔离。

7.3 流式输出：为什么界面一直“没反应”

很多业务场景希望模型像打字机一样逐字吐内容，这样用户体验好。LangChain4j提供了流式模型接口StreamingChatModel，跟ChatModel是两套API。新手最容易踩的坑是：用了流式接口，但代码里没有正确订阅/消费流事件，结果控制台半天不出字，误以为卡死了。

流式返回是响应式流（在Java里通常是Flux或者回调），必须先消费才有输出。如果你不熟悉响应式编程，先用最朴素的版本——把每个流式片段逐段打印出来，理解事件流转的顺序，再考虑封装到WebSocket或者SSE里推给前端。别一上来就把反应式栈引入业务代码，否则排查问题难度直接翻倍。

7.4 三个“先确认再怀疑”的排错口诀

遇到LangChain4j报错，我建议你按这个顺序排查，省掉大量瞎折腾的时间：

一、先确认网络与模型服务状态。检查HTTP请求有没有发出、返回状态码是多少。很多“框架问题”其实是模型服务的配额用完了或者服务限流，日志里会有明确提示，先看状态码。

二、再确认模型名是否被当前服务端点支持。模型名写错是概率极高的事件。不同厂商用不同的标识，哪怕同一个模型，在不同地区网关可能名字还不一样。把模型名打印出来核对一遍，别凭记忆写。

三、最后才怀疑你的Prompt和参数。如果请求发出去了，模型有响应，只是结果不是你想要的，那多半是Prompt写得不到位、温度太高、输出结构没有被明确约束。这些问题是逻辑层面的，调起来要慢一点，但方向完全不同于前面的排查。

我自己带团队的时候，要求新同事把这三条规则打印出来贴在显示器边上，遇到问题先走流程，而不是上来就改Prompt。事实也证明，超过七成的“框架问题”都倒在第一步。

最后说点个人习惯。我每次学一个新框架，都会强迫自己做一个“无业务含义的最小原型”——一个空的main方法，一个最简单的模型调用，跑通过之后再一点点往上叠。这个方法看起来傻，但它能清晰切开“环境问题”和“业务代码问题”的边界，在LangChain4j这种组件多、链路长的框架里尤其好用。如果你正在入门，我建议也试试看，花不了半小时，后面省下的排查时间可能以天计算。