LangChain4j 实战：在 Java 项目中接入大模型的完整记录

第一个模块用通义千问 qwen-plus，接入方式走 OpenAI 兼容接口。先去阿里云百炼申请 Key，baseUrl 固定为 https://dashscope.aliyuncs.com/compatible-mode/v1。

工程结构长这样：

新建子模块 langChain4j-01study，pom 加上 langchain4j-open-ai 和 langchain4j。

配置类直接创建 OpenAiChatModel Bean：

@Configuration
public class LLMConfig {
    @Bean
    public ChatModel chatModel() {
        return OpenAiChatModel.builder()
                .apiKey(System.getenv("aliQwen-api"))
                .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                .modelName("qwen-plus")
                .build();
    }
}

控制器里调用 chatModel.chat(msg) 就能得到回复。

多模型共存：加一个 DeepSeek

同一个工程里用不同模型也很简单。DeepSeek 的 baseUrl 是 https://api.deepseek.com/v1，模型名 deepseek-chat，去官网拿 Key。

配置类里声明两个带不同名字的 Bean：

@Bean("qwen")
public ChatModel qwenChatModel() {
    return OpenAiChatModel.builder()
            .apiKey(System.getenv("aliQwen-api"))
            .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
            .modelName("qwen-plus")
            .build();
}

@Bean("deepseek")
public ChatModel deepseekChatModel() {
    return OpenAiChatModel.builder()
            .apiKey("sk-4af********")
            .baseUrl("https://api.deepseek.com/v1")
            .modelName("deepseek-chat")
            .build();
}

控制器分别注入两个模型，测试都能正常响应。

和 Spring Boot 深度整合

LangChain4j 提供了 Spring Boot Starter，在配置文件里写几行就能自动装配。

官方教程

新建模块 langChain4j-02boot，pom 引入 langchain4j-open-ai-spring-boot-starter 和 langchain4j-spring-boot-starter。

properties 配置：

langchain4j.open-ai.chat-model.api-key=${aliQwen-api}
langchain4j.open-ai.chat-model.model-name=qwen-plus
langchain4j.open-ai.chat-model.base-url=https://dashscope.aliyuncs.com/compatible-mode/v1

ChatModel Bean 会自动创建。也可以使用 @AiService 声明式接口，框架生成代理。

低阶 API vs 高阶 API

LangChain4j 有两层抽象，可以根据场景选。

文档说明

• 低阶 API：直接操作 ChatModel、UserMessage、ChatResponse 等，能拿到 token 消耗，控制力强。
• 高阶 API：通过 AiServices.create(interface, model) 代理接口，代码更少。

新建模块 langChain4j-03lowhigh。

低阶调用示例：

@GetMapping("/chat1")
public String chat1(@RequestParam String msg) {
    return chatModel.chat(msg);
}

如果想拿 token 信息，可以这样：

ChatResponse chatResponse = chatModel.chat(UserMessage.from(msg));
TokenUsage tokenUsage = chatResponse.tokenUsage();
System.out.println("本次 token 消耗：" + tokenUsage);

高阶 API 定义一个接口：

public interface ChatAssistant {
    String chat(String prompt);
}

@Bean
public ChatAssistant chatAssistant(ChatModel chatModel) {
    return AiServices.create(ChatAssistant.class, chatModel);
}

调整模型参数

几个常用配置可以在 builder 里设置。

日志：.logRequests(true).logResponses(true)，同时 logging.level.dev.langchain4j=DEBUG。

监听器：实现 ChatModelListener 可以在请求/响应时插入逻辑，比如透传 TraceID。

重试：.maxRetries(2)，网络异常时会自动重试。断开网络后访问，可以看到重试请求：

超时：.timeout(Duration.ofSeconds(1))，避免长时间卡住。

多模态：看图说话

视觉模型（如 qwen-vl-max）能同时理解文本和图片。新建模块 langChain4j-04chatimage。

配合 UserMessage 里的 ImageContent 可以把 base64 图片传进去。

byte[] imageBytes = resource.getContentAsByteArray();
String base64 = Base64.getEncoder().encodeToString(imageBytes);
UserMessage userMessage = UserMessage.from(
    TextContent.from("描述图片内容"),
    ImageContent.from(base64, "image/jpg")
);

阿里的文生图模型 wanx2.1-t2i-turbo 也能通过 langchain4j-community-dashscope 接入。新建模块 langChain4j-05chatimage。

Response<Image> generate = wanxImageModel.generate("一只猫");
String url = generate.content().url().toString();

也可以自定义参数：

ImageSynthesisParam build = ImageSynthesisParam.builder()
        .apiKey(System.getenv("aliQwen-api"))
        .model("wanx2.1-t2i-turbo")
        .prompt(prompt)
        .n(2)
        .size("1024*1024")
        .build();
ImageSynthesisResult result = new ImageSynthesis().call(build);

流式输出

服务端生成一段，客户端就收到一段，体验会好很多。引入 langchain4j-reactor 就行。

新建模块 langChain4j-06chatstream。

StreamingChatModel 配合 Flux 使用：

@GetMapping("/chat1")
public Flux<String> chat1(String msg) {
    return Flux.create(fluxSink -> {
        streamingChatModel.chat(msg, new StreamingChatResponseHandler() {
            @Override
            public void onPartialResponse(String s) {
                fluxSink.next(s);
            }
            @Override
            public void onCompleteResponse(ChatResponse cr) {
                fluxSink.complete();
            }
            // ...
        });
    });
}

对话记忆

为了让模型记住上下文，LangChain4j 提供了 MessageWindowChatMemory 和 TokenWindowChatMemory。

新建模块 langChain4j-07chatmemory。

在 AiService 里用 @MemoryId 标注，框架会按 id 保存历史。

public interface ChatMemoryAssistant {
    String chat(@MemoryId Long userId, @UserMessage String prompt);
}

@Bean
public ChatMemoryAssistant assistant(ChatModel model) {
    return AiServices.builder(ChatMemoryAssistant.class)
            .chatModel(model)
            .chatMemoryProvider(memoryId -> MessageWindowChatMemory.withMaxMessages(20))
            .build();
}

测试：user 1 说自己叫 Java，再问'我叫什么'，回答正确；user 3 的记忆互不干扰。

提示词工程

多种方式组织提示词。

新建模块 langChain4j-08chatprompt。

注解方式：

@SystemMessage("你是一位专业的中国法律顾问，只回答与中国法律相关的问题")
@UserMessage("请回答：{{question}}，字数控制在{{length}}以内")
String chat(@V("question") String question, @V("length") int length);

结构化模板：用 @StructuredPrompt 注解 POJO。

@StructuredPrompt("根据中国{{legal}}法律解答：{{question}}")
public class LawPrompt {
    private String legal;
    private String question;
}

程序化 PromptTemplate：

PromptTemplate template = PromptTemplate.from("你是一个{{it}}助手，{{question}}怎么办");
Prompt prompt = template.apply(Map.of("it", "财务", "question", "人民币大写"));
ChatResponse response = chatModel.chat(prompt.toUserMessage());

持久化到 Redis

默认的 ChatMemory 在内存中，重启就没了。实现 ChatMemoryStore 接口可以把消息存进 Redis。

新建模块 langChain4j-09chatPersistence。

@Component
public class RedisChatMemoryStore implements ChatMemoryStore {
    @Override
    public List<ChatMessage> getMessages(Object memoryId) {
        String json = redisTemplate.opsForValue().get("chat_memory:" + memoryId);
        return ChatMessageDeserializer.messagesFromJson(json);
    }

    @Override
    public void updateMessages(Object memoryId, List<ChatMessage> list) {
        redisTemplate.opsForValue().set("chat_memory:" + memoryId, ChatMessageSerializer.messagesToJson(list));
    }

    @Override
    public void deleteMessages(Object memoryId) {
        redisTemplate.delete("chat_memory:" + memoryId);
    }
}

然后在 ChatMemoryProvider 里使用这个 Store。测试后可以看到 Redis 里有了对应 key。

工具调用 (Function Calling)

大模型通过 Function Calling 告诉我们需要调哪个函数、传什么参数。LangChain4j 支持低阶和高阶两种方式。

新建模块 langChain4j-10chatFunctionCalling。

低阶 API 手工构建 ToolSpecification 和 ToolExecutor：

ToolSpecification tool = ToolSpecification.builder()
        .name("开具发票助手")
        .description("根据信息开具发票")
        .parameters(JsonObjectSchema.builder()
                .addStringProperty("companyName", "公司名称")
                .addStringProperty("dutyNumber", "税号")
                .addStringProperty("amount", "金额")
                .build())
        .build();

高阶 API 只需要把带有 @Tool 注解的类交给 AiServices。这里以查询天气为例，借助和风天气 API。

去 dev.qweather.com 注册账号，创建凭据。

编写天气服务类，注意替换你自己的 key：

@Service
public class WeatherService {
    private static final String URL = "https://api.qweather.com/v7/weather/now?location=%s&key=%s";

    public JsonNode getWeather(String location) {
        String url = String.format(URL, location, "你的KEY");
        // 发送 GET 请求并解析为 JsonNode
        return new ObjectMapper().readTree(new RestTemplate().getForObject(url, String.class));
    }
}

然后定义工具类：

public class InvoiceHandler {
    @Tool("获取天气信息")
    public String handle(@P("天气状况") String text, @P("风向") String windDir) throws Exception {
        System.out.println("天气状况：" + text + " 风向：" + windDir);
        return new WeatherService().getWeather("101010100").toString();
    }
}

配置类：

@Bean("highfunction")
public FunctionAssistant highFunctionAssistant(ChatModel chatModel) {
    return AiServices.builder(FunctionAssistant.class)
            .chatModel(chatModel)
            .tools(new InvoiceHandler())
            .build();
}

测试'北京今天的天气'，输出天气信息。

待补充

向量数据库、RAG 和 MCP 模型上下文切换的部分正在整理，后续会持续更新。