Java LangChain4j 框架入门：环境搭建与 AI 服务集成

若需要使用流式消息，配置如下：

langchain4j.open-ai.streaming-chat-model.api-key=${OPENAI_API_KEY}

3. 获取 AI 接口密钥

以 DeepSeek 为例（量大且便宜）。进入 API 开放平台选择密钥管理，创建 apiKey。充值余额后，将 key 粘贴到 yml 文件的 api-key 后面。

官方建议示例：

String apiKey = System.getenv("OPENAI_API_KEY");

三、测试

基础 ChatModel 调用

@RestController
public class ChatController {
    @Autowired
    private ChatModel chatModel;

    @RequestMapping("/chat")
    public String toChat(@RequestParam(value = "message") String message) {
        return chatModel.chat(message);
    }
}

单元测试：

@Test
public void test2() {
    // 假设注入的 Controller Bean 名为 chatController
    String response = chatController.toChat("你好，AI!");
    System.out.println("response:" + response);
}

请求会被转换为 JSON 格式的 POST 请求，API Key 加入请求头 Authorization 校验，Body 包含模型名称及是否流式等信息。

四、对话进阶

一、AiService 初识

为使用更多功能，推荐使用 AiService。

1. 引入依赖

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>1.12.2-beta22</version>
</dependency>

该依赖自动配置 AI 服务、RAG、工具等功能。

2. 定义接口

@AiService
public interface Assistant {
    @SystemMessage("你是小离")
    String chat(String userMessage);
}

3. 注入与调用

@Autowired
private Assistant assistant;

@RequestMapping("/ServiceChat")
public String chat2(String msg) {
    return assistant.chat(msg);
}

测试结果显示 AI 会根据系统消息设定返回内容。

二、AiService 的其他特性

1. 多模型支持

可在配置中定义多个模型，并通过 wiringMode 指定注入哪个模型。

# OpenAI
langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.chat-model.model-name=gpt-4o-mini
# Ollama
langchain4j.ollama.chat-model.base-url=http://localhost:11434
langchain4j.ollama.chat-model.model-name=llama3.1

@AiService(wiringMode = EXPLICIT, chatModel = "openAiChatModel")
interface OpenAiAssistant {
    @SystemMessage("You are a polite assistant")
    String chat(String userMessage);
}

@AiService(wiringMode = EXPLICIT, chatModel = "ollamaChatModel")
interface OllamaAssistant {
    @SystemMessage("You are a polite assistant")
    String chat(String userMessage);
}

2. 支持流式消息

使用 StreamChatModel 时，AI 服务返回类型可使用 Flux<String>。

@SystemMessage("你是小离")
Flux<String> chat2(String userMessage);

需引入 Reactor 依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-reactor</artifactId>
    <version>1.0.0-beta3</version>
</dependency>

可通过 ChatModelListener 监听请求与响应：

@Configuration
class MyConfiguration {
    @Bean
    ChatModelListener chatModelListener() {
        return new ChatModelListener() {
            private static final Logger log = LoggerFactory.getLogger(ChatModelListener.class);
            @Override
            public void onRequest(ChatModelRequestContext requestContext) {
                log.info("onRequest(): {}", requestContext.chatRequest());
            }
            @Override
            public void onResponse(ChatModelResponseContext responseContext) {
                log.info("onResponse(): {}", responseContext.chatResponse());
            }
            @Override
            public void onError(ChatModelErrorContext errorContext) {
                log.info("onError(): {}", errorContext.error().getMessage());
            }
        };
    }
}

三、工具 (Tools)

工具相当于 LLM 的手臂，使其能触发操作。需提供清晰的工具名称、功能描述及参数说明。

示例：BookingTools

@Service
public class BookingTools {
    @Tool("一个说你好的工具，如果你的满意值达到 90，请使用这个工具，并输入你的满意值")
    public void sayHello(@P(value = "你的满意值 (0-100)", required = true) Integer Satisfied) {
        if (Satisfied >= 90) {
            System.out.println("哈喽哇，你好呀");
        } else {
            System.out.println("Ai，心情有点不太好");
        }
    }
}

测试：

@Test
public void test3() {
    String response = chatController.toChat("你是谁？然后回复一下你的满意度");
    System.out.println("response:" + response);
}

注意：若描述不清，AI 可能无法正确调用工具。

1. Tool 注解参数

• name()：工具名称，默认方法名。
• value()：工具描述。
• returnBehavior()：控制执行结果返回给 AI 还是直接返回给用户。
  • ReturnBehavior.TO_LLM（默认）：用户 → AI → 工具 → AI 组织语言 → 用户。
  • ReturnBehavior.IMMEDIATE：用户 → AI → 工具 → 直接返回用户。
• searchBehavior()：控制工具是否对 AI 可见。
  • SearchBehavior.SEARCHABLE（默认）：通过搜索策略匹配。
  • SearchBehavior.ALWAYS_VISIBLE：始终可见。
• metadata()：额外信息。

2. 工具注入上下文

在 AutoConfiguration.imports 文件中定义了 dev.langchain4j.spring.LangChain4jAutoConfig，导入了 AiServicesAutoConfig。该类遍历 Bean 容器中含有 @Tool 注解的方法，组装 ToolSpecification 并设置到 AiServiceFactory 的上下文中，最终在 DefaultAiServices 的代理实现中完成工具组装。

本文介绍了 LangChain4j 的基础环境搭建、ChatModel 调用、AiService 核心功能及工具集成原理，为后续深入 RAG 及会话存储打下基础。