Spring Boot项目里，5分钟搞定LangChain4j调用本地Ollama模型（附完整代码）

Spring Boot项目快速集成LangChain4j调用本地Ollama模型实战指南

在当今AI技术快速发展的背景下，将大语言模型能力集成到现有Java应用中已成为提升产品竞争力的有效手段。本文将手把手指导Spring Boot开发者如何在5分钟内完成LangChain4j与本地Ollama模型的对接，无需复杂配置即可为应用注入AI能力。

1. 环境准备与基础配置

1.1 创建Spring Boot项目

使用Spring Initializr快速生成项目骨架，选择以下核心依赖：

curl https://start.spring.io/starter.zip \ -d dependencies=web,lombok \ -d language=java \ -d type=gradle-project \ -d javaVersion=17 \ -d artifactId=ollama-demo \ -o ollama-demo.zip

关键依赖说明：

• Spring Web：提供RESTful接口支持
• Lombok：简化Java Bean编写

1.2 添加LangChain4j依赖

在build.gradle中添加Ollama集成包：

dependencies { implementation 'dev.langchain4j:langchain4j-ollama-spring-boot-starter:0.25.0' // 其他已有依赖... }

注意：建议使用最新稳定版本，可通过Maven中央仓库查询

2. Ollama本地服务配置

2.1 安装与启动Ollama

根据操作系统下载对应版本（以macOS为例）：

brew install ollama ollama pull llama2 # 下载基础模型 ollama serve # 启动服务

服务默认监听端口为11434，可通过以下命令验证：

curl http://localhost:11434/api/tags

2.2 Spring Boot应用配置

在application.yml中添加：

langchain4j: ollama: chat-model: base-url: http://localhost:11434 model-name: llama2 temperature: 0.7 timeout: 60s

关键参数说明：

• model-name：指定使用的本地模型
• temperature：控制生成文本的随机性（0-1）
• timeout：设置请求超时时间

3. 核心代码实现

3.1 创建对话服务

@Service @RequiredArgsConstructor public class AIChatService { private final OllamaChatModel chatModel; public String chat(String message) { return chatModel.generate(message); } public List<String> multiTurnChat(List<ChatMessage> history) { return chatModel.generate(history.stream() .map(m -> new dev.langchain4j.data.message.ChatMessage( m.role().equals("user") ? USER : AI, m.content())) .collect(Collectors.toList())); } }

3.2 实现REST接口

@RestController @RequestMapping("/api/ai") @RequiredArgsConstructor public class AIController { private final AIChatService chatService; @PostMapping("/chat") public ResponseEntity<String> simpleChat(@RequestBody String prompt) { return ResponseEntity.ok(chatService.chat(prompt)); } @PostMapping("/chat/history") public ResponseEntity<List<String>> contextualChat( @RequestBody List<ChatMessage> messages) { return ResponseEntity.ok(chatService.multiTurnChat(messages)); } }

4. 高级功能扩展

4.1 流式响应处理

修改控制器支持Server-Sent Events：

@GetMapping(path = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> streamChat(@RequestParam String prompt) { return Flux.create(sink -> { chatModel.generate(prompt, new StreamingResponseHandler() { @Override public void onNext(String token) { sink.next(token); } @Override public void onComplete() { sink.complete(); } @Override public void onError(Throwable error) { sink.error(error); } }); }); }

4.2 自定义模型参数

动态调整生成参数：

public String chatWithParams(String prompt, float temperature, int maxTokens) { return chatModel.builder() .temperature(temperature) .maxTokens(maxTokens) .build() .generate(prompt); }

4.3 异常处理建议

全局异常处理器示例：

@RestControllerAdvice public class AIExceptionHandler { @ExceptionHandler(OllamaException.class) public ResponseEntity<ErrorResponse> handleOllamaError(OllamaException ex) { return ResponseEntity.status(502) .body(new ErrorResponse("AI_SERVICE_ERROR", ex.getMessage())); } }

5. 性能优化与监控

5.1 连接池配置

在application.yml中增加：

langchain4j: ollama: client: connect-timeout: 5s read-timeout: 30s max-retries: 3 connection-pool: max-idle: 10 max-total: 20

5.2 监控指标集成

添加Micrometer监控：

@Bean public OllamaMetrics ollamaMetrics(MeterRegistry registry) { return new OllamaMetrics(registry); }

关键监控指标包括：

• langchain4j.ollama.requests.duration
• langchain4j.ollama.requests.count
• langchain4j.ollama.errors.count

5.3 缓存策略实现

@Cacheable(value = "aiResponses", key = "#prompt.hashCode()") public String getCachedResponse(String prompt) { return chatModel.generate(prompt); }

6. 安全防护方案

6.1 请求限流配置

使用Resilience4j实现：

@Bean public OllamaChatModel rateLimitedChatModel( OllamaChatModel delegate, RateLimiterRegistry registry) { RateLimiter limiter = registry.rateLimiter("ollama"); return new RateLimitedOllamaChatModel(delegate, limiter); }

6.2 内容过滤机制

public String safeChat(String prompt) { if (containsSensitiveWords(prompt)) { throw new ContentPolicyViolationException(); } return chatModel.generate(prompt); } private boolean containsSensitiveWords(String text) { // 实现自定义过滤逻辑 return false; }

7. 测试验证方案

7.1 单元测试示例

@SpringBootTest class AIChatServiceTest { @Autowired private AIChatService chatService; @Test void shouldReturnResponse() { String response = chatService.chat("你好"); assertThat(response).isNotBlank(); } }

7.2 集成测试配置

测试专用配置类：

@TestConfiguration public class TestOllamaConfig { @Bean @Primary public OllamaChatModel mockOllama() { return new OllamaChatModel() { @Override public String generate(String prompt) { return "Mock response for: " + prompt; } }; } }

8. 部署优化建议

8.1 Docker Compose配置

docker-compose.yml示例：

version: '3.8' services: ollama: image: ollama/ollama ports: - "11434:11434" volumes: - ollama_data:/root/.ollama app: build: . ports: - "8080:8080" depends_on: - ollama volumes: ollama_data:

8.2 健康检查端点

自定义健康指标：

@Component public class OllamaHealthIndicator implements HealthIndicator { private final OllamaClient client; @Override public Health health() { try { client.listModels(); return Health.up().build(); } catch (Exception e) { return Health.down(e).build(); } } }

9. 常见问题解决

9.1 连接超时排查

典型错误场景处理流程：

1. 验证Ollama服务状态：ollama list
2. 检查端口连通性：telnet localhost 11434
3. 查看Spring Boot日志中的连接错误详情

9.2 内存优化配置

JVM参数建议：

java -Xms512m -Xmx2g -XX:MaxRAMPercentage=75.0 -jar your-app.jar

Ollama启动参数调整：

OLLAMA_NUM_PARALLEL=2 ollama serve

10. 架构设计建议

10.1 服务分层设计

推荐架构模式：

Controller Layer → Service Layer → AI Adapter Layer → LangChain4j Client

10.2 异步处理实现

使用Spring WebFlux实现非阻塞调用：

@GetMapping("/async") public Mono<String> asyncChat(@RequestParam String prompt) { return Mono.fromCallable(() -> chatService.chat(prompt)) .subscribeOn(Schedulers.boundedElastic()); }

11. 模型管理进阶

11.1 多模型切换策略

动态模型选择实现：

public String chatWithModel(String prompt, String modelName) { return OllamaChatModel.builder() .baseUrl(baseUrl) .modelName(modelName) .build() .generate(prompt); }

11.2 本地模型缓存

实现模型预加载机制：

@PostConstruct public void preloadModels() { Arrays.asList("llama2", "mistral").forEach(model -> { ollamaClient.pullModel(model); }); }

12. 客户端集成示例

12.1 Web前端对接

JavaScript调用示例：

fetch('/api/ai/chat', { method: 'POST', body: JSON.stringify("如何学习Spring Boot") }).then(response => response.text()) .then(data => console.log(data));

12.2 移动端适配

Android Retrofit接口定义：

interface AIService { @POST("/api/ai/chat") suspend fun chat(@Body prompt: String): Response<String> }

13. 日志与诊断

13.1 请求日志配置

在application.yml中启用详细日志：

logging: level: dev.langchain4j: DEBUG

13.2 诊断端点实现

@GetMapping("/diag") public Map<String, Object> diagnostics() { return Map.of( "modelStatus", ollamaClient.listModels(), "systemLoad", ManagementFactory.getOperatingSystemMXBean().getSystemLoadAverage() ); }

14. 成本控制策略

14.1 计费单元设计

实现简单的使用量统计：

@Aspect @Component public class UsageTrackingAspect { @Autowired private UsageMetrics metrics; @Around("execution(* com..AIChatService.*(..))") public Object trackUsage(ProceedingJoinPoint pjp) throws Throwable { long start = System.currentTimeMillis(); Object result = pjp.proceed(); metrics.record(pjp.getSignature().getName(), System.currentTimeMillis() - start); return result; } }

14.2 资源限制实现

基于Spring的RateLimiter：

@Bean public RateLimiter aiRateLimiter() { return RateLimiter.create(10); // 10请求/秒 }

15. 扩展阅读与资源

15.1 官方文档参考

• LangChain4j Ollama集成文档
• Ollama模型库

15.2 性能优化白皮书

关键指标基准测试结果：