Spring Boot 集成 LangChain4j 实战指南

如果是其他模型（如 Azure OpenAI、Ollama 等），请将 open-ai 替换为对应的集成名称（如 azure-open-ai, ollama 等）。

3. 配置文件设置

在 application.properties 或 application.yml 中配置模型参数。推荐使用环境变量来管理敏感信息（如 API Key），避免硬编码。

3.1 基础 Chat 模型配置

# 设置 OpenAI API Key，实际生产环境建议使用 ${OPENAI_API_KEY} 读取环境变量
langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
# 指定使用的模型名称，例如 GPT-4o
langchain4j.open-ai.chat-model.model-name=gpt-4o
# 开启请求日志，便于调试
langchain4j.open-ai.chat-model.log-requests=true
# 开启响应日志
langchain4j.open-ai.chat-model.log-responses=true

3.2 流式输出配置

如果需要支持流式响应（Streaming），需额外配置 streaming-chat-model：

langchain4j.open-ai.streaming-chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.streaming-chat-model.model-name=gpt-4o

启动后，Spring Boot 会自动创建 OpenAiChatModel 实例（实现 ChatLanguageModel 接口）以及 StreamingChatLanguageModel 实例，并注册到 Spring 容器中。

4. 基础聊天功能实现

通过依赖注入，可以在任何 Spring Bean 中使用已配置的模型。

4.1 同步聊天示例

创建一个 REST Controller 来处理简单的文本生成请求：

import dev.langchain4j.model.chat.ChatLanguageModel;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    private final ChatLanguageModel chatLanguageModel;

    // 构造函数注入
    public ChatController(ChatLanguageModel chatLanguageModel) {
        this.chatLanguageModel = chatLanguageModel;
    }

    @GetMapping("/chat")
    public String model(@RequestParam(value = "message", defaultValue = "Hello") String message) {
        // 直接调用模型生成回复
        return chatLanguageModel.generate(message);
    }
}

4.2 流式聊天示例

对于需要实时反馈的场景，可以使用流式模型。注意返回类型可能需要调整为 SseEmitter 或使用 WebFlux。

import dev.langchain4j.model.chat.StreamingChatLanguageModel;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StreamingChatController {

    private final StreamingChatLanguageModel streamingChatLanguageModel;

    public StreamingChatController(StreamingChatLanguageModel streamingChatLanguageModel) {
        this.streamingChatLanguageModel = streamingChatLanguageModel;
    }

    @GetMapping("/chat-stream")
    public void streamChat(@RequestParam String message) {
        // 此处应结合 SseEmitter 处理流式数据推送
        // streamingChatLanguageModel.generate(message, new TokenStream() { ... });
    }
}

5. 声明式 AI 服务 (@AiService)

LangChain4j 提供了强大的声明式编程能力，允许通过接口定义 AI 行为，类似于标准的 Spring @Service。

5.1 定义 AI 服务接口

使用 @AiService 注解标记接口，并使用提示词注解定义系统指令。

import dev.langchain4j.service.AiService;
import dev.langchain4j.service.SystemMessage;

@AiService
interface Assistant {

    @SystemMessage("You are a polite and helpful assistant.")
    String chat(String userMessage);
}

5.2 使用 AI 服务

启动时，LangChain4j 会扫描类路径下所有带有 @AiService 的接口，并根据上下文中的组件（如 ChatModel、EmbeddingStore 等）自动生成实现类。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
class AssistantController {

    @Autowired
    private Assistant assistant;

    @GetMapping("/assistant/chat")
    public String chat(String message) {
        return assistant.chat(message);
    }
}

5.3 高级提示词控制

除了 @SystemMessage，还可以使用 @UserMessage 动态注入上下文，或者使用 @MemoryId 管理会话状态。

@AiService
class AdvancedAssistant {

    @SystemMessage("You are an expert developer.")
    String answer(@UserMessage String question, @MemoryId Long memoryId);
}

6. 工具调用 (Tool Use)

为了让 AI 执行具体操作（如查询数据库、调用外部 API），可以注册自定义工具。

6.1 定义工具类

使用 @Component 和 @Tool 注解。

import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;

@Component
public class BookingTools {

    // 模拟业务服务
    private BookingService bookingService;

    @Tool("Cancels a booking based on the provided details")
    public String cancelBooking(String bookingNumber, String customerName, String customerSurname) {
        try {
            bookingService.cancelBooking(bookingNumber, customerName, customerSurname);
            return "Booking cancelled successfully.";
        } catch (Exception e) {
            return "Error cancelling booking: " + e.getMessage();
        }
    }
}

6.2 集成到 AI 服务

在 @AiService 接口中声明方法，LangChain4j 会自动识别并注入工具。

@AiService
interface SupportAgent {
    String chat(String userMessage);
}

当用户询问如何取消预订时，AI 会自动选择调用 cancelBooking 工具。

7. RAG (检索增强生成) 集成概览

虽然本文主要关注 Chat 模型，但 LangChain4j 也支持 RAG 模式，即结合私有知识库回答问题。

7.1 嵌入模型配置

需要引入 Embedding Model 的 Starter（如 langchain4j-embeddings-all-minilm-l6-v2）。

7.2 向量存储配置

配置一个向量存储（如 Redis, PostgreSQL, Elasticsearch）作为 EmbeddingStore。

7.3 构建 RAG 服务

使用 @RagResponseBuilder 或手动构建 RetrievalAugmentor 来实现知识检索。

8. 常见问题与最佳实践

8.1 安全性

• API Key 管理：永远不要将 API Key 提交到代码仓库。务必使用环境变量或密钥管理服务（如 Vault）。
• 输入过滤：对用户输入进行校验，防止 Prompt Injection 攻击。

8.2 性能优化

• 缓存：对于重复的查询，考虑在应用层实现缓存机制。
• 超时设置：配置合理的 HTTP 超时时间，防止 LLM 响应过慢阻塞线程。

8.3 错误处理

• 异常捕获：LLM 调用可能因网络或服务端问题失败，建议在 Service 层添加 try-catch 块并提供友好的降级策略。
• 重试机制：对于偶发性错误，可配置指数退避重试策略。

9. 总结

通过 LangChain4j 的 Spring Boot Starter，开发者可以极大地简化 AI 应用的开发流程。从基础的对话机器人到复杂的 RAG 系统，Spring 的自动配置和依赖注入机制让 AI 组件的管理变得像普通 Bean 一样简单。建议在实际项目中遵循上述最佳实践，确保应用的安全性、稳定性和可扩展性。