LangChain4J 1.0 全面教程：核心功能详解与实战代码示例

2025年最新版LangChain4J彻底革新Java AI开发：简洁的注解驱动设计、强大的函数调用能力、生产级RAG支持，让大模型集成从未如此简单。

LangChain4J是当前Java生态中最成熟的AI应用开发框架，其1.0版本（2025年6月发布）标志着API的全面稳定。本文将基于1.0.1版本详解核心功能与注解，并提供可直接运行的代码示例。

一、LangChain4J 1.0 新特性速览

命名优化与API简化
- ChatLanguageModel → ChatModel
- StreamingChatLanguageModel → StreamingChatModel
- 流式/非流式API统一配置，减少冗余代码
java 复制代码
```
// 新版API示例  
ChatModel model = OpenAiChatModel.builder()  
    .modelName("gpt-4o")  
    .apiKey(System.getenv("OPENAI_API_KEY"))  
    .build();  
```

官方OpenAI SDK集成

告别自定义HTTP客户端，直接使用官方SDK提升稳定性：

java 复制代码

OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder()  
    .modelName(ChatModel.GPT_4O)  
    .apiKey("sk-xxx")  
    .build();

增强的数据库支持
- Neo4j图数据库（GraphRAG应用）
- MongoDB Atlas向量存储
- Google Cloud SQL/AlloyDB集成

二、核心注解详解与代码实战

1. 角色定义：`@SystemMessage`

控制AI的行为边界，实现领域专注：

java 复制代码

@AiService  
public interface LegalAssistant {  
    @SystemMessage("你是一位中国法律顾问，仅回答法律相关问题。非法律问题回复：'抱歉，我只能回答法律问题。'")  
    @UserMessage("解答：{{question}}")  
    String answer(@V("question") String question);  
}

效果测试：

java 复制代码

legalAssistant.answer("什么是著作权？");  
// 输出：著作权是指作者对其创作的文学、艺术...  

legalAssistant.answer("如何做红烧肉？");  
// 输出：抱歉，我只能回答法律问题。

2. 函数调用：`@Tool`

赋予大模型调用外部方法的能力：

java 复制代码

@Component  
public class CalculatorTools {  
    @Tool("计算两个数的和")  
    double add(  
        @ToolMemoryId int userId,  // 会话隔离  
        @P("加数1") double a,  
        @P("加数2") double b  
    ) {  
        return a + b;  
    }  
}  

// 服务层集成工具  
@AiService(tools = "calculatorTools")  
public interface MathAssistant {  
    String chat(@MemoryId int userId, @UserMessage String msg);  
}

调用流程：

复制代码

用户提问 → AI生成工具调用请求 → 执行工具方法 → AI解析结果 → 返回自然语言响应

3. 结构化输出：`@Description`

从文本中精准提取POJO对象字段：

java 复制代码

public class Recipe {  
    @Description("简短标题，最多3个词")  
    private String title;  

    @Description("烹饪步骤列表，每步不超过10字")  
    private List<String> steps;  
}  

interface RecipeExtractor {  
    @UserMessage("从文本提取菜谱：{{it}}")  
    Recipe extract(String text);  
}

优势：解决大模型自由文本输出难以解析的问题

4. 复杂提示工程：`@StructuredPrompt`

组合多变量生成专业提示词：

java 复制代码

@Data  
@StructuredPrompt("根据中国{{area}}法律，分析案件：{{case}}")  
class LegalPrompt {  
    private String area;  
    private String case;  
}  

interface Lawyer {  
    String analyze(LegalPrompt prompt);  
}

三、生产级RAG实战：从数据清洗到问答

1. 自定义文档清洗器（去除HTML标签）

java 复制代码

public class HtmlCleaner implements DocumentTransformer {  
    @Override  
    public Document transform(Document doc) {  
        String cleanText = doc.text().replaceAll("<[^>]+>", "");  
        return Document.from(cleanText);  
    }  
}  

// 使用示例  
Document dirtyDoc = Document.from("<html><body><p>有效<b>内容</b></p></body>");  
Document cleanDoc = new HtmlCleaner().transform(dirtyDoc); // "有效内容"

2. 智能文本分割（保留语义边界）

java 复制代码

Tokenizer tokenizer = new HuggingFaceTokenizer();  
DocumentSplitter splitter = new DocumentBySentenceSplitter(200, 10, tokenizer);  

List<TextSegment> segments = splitter.split(cleanDoc);

关键参数：

maxSegmentSize：每段最大token数（200）
overlap：段间重叠token数（10）

3. 检索增强生成全流程

java 复制代码

// 1. 存储向量  
EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>();  
store.addAll(embeddingModel, segments);  

// 2. 构建RAG链  
Retriever<TextSegment> retriever = EmbeddingStoreRetriever.from(store, embeddingModel);  
ChatModel chatModel = OpenAiChatModel.withApiKey("sk-xxx");  

Assistant assistant = AiAssistant.builder()  
    .chatModel(chatModel)  
    .retriever(retriever)  
    .build();  

// 3. 提问获取增强回答  
String answer = assistant.chat("劳动法规定加班费如何计算？");

四、避坑指南：1.0 版本升级关键点

破坏性变更处理

diff 复制代码

// 旧代码  
- ChatLanguageModel model = ...  
// 新代码  
+ ChatModel model = ...

流式API方法重命名
- onNext() → onPartialResponse()
- onComplete() → onCompleteResponse()

依赖管理最佳实践
使用BOM统一版本：

xml 复制代码

<dependencyManagement>  
    <dependencies>  
        <dependency>  
            <groupId>dev.langchain4j</groupId>  
            <artifactId>langchain4j-bom</artifactId>  
            <version>1.0.1</version>  
            <type>pom</type>  
        </dependency>  
    </dependencies>  
</dependencyManagement>

五、总结：为什么选择LangChain4J？

Java原生支持：强类型注解驱动开发，无缝整合Spring生态
企业级特性：生产验证的RAG流程、多数据库向量存储支持
极简代码：10行实现法律顾问、数学助手等专业AI应用
版本稳定：1.0+版本API冻结，适合长期项目

最佳实践提示：对中文场景，建议扩展中文NLP工具（如HanLP）优化文本分割效果。

完整代码示例 ：

访问 LangChain4J官方示例库获取最新案例。

LangChain4J 1.0 全面教程：核心功能详解与实战代码示例

LangChain4J 1.0 全面教程：核心功能详解与实战代码示例

一、LangChain4J 1.0 新特性速览

二、核心注解详解与代码实战

1. 角色定义：@SystemMessage

2. 函数调用：@Tool

3. 结构化输出：@Description

4. 复杂提示工程：@StructuredPrompt

三、生产级RAG实战：从数据清洗到问答

1. 自定义文档清洗器（去除HTML标签）

2. 智能文本分割（保留语义边界）

3. 检索增强生成全流程

四、避坑指南：1.0 版本升级关键点

五、总结：为什么选择LangChain4J？

1. 角色定义：`@SystemMessage`

2. 函数调用：`@Tool`

3. 结构化输出：`@Description`

4. 复杂提示工程：`@StructuredPrompt`