LangChain4J-(2)-高阶API与低阶API

一、ChatLanguageModel 和 LanguageModel

ChatLanguageModel 和 LanguageModel 两种 API 类型是由 LangChain4j 框架提供，用于与大型语言模型（LLM）进行交互

1.1 LanguageModel

• 输入输出形式：其 API 设计较为简单，以单个字符串作为输入，并返回一个字符串作为输出。
• 适用场景：适合进行简单的文本生成或文本补全任务，比如将其用于快速获取针对某一简单问题的文本答案，或依据简短提示续写文本等基本场景。
• 现状：这种 API 正在逐渐被聊天 API 取代，LangChain4j 也明确表示后续不再扩展对它的支持。

1.2 ChatLanguageModel

• 输入输出形式：接受一个或多个 ChatMessage 作为输入，输出则为 AiMessage。ChatMessage 存在多种类型，包含代表用户提问的 UserMessage、设定任务背景或模型行为的 SystemMessage 及表示模型回复的 AiMessage 等，能清晰区分对话中的不同角色内容。
• 适用场景：因支持以消息序列的形式输入，其更适配构建需维护上下文的对话场景，契合多数现代聊天式 AI 应用的开发需求。像 OpenAI GPT-4o-mini、Google Gemini-1.5-pro 等主流大模型常借由此 API 接入。
• 额外能力：部分支持多模态的模型借助 ChatLanguageModel API，可通过 ChatMessage 传递图像、音频等非文本数据。例如能将文本搭配图像一同输入至 Gemini-1.5-pro，以完成基于图像内容分析提问等任务。

二、langchain4j在两个抽象层提供的不同api

LangChain4j 在与大语言模型（LLM）交互时，主要通过两个核心抽象层提供不同级别的 API，分别是低级 API（低级 API） 和high-level API（高级 API）。这两个抽象层针对不同的使用场景设计，提供了从基础交互到复杂应用的完整能力支持。

2.1 低阶 API（Low-Level API）：直接与模型交互

低级 API 是 LangChain4j 最基础的抽象，专注于与 LLM 进行直接、原始的交互，提供对模型输入输出的精细化控制。它主要包含以下核心接口：

1）LanguageModel

最基础的文本生成接口，接收字符串形式的提示（Prompt），返回模型生成的字符串结果。

适用于简单的文本补全、生成任务，不支持对话上下文管理。

示例：

LanguageModel model = OpenAiLanguageModel.builder().apiKey("your-api-key").modelName("gpt-3.5-turbo-instruct").build();String response = model.generate("请介绍一下 LangChain4j");

2）ChatLanguageModel

针对对话场景设计的接口，接收ChatMessage列表（包含用户消息、系统消息、模型回复等），返回模型生成的AiMessage。

支持多轮对话上下文管理，是现代 LLM 交互的主流方式（如 GPT、Gemini 等模型的聊天接口）。

示例：

ChatLanguageModel chatModel = OpenAiChatModel.builder().apiKey("your-api-key").modelName("gpt-4").build();List<ChatMessage> messages = Arrays.asList(SystemMessage.from("你是一个助手"),UserMessage.from("什么是 LangChain4j？")
);AiMessage response = chatModel.generate(messages);

3）EmbeddingModel

用于将文本转换为向量（Embedding）的接口，支持语义相似性计算、检索等场景。

示例：

EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder().apiKey("your-api-key").modelName("text-embedding-ada-002").build();Embedding embedding = embeddingModel.embed("这是一段文本");

特点：

• 贴近模型原生 API，灵活度高，可直接控制参数（如温度、最大 tokens 等）。
• 需手动处理对话状态、提示词构造等细节，适合需要深度定制交互逻辑的场景。

2.2 高级 API（High-Level API）：封装复杂功能

高级 API 在低级 API 基础上封装了更复杂的功能，旨在简化常见业务场景的开发，减少重复工作。核心接口和组件包括：

1）Assistant

模拟 “助手” 角色的高级抽象，内置对话状态管理、工具调用（Tool）、记忆（Memory）等能力。

支持通过注解定义工具方法，自动决定是否调用工具或直接回答问题。

示例：

EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder().apiKey("your-api-key").modelName("text-embedding-ada-002").build();Embedding embedding = embeddingModel.embed("这是一段文本");

2）ChatMemory

专门用于管理对话历史的组件，支持持久化（如存储到数据库）、过期策略等，无需手动维护消息列表。

示例：

ChatMemory memory = TokenWindowChatMemory.withMaxTokens(1000);
Assistant assistant = Assistant.builder().chatLanguageModel(chatModel).chatMemory(memory).build();

3）RetrievalAugmentedGeneration（RAG，检索增强生成）

整合了检索能力的生成接口，自动从知识库中获取相关信息并辅助模型生成更准确的回答。

示例：

ChatMemory memory = TokenWindowChatMemory.withMaxTokens(1000);
Assistant assistant = Assistant.builder().chatLanguageModel(chatModel).chatMemory(memory).build();

• 封装了对话记忆、工具调用、RAG 等复杂逻辑，开箱即用。
• 降低开发门槛，适合快速构建具有高级功能的 LLM 应用（如智能助手、问答系统等）。

  2.3总结

  • 低级 API：面向模型交互细节，提供基础能力，适合需要深度定制的场景。
  • 高级 API：面向业务场景，封装复杂功能，适合快速开发应用。
  两者并非互斥，实际开发中可结合使用（例如用低级 API 定制模型交互，再通过高级 API 构建业务逻辑）。

三、撸代码

3.1 低阶API

按本专栏第一章的方法创建maven工程，在看一下创建的Config类

package com.xxx.demo.config;import com.bbchat.demo.service.ChatAssistant;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class LLMConfig {@Bean(name = "qwen")public ChatModel chatModelQwen(){return OpenAiChatModel.builder().apiKey(System.getenv("aliqwen-apikey")).modelName("qwen-plus").baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1").build();}}

写一个controller验证一下低阶api的使用

package com.xxx.demo.controller;import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.model.output.TokenUsage;
import jakarta.annotation.Resource;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;@RestController
public class LowApiController {@Resource(name = "qwen")private ChatModel chatModelQwen;@GetMapping(value = "/lowapi/api01")public String api01(@RequestParam(value = "prompt", defaultValue = "你是谁") String prompt){String result = chatModelQwen.chat(prompt);System.out.println("通过langchain4j调用模型返回结果："+result);return result;}// http://localhost:9004/lowapi/api02@GetMapping(value = "/lowapi/api02")public String api02(@RequestParam(value = "prompt", defaultValue = "你是谁") String prompt){ChatResponse chatResponse = chatModelQwen.chat(UserMessage.from(prompt));String result = chatResponse.aiMessage().text();System.out.println("通过langchain4j调用模型返回结果："+result);TokenUsage tokenUsage = chatResponse.tokenUsage();System.out.println("本次调用消耗Token："+tokenUsage);result = result +"\t\n"+ tokenUsage;return result;}
}

验证结果

3.2 高阶API

先拓展一下前文中的config类

package com.xxx.demo.config;import com.bbchat.demo.service.ChatAssistant;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class LLMConfig {@Bean(name = "qwen")public ChatModel chatModelQwen(){return OpenAiChatModel.builder().apiKey(System.getenv("aliqwen-apikey")).modelName("qwen-plus").baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1").build();}@Beanpublic ChatAssistant chatAssistant(@Qualifier("qwen") ChatModel chatModelQwen){return AiServices.create(ChatAssistant.class, chatModelQwen);}
}

高阶API既然是高度封装的，那么我们写一个service层来调用他

package com.xxx.demo.service;/*
* 按照Java开发一般习惯，有接口就要有实现类* 比如接口ChatAssistant，就会有实现类ChatAssistantImpl* 现在用高阶api-AIServics不用你自己写impl实现类，交给langchain4j给你搞定** 本次配置用的是langchain4j原生整合，没有引入sprinboot，不需要接口头上配置@AiService注解标签
* */
public interface  ChatAssistant {String chat(String prompt);
}

写一个controller验证一下

package com.xxx.demo.controller;import com.bbchat.demo.service.ChatAssistant;
import jakarta.annotation.Resource;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;@RestController
public class HighApiController {@Resourceprivate ChatAssistant chatAssistant;@GetMapping(value = "/highapi/api01")public String highApi(@RequestParam(value = "prompt", defaultValue = "你是谁") String prompt){return chatAssistant.chat(prompt);}
}

验证结果

看到这里我们就需要了解一下AIServices是怎样工作的

在 LangChain4j 中，AIService 是一个高级抽象层，它的核心作用是通过注解驱动的方式，将普通的 Java 接口自动转换为具备 AI 能力的服务。简单来说，开发者只需定义一个接口并添加少量注解，AIService 就能自动完成提示词构造、模型调用、响应解析、工具调用（若有）等复杂逻辑，大幅简化 LLM 应用的开发流程。

1）AIService 的核心工作原理

AIService 的本质是动态代理：它会为开发者定义的接口生成一个实现类，在实现类中自动注入与 LLM 交互的逻辑。其工作流程可概括为：

1. 定义接口与注解：开发者定义一个接口，通过注解（如 @SystemMessage、@UserMessage、@Tool 等）声明模型的系统提示、用户输入模板、需要调用的工具等。
2. 创建 AIService 实例：通过 AIServiceFactory，结合定义的接口、ChatLanguageModel（如 GPT-4、Gemini 等）以及其他组件（如工具、记忆等），创建接口的实例。
3. 调用接口方法：开发者调用接口方法时，AIService 会自动执行以下操作：

2）关键注解与功能

AIService 的核心能力通过注解实现，常用注解包括：

• @SystemMessage：定义系统提示（告知模型角色、规则等），通常添加在接口上。​​​
• @UserMessage：定义用户输入的模板，支持通过 {{参数名}} 引用方法参数，添加在接口方法上。
• @Tool：声明方法需要调用的工具（工具类需实现 Tool 接口），模型会根据问题自动决定是否调用工具
• @MemoryId：用于多轮对话中标识会话 ID，结合 ChatMemory 组件保存对话上下文。

3）AIService 从定义到调用的完整过程：

step1. 定义接口并添加注解

import dev.langchain4j.chain.ConversationalChain;
import dev.langchain4j.service.AIService;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;@SystemMessage("你是一个翻译助手，将中文翻译成英文")
public interface TranslationService {@UserMessage("请翻译：{{chineseText}}")String translate(String chineseText);
}

step2. 创建 AIService 实例

import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AIServiceFactory;public class Main {public static void main(String[] args) {// 1. 配置底层模型（如 OpenAI 的 GPT-3.5）OpenAiChatModel chatModel = OpenAiChatModel.builder().apiKey("你的 OpenAI API 密钥").modelName("gpt-3.5-turbo").build();// 2. 通过工厂创建 AIService 实例TranslationService translationService = AIServiceFactory.create(TranslationService.class, chatModel);// 3. 调用接口方法（AIService 自动处理与模型的交互）String result = translationService.translate("你好，世界！");System.out.println(result); // 输出：Hello, World!}
}

step3. 内部处理逻辑

当调用 translate("你好，世界！") 时，AIService 会自动执行：

• 解析 @SystemMessage 和 @UserMessage，生成完整提示：​​​​​​​​​​​​​​

  系统消息：你是一个翻译助手，将中文翻译成英文  
  用户消息：请翻译：你好，世界！
  

• 调用 OpenAiChatModel 发送提示，获取模型返回的英文翻译；
• 将翻译结果作为字符串返回给调用者。

4） AIService 的核心优势

1. 简化开发：无需手动构造提示词、调用模型、解析响应，开发者只需关注业务逻辑（定义接口和注解）。
2. 整合高级功能：自动支持工具调用、对话记忆、多轮交互等，无需手动处理复杂流程。
3. 类型安全：支持将模型响应直接解析为自定义 Java 对象（通过 JSON 序列化），避免字符串解析的繁琐。

总之，AIService 是 LangChain4j 中连接业务逻辑与 AI 模型的 “桥梁”，通过注解驱动和动态代理，让开发者以最低成本实现 LLM 能力的集成。