SpringBoot+LangChain4j+Ollama：本地大模型智能客服落地实践

之前接了一个客服后台的改造需求，团队里最早的方案是直接调云端对话模型 API。结果一评审就卡住了：客服对话里全是用户账号、订单、售后记录，这种东西要出内网，产品同学第一个不同意。后来又试了几套方案，最后落在本地部署这条路上——用 Ollama 把开源大模型跑在内网服务器，通过 LangChain4j 接入已有的 SpringBoot 后台，一周时间就搭出了一个能用的智能客服原型。这篇文章把我整个落地过程、代码实现、还有踩过的坑都整理出来，给同样在 Java 技术栈里做本地大模型接入的同学做个参考。

这套方案适合谁？如果你的团队是 Java 后端为主、不想为了 AI 功能单独养一支 Python 服务，或者你有明确的私有化部署和合规要求，那 SpringBoot + LangChain4j + Ollama 是一个非常稳的起点。它不挑显卡，CPU 机器也能跑，模型能力有上限但足够应付客服问答这类场景。我会从方案选型讲到环境准备，再讲完整代码实现，最后把常见的坑和优化手段一并列出来。

1. 方案选型：为什么是这三件套

1.1 三个组件各自扮演什么角色

这个组合里有三个角色，各管一摊，缺一不可。

Ollama 是模型运行层。它做的事情和 Docker 很像——负责把大模型下载下来、在本地跑起来、对外提供 HTTP 接口。早期本地跑大模型是一件很折腾的事，要自己下载模型权重、编译推理框架、处理显存分配。Ollama 把这些全封装了，一条命令就能拉起一个模型服务。它底层封装的是 llama.cpp 那套推理引擎，支持 CPU 和 GPU 加速，还提供了兼容 OpenAI 风格的 HTTP API，应用层接入非常友好。

LangChain4j 是模型应用开发框架。它解决的问题是：大模型本身只懂"生成文字"，但一个真正的智能客服需要记忆上下文、查企业知识库、调用内部业务接口。这些能力如果全部自己从零写，工程量不小。LangChain4j 提供了现成的 ChatMemory、RAG、Tool Calling、流式输出组件，用 Java 的思维封装好了，写起来跟写普通 Spring 服务没什么区别。

SpringBoot 是老本行，负责业务聚合。用户请求先进 Controller，经过鉴权、参数校验，再交给 LangChain4j 组装好的 Assistant，最后把模型返回值渲染给前端。后面如果要接订单系统、会员系统、工单系统，还是在 SpringBoot 这一层做编排。

打个比方：Ollama 是厨房里的灶台和锅，负责把食材加工成熟菜；LangChain4j 是配菜师傅，负责按菜单把各种食材搭配好；SpringBoot 就是前厅的服务员，负责接待客人、端菜上桌。三个角色各司其职，谁也不抢谁的活。

1.2 对比其他方案的取舍

很多团队第一次接触这个大模型改造，第一反应是直接用 Python 写一个 FastAPI 服务，再接 LangChain。这个思路本身没问题，但对以 Java 为主的团队来说，等于要维护两套技术栈。Python 服务要单独部署、单独监控、单独招人维护，为了一个客服机器人引入这么大复杂度，不划算。

还有人会问，为什么不用 Spring AI？Spring AI 是 Spring 官方出的 AI 框架，思路跟 LangChain4j 很像。但它起步晚，工具链和文档成熟度不如 LangChain4j。LangChain4j 从 2023 年开始迭代，社区活跃，对 Ollama 的支持也一直是第一梯队，中文资料的积累也更多。我自己的体验是，LangChain4j 在遇到问题时查资料更好查，踩坑成本低一些。

也有人会觉得，既然 Ollama 已经提供了 OpenAI 兼容接口，那我直接用 HTTP 调用不就行了？确实能跑通。但一旦你要做多轮对话、知识库检索、工具调用，你就得自己管理上下文、自己做文本向量化、自己维护会话状态。这些轮子 LangChain4j 已经造好了，没必要重新发明一遍。

1.3 智能客服场景的需求拆解

智能客服看起来简单，拆开全是需求。我在动手之前，先把客服机器人需要的能力列了一遍：

• 多轮对话能力：用户说了"我要退货"，下一步问"退哪个订单"，机器人得记得住是在聊退货，而不是重新理解成新问题。这对应 LangChain4j 的 ChatMemory。
• 知识库问答：产品使用说明、退款政策、发货时效，这些内容要喂给模型，让它在回答时有依据。这对应 RAG 检索增强生成。
• 业务系统打通：用户问"我的订单到哪了"，机器人要能去订单系统查真实数据，而不是编一个物流信息。这对应 Tool Calling。
• 流式输出：客服对话场景下，用户等不了好几秒才看到整段回复，字一个一个蹦出来体验会好很多。

这四个能力全部落地之后，这个客服才真正能用。下面正文我就按这四个点逐个展开，每一步都给完整可跑的代码。

2. 环境准备与模型部署

2.1 Ollama 本地部署与模型选型

先装 Ollama。Linux 环境下官方提供了一键安装脚本，Windows 和 macOS 直接下载安装包，安装完就是一个后台服务。我这边用的是 Linux 服务器，装好之后先确认服务有没有起来，执行ollama list，如果输出空列表说明服务正常。

然后拉模型。客服场景是中文为主，我选了 7B 参数级别的中文开源模型 qwen2.5:7b，它在中文理解、指令遵循和对话连贯性上表现均衡，参数量不大，CPU 也能跑，只是速度慢一点。有显卡的话体验会好很多，7B 模型大概需要 8GB 以上显存，推荐 16GB。如果你的机器只有 CPU，也能跑，就是一句话可能要等十几秒。

# 拉取对话模型 ollama pull qwen2.5:7b # 拉取向量化模型，RAG 知识库要用 ollama pull nomic-embed-text # 查看本地已有模型 ollama list

模型跑起来之后，先用 curl 快速验证一下服务是否可用，避免后面排查问题时分不清是模型问题还是代码问题：

curl http://localhost:11434/api/chat \ -H "Content-Type: application/json" \ -d '{"model":"qwen2.5:7b","messages":[{"role":"user","content":"你好"}]}'

能正常返回一段文字，说明模型服务没问题。注意 Ollama 默认只监听本机 127.0.0.1，如果 SpringBoot 服务在另一台机器或 Docker 容器里，需要设置环境变量OLLAMA_HOST=0.0.0.0再启动服务，或者直接用宿主机 IP 访问，这个细节后面排查部分会细说。

2.2 SpringBoot 工程初始化与依赖装配

SpringBoot 这边我用的 Java 17 + SpringBoot 3.x。项目可以直接用 Spring Initializr 创建，只需要引入 Web 依赖。LangChain4j 目前的最新稳定版本是 1.x，和 SpringBoot 3.x 配合没有问题。

pom.xml 里需要加入这几个依赖：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>1.0.1</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-ollama</artifactId> <version>1.0.1</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-embeddings-all-minilm-lm-v2</artifactId> <version>1.0.1</version> </dependency>

第三个依赖是本地向量化模型库，用于 RAG 场景，如果你已经用 Ollama 的 embedding 模型，也可以不引入，直接用 Ollama 做向量化。我后面示例代码里用的是 Ollama 的 nomic-embed-text。

依赖装好后，在 application.yml 里加基础配置。LangChain4j 的配置项在不同小版本里会有调整，我习惯不依赖 starter 的自动配置，而是手动创建模型对象，这样版本升级时影响最小：

spring: application: name: ai-customer-service ai: ollama: base-url: http://localhost:11434 chat-model: qwen2.5:7b embedding-model: nomic-embed-text server: port: 8080

然后写一个配置类，把 OllamaChatModel 作为 Bean 注册到 Spring 容器：

@Configuration public class OllamaConfig { @Value("${ai.ollama.base-url}") private String baseUrl; @Value("${ai.ollama.chat-model}") private String chatModel; @Bean public ChatLanguageModel chatLanguageModel() { return OllamaChatModel.builder() .baseUrl(baseUrl) .modelName(chatModel) .temperature(0.7) .timeout(Duration.ofSeconds(60)) .build(); } }

temperature控制回答的随机性。客服场景我建议设在 0.5 到 0.7 之间，太低回答会很机械，太高容易胡说。timeout一定要设大一点，本地模型在 CPU 上推理速度慢，默认超时时间很容易不够用。

3. 核心功能实现

3.1 第一版对话接口：快速跑通

配置完成后，写一个最基础的对话服务。先用 LangChain4j 的AiServices创建一个 Assistant 接口，这是 LangChain4j 的核心用法——你定义一个 Java 接口，框架通过动态代理帮你把大模型调用、提示词管理、工具绑定都串起来。

public interface CustomerAssistant { String chat(String message); }

然后创建 Service 类，把模型传进去，并暴露一个方法给 Controller 调用：

@Service public class ChatService { private final ChatLanguageModel chatLanguageModel; private CustomerAssistant assistant; public ChatService(ChatLanguageModel chatLanguageModel) { this.chatLanguageModel = chatLanguageModel; this.assistant = AiServices.builder(CustomerAssistant.class) .chatLanguageModel(chatLanguageModel) .build(); } public String chat(String message) { return assistant.chat(message); } }

Controller 写一个简单的 POST 接口：

@RestController @RequestMapping("/api/chat") public class ChatController { private final ChatService chatService; public ChatController(ChatService chatService) { this.chatService = chatService; } @PostMapping public Map<String, String> chat(@RequestBody Map<String, String> request) { String message = request.get("message"); String reply = chatService.chat(message); return Map.of("reply", reply); } }

到这里，一个最原始的客服机器人已经能跑了。找一个前端页面，或者在 Apifox 里发一段"你好，你们有什么产品"，模型会返回一段还像样的回复。

但我必须提醒：这个版本只能处理单轮对话，用户问完一个问题，再追问一句，模型就失忆了。下一个问题它完全不记得刚才聊过什么。真实客服场景必须解决这个问题。

3.2 多轮记忆：让客服记住上下文

大模型本身是无状态的，同一个模型实例，你每次调用它，它都不会记得之前的对话。想让机器人"记住"上下文，就要把历史消息一起发给模型。LangChain4j 提供了 ChatMemory 组件，用来管理消息历史的存取。

先改造 Assistant，给chat方法加一个@MemoryId参数：

public interface CustomerAssistant { String chat(@MemoryId String memoryId, @UserMessage String message); }

在构建 Assistant 时，绑定一个 ChatMemory。我用的MessageWindowChatMemory，它的作用是最多保留最近 N 条消息，超出范围的旧消息会被丢弃，避免上下文无限膨胀导致 token 超限：

@Service public class ChatService { private final ChatLanguageModel chatLanguageModel; private CustomerAssistant assistant; private final Map<String, ChatMemory> memoryStore = new ConcurrentHashMap<>(); public ChatService(ChatLanguageModel chatLanguageModel) { this.chatLanguageModel = chatLanguageModel; ChatMemory chatMemory = MessageWindowChatMemory.withMaxMessages(20); this.assistant = AiServices.builder(CustomerAssistant.class) .chatLanguageModel(chatLanguageModel) .chatMemory(chatMemory) .build(); } public String chat(String memoryId, String message) { return assistant.chat(memoryId, message); } }

注意，memoryId非常关键。如果所有用户共用一个 memoryId，两个人聊天内容就会串。我在实际接入时用用户 ID 作为 memoryId，游客场景用设备生成的 UUID，保证每个会话上下文隔离。

MessageWindowChatMemory.withMaxMessages(20)的意思是模型每次调用最多能看到最近 20 条消息。这个数字不是越大越好，消息越多，模型要处理的内容越长，响应越慢、显存占用越高。客服场景 20 条足够覆盖大部分对话轮次。

还有一个坑：LangChain4j 1.x 之后，ChatMemory 默认是单机内存存储，应用重启后聊天记录就没了。生产环境如果有多实例部署，需要自己实现ChatMemoryStore接口，把消息存到 Redis 或数据库里。这个我在后面生产落地部分展开。

3.3 RAG 知识库：接入内部文档

模型只会它的训练数据，你的产品说明书、售后政策、操作手册它完全不知道。把企业文档喂给模型，有两种办法：一是微调，成本高、周期长；二是 RAG，把文档切成片段、向量化、存起来，用户提问时先检索相关片段，再拼进提示词让模型基于片段回答。客服场景用 RAG 就足够。

先拉一个向量化模型。前面提到用nomic-embed-text，Ollama 拉起它之后，LangChain4j 里配置 OllamaEmbeddingModel：

@Bean public EmbeddingModel embeddingModel() { return OllamaEmbeddingModel.builder() .baseUrl(baseUrl) .modelName("nomic-embed-text") .build(); }

然后做文档接入。LangChain4j 里把文档加载、切分、向量化、入库这几个步骤封装成了流水线。我写了一个初始化方法，启动时读取 classpath 下的知识库文档：

@Component public class KnowledgeBaseInitializer { private final EmbeddingModel embeddingModel; public KnowledgeBaseInitializer(EmbeddingModel embeddingModel) { this.embeddingModel = embeddingModel; } @PostConstruct public void init() throws Exception { // 从 classpath 加载客服知识文档 var document = FileSystemDocumentLoader.loadDocument("knowledge/faq.txt"); // 按 300 字一段、重叠 50 字的方式切分文档 var splitter = DocumentSplitters.recursive(300, 50); var segments = splitter.split(document); // 向量化并存入内存向量库 var store = new InMemoryEmbeddingStore<>(); var embeddings = embeddingModel.encodeAll(segments); store.addAll(embeddings, segments); // 构建一个支持检索的辅助对象，后续注入到 Assistant 中 this.retriever = new EmbeddingStoreContentRetriever(store, embeddingModel, 3); } }

切分参数值得说一句：300 字一段比较适合中文客服文档，太短语义不完整，太长又容易混入无关内容。重叠 50 字是为了防止关键信息恰好被切断在边界。检索数量 3，表示每次从知识库挑 3 段最相关的内容拼进提示词，这个值要根据实际情况调。

把检索器和 Assistant 绑定：

this.assistant = AiServices.builder(CustomerAssistant.class) .chatLanguageModel(chatLanguageModel) .chatMemory(chatMemory) .contentRetriever(retriever) .build();

这下你再问"你们退货政策是什么"，模型会先从知识库检索出对应段落，再基于这些内容回答，而不是凭空编造。RAG 是智能客服落地中最关键的一环，没有它，模型就是一个只会聊天的摆设。

3.4 工具调用：让客服真正能干活

用户问"帮我查一下订单 12345 到哪了"，模型不知道订单物流数据，但它可以调用你写的 Java 方法去查。这就是工具调用，LangChain4j 里叫 Tool Calling。

定义一个工具类，方法加@Tool注解：

public class OrderTools { @Tool("根据订单号查询订单物流状态") public String queryOrderStatus(String orderId) { // 这里实际会调用订单系统的接口 return "订单 " + orderId + " 已于 2025-01-15 发货，当前正在运输中，预计 2025-01-18 到达"; } @Tool("根据订单号查询订单商品明细") public String queryOrderItems(String orderId) { return "订单 " + orderId + " 包含商品：智能手环 x1，替换表带 x2"; } }

方法名写清楚用途，参数和返回值尽量用简单类型，LangChain4j 会自动把模型生成的调用参数映射到方法参数上。工具方法返回的字符串会被模型整合到最终回答里。

构建 Assistant 时把工具注册进去：

this.assistant = AiServices.builder(CustomerAssistant.class) .chatLanguageModel(chatLanguageModel) .chatMemory(chatMemory) .contentRetriever(retriever) .tools(new OrderTools()) .build();

前面接口不用改，chat方法里的@Tool注解已经生效。调用流程变成：用户提问，模型判断需要查订单，生成一个工具调用，LangChain4j 帮你执行 Java 方法，拿到结果再让模型组织成自然语言回答。用户感觉不到中间过程，只觉得客服像个真人一样"知道"他的订单信息。

工具返回值未必完全可信，模型有可能在用户没提供订单号时直接生成一个假的订单号去调用。所以工具方法里一定要做参数校验，发现订单号格式不对就返回错误提示，让模型引导用户重新提供。

3.5 流式输出：提升交互体验

本地模型在 CPU 上推理速度慢，一个完整的回答可能要好几秒。如果让用户干等一个 HTTP 响应，体验很差。改成流式输出，模型生成一个字就往前端推一个字，用户第一秒就能看到内容在动，体感上会快很多。

SpringBoot 里做流式输出最简单的方式是引入 WebFlux，用 SSE 推送。先加依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency>

然后改造 Assistant，把接口返回值改成Flux<String>：

public interface CustomerAssistant { Flux<String> streamChat(@MemoryId String memoryId, @UserMessage String message); }

Controller 改成返回application/x-ndjson：

@PostMapping(value = "/stream", produces = "application/x-ndjson") public Flux<String> streamChat(@RequestBody Map<String, String> request) { return assistant.streamChat(request.get("memoryId"), request.get("message")); }

前端用 EventSource 或 fetch 流式读取即可。我实际测试下来，首字返回时间比整体返回快了 50% 以上，用户明显感觉"变快了"。其实不是速度变快，是感知变快了，但这在客服场景里非常重要。

4. 常见故障与生产落地经验

4.1 前几天最容易踩的坑

我把一开始踩过的坑整理成了一份速查表。这些是我在联调阶段真实遇到的，按出现概率排序：

这里单独说说内存问题。本地模型跑起来不是一次性占用全部权重，而是按需加载到内存。但如果你同时开了对话模型和 embedding 模型，机器内存又不大，很容易触发 OOM。建议在同一台机器上只保留一个对话模型常驻，embedding 模型用的时候再唤醒，让 Ollama 自动管理。

如果机器实在跑不动 7B 模型，可以用 4B 或 3B 的量化版本，或者换成 qwen2.5:3b。差距主要在复杂推理能力，客服这种短对话场景，3B 模型也能顶一顶。

4.2 性能和资源怎么优化

先把预期放在前面：本地模型不是万能的，它的响应速度和云端 GPT 级别的模型没法比。但可以通过几个手段把体验拉到可接受范围。

第一，对话模型尽量跑在独显上。CPU 推理 7B 模型，一个字符可能就要几十毫秒，一句话算下来要十几秒。有显卡的话，推理速度能快好几倍。没有独显就老老实实用小模型，别硬撑。

第二，控制上下文长度。前面说的withMaxMessages(20)，就是防止消息历史无限膨胀。消息越长，模型每轮推理要处理的内容越多，速度越慢。如果用户对话很长，考虑定期总结历史并截断。

第三，合理配置 Ollama 的并发参数。Ollama 默认可以并行处理请求，但并发太高会把显存打满，后面请求排长队。我一般限制为单模型并发 1 到 2，多的请求排队处理，避免互相拖垮。可以设置OLLAMA_NUM_PARALLEL=1。

第四，使用流式输出。这个前面说了，是投入产出比最高的一项改动，强烈建议第一时间做。

第五，响应缓存。高频问题（比如"你们几点上班"）的结果可以缓存到本地，没必要每次让模型重新生成。我自己在网关层做了一个简单缓存，命中率大概在 20% 左右，能省一部分算力。

4.3 上线前还要处理哪些事

把 Demo 跑通只是第一步，真正上线要处理的事情还很多。

会话隔离要做扎实。客服系统通常有明确用户体系，memoryId直接用用户 ID 没问题。但如果是未登录咨询场景，建议用服务端生成的 UUID 代替用户传入的 ID，避免有人伪造 memoryId 看到别人的聊天上下文。

人工接管机制不能省。模型答不上来、用户要求转人工，这些状态要有一套兜底流程。我的做法是：当用户连续两次表达不满，或者明确说"转人工"，客服机器人直接返回一段话术并触发工单创建。这个逻辑写在 SpringBoot 服务里，判断模型输出或用户输入即可。

内容安全要过一遍。不是所有问题都适合让模型自由发挥，尤其是涉及个人隐私、法律法规类的咨询，建议在提示词里明确"不知道的就回答不知道，引导用户转人工"。同时在工具方法里限制能查询的数据范围，比如普通客服工具只能查本人的订单，不能查别人的。

监控和日志。LangChain4j 本身不提供完整的可观测性，我建议至少把每次对话的请求参数、模型响应、耗时、token 消耗记到日志里。排查线上问题时，这些日志非常关键。有条件的话可以把每次检索命中的知识片段也记录下来，用于后续优化提示词和切分参数。

多实例部署时，ChatMemory 和向量库都要换成共享存储。内存版 ChatMemory 在单实例没问题，一旦水平扩展就会串。向量库可以从 InMemory 换成 PGVector 或 Qdrant，这个替换成本不算大，LangChain4j 的接口是统一的，换实现类就行。

最后说一个我个人的小经验：LangChain4j 的版本更新很快，小版本之间 API 会有调整，尤其是 starter 和手动配置混用的时候，经常出现类找不到的情况。我的做法是固定一个大版本，不要随手升级。所有模型相关的配置都放在一个配置类里，后续升级版本时只需要改这一个文件，排查问题也方便。这套组合跑了一段时间，整体稳定，问题大多出在模型能力边界和知识库质量上，框架本身没出过什么幺蛾子。