LangChain4j工具调用实战：博客园文章搜索实现

集成电路科普者

1. LangChain4j工具调用实战：从零实现博客园文章搜索工具

作为一名长期在AI应用开发一线的工程师，我发现很多开发者对工具调用(Tool Calling)这个关键技术存在理解偏差。今天我就通过一个实战案例——用LangChain4j+Jsoup实现博客园文章搜索工具，带大家彻底掌握工具调用的核心原理和实现细节。

工具调用本质上是一种"AI决策+本地执行"的协作模式。当用户提出"帮我查下博客园用户BNTang的最新文章"这类需求时，AI并不直接执行操作，而是分析意图后生成工具调用请求，由我们的程序实际执行网页抓取、数据处理等操作，最后将结构化结果返回给AI生成自然语言回复。这种模式完美结合了AI的理解能力和本地程序的执行能力。

2. 工具调用核心原理与架构设计

2.1 工具调用六步工作流

完整的工具调用流程可以分为六个关键阶段：

用户提问：用户向AI服务提出自然语言请求
意图分析：AI模型解析用户意图，判断是否需要调用工具
工具决策：AI确定要调用的具体工具及参数
本地执行：应用程序执行工具逻辑（如网页抓取）
结果返回：将工具执行结果（结构化数据）返回给AI
回复生成：AI基于工具结果生成最终回复

关键点：工具执行完全发生在应用侧，AI服务器只负责决策和结果处理。这种架构既保障了数据隐私，又能利用本地计算资源。

2.2 技术选型考量

在本案例中，我们选择以下技术组合：

LangChain4j：Java生态中最成熟的AI应用框架，提供简洁的工具调用API
Jsoup：轻量级HTML解析库，特别适合网页数据抓取场景
Qwen ChatModel：阿里云的通义千问模型，对工具调用支持良好

选择LangChain4j而非Python生态的LangChain，主要基于以下考虑：

Java应用的集成更简单
类型安全的API设计
与Spring生态无缝整合
更适合企业级应用部署

3. 四步实现博客园文章搜索工具

3.1 环境准备与依赖配置

首先创建Maven项目，在pom.xml中添加必要依赖：

xml复制<dependencies>
    <!-- LangChain4j 核心库 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>0.25.0</version>
    </dependency>
    
    <!-- Jsoup 网页抓取 -->
    <dependency>
        <groupId>org.jsoup</groupId>
        <artifactId>jsoup</artifactId>
        <version>1.17.2</version>
    </dependency>
    
    <!-- 根据实际使用的AI模型添加 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-qianwen</artifactId>
        <version>0.25.0</version>
    </dependency>
</dependencies>

3.2 工具类实现详解

在tools包下创建CnblogsArticleTool类，这是整个功能的核心。我们使用@Tool注解声明这是一个可被AI调用的工具：

java复制@Slf4j
public class CnblogsArticleTool {
    
    @Tool(name = "cnblogsSearch", value = """
        从博客园获取最新文章。输入可以是：
        - 博客园用户名（例如：'someUser'）
        - 完整的个人主页URL（例如：'https://www.cnblogs.com/someUser/'）
        可选择性地附加'|N'来限制结果数量，例如：'someUser|5'。
        返回包含标题、链接、日期、摘要、阅读数、评论数、推荐数的JSON数组。
        """)
    public String searchCnblogsArticles(
        @P("用户名或URL（可选地附加|限制数量）") String input) {
        
        // 参数校验与解析
        if (input == null || input.trim().isEmpty()) {
            return errorResponse("Empty input");
        }
        
        // 解析输入参数
        ParamInfo params = parseInput(input);
        
        // 构建目标URL
        String targetUrl = buildTargetUrl(params.username);
        
        // 获取并解析HTML文档
        Document doc = fetchDocumentWithRetries(targetUrl, 3, 8000);
        if (doc == null) {
            return errorResponse("Failed to fetch page");
        }
        
        // 提取文章信息
        List<ArticleInfo> articles = extractArticles(doc, params.limit);
        
        // 生成JSON响应
        return toJsonResponse(articles);
    }
    
    // 其他辅助方法...
}

3.2.1 关键实现细节

输入参数处理：
- 支持两种输入格式：用户名或完整URL
- 可选的结果数量限制（如user|5表示最多返回5条）
- 内置参数校验和默认值处理
网页抓取优化：
- 自定义User-Agent模拟浏览器访问
- 实现带重试机制的抓取逻辑（3次尝试）
- 设置合理的超时时间（8秒）
HTML解析技巧：
- 使用CSS选择器定位文章元素（.day）
- 处理置顶文章标记（[置顶]）
- 提取并清洗摘要文本（移除"阅读全文"等无关内容）
数据去重处理：
- 基于文章URL的去重检查
- 防止同一文章多次出现在结果中

3.3 工具注册与AI服务配置

创建AI服务配置类，将工具绑定到AI模型：

java复制@Configuration
public class AiServiceConfig {
    
    @Bean
    public AiCodeHelperService aiCodeHelperService(
        ChatModel chatModel, 
        CnblogsArticleTool articleTool) {
        
        return AiServices.builder(AiCodeHelperService.class)
            .chatModel(chatModel)
            .chatMemory(MessageWindowChatMemory.withMaxMessages(10))
            .tools(articleTool)
            .build();
    }
}

关键配置项说明：

ChatModel：实际使用的AI模型实例
ChatMemory：保留最近10条对话记录
tools()：注册我们的博客园文章搜索工具

3.4 测试验证与调试技巧

编写JUnit测试验证工具调用流程：

java复制@SpringBootTest
class CnblogsArticleToolTest {
    
    @Autowired
    private AiCodeHelperService aiService;
    
    @Test
    void testArticleSearch() {
        String response = aiService.chat(
            "帮我查下博客园用户BNTang的最新3篇文章");
        
        System.out.println("AI回复：\n" + response);
        
        // 验证响应包含预期内容
        assertTrue(response.contains("标题"));
        assertTrue(response.contains("阅读数"));
    }
}

调试技巧：

在工具方法内设置断点，确认是否被调用
检查AI生成的工具调用请求参数
验证网页抓取返回的原始HTML
检查最终生成的JSON数据结构

4. 高级技巧与实战经验

4.1 工具描述的最佳实践

工具描述(@Tool注解的value值)直接影响AI的调用准确性。好的描述应包含：

功能说明：清晰描述工具的用途
输入格式：明确接受的参数形式和示例
输出说明：告知AI会返回什么数据
特殊约定：如参数分隔符、默认值等

java复制@Tool(name = "cnblogsSearch", value = """
    从博客园获取最新文章。输入可以是：
    - 博客园用户名（例如：'someUser'）
    - 完整的个人主页URL（例如：'https://www.cnblogs.com/someUser/'）
    可选择性地附加'|N'来限制结果数量，例如：'someUser|5'。
    返回包含标题、链接、日期、摘要、阅读数、评论数、推荐数的JSON数组。
    """)

4.2 异常处理与健壮性设计

确保工具在各种异常情况下都能妥善处理：

网络问题：
- 实现带退避策略的重试机制
- 设置合理的超时时间
输入错误：
- 验证输入参数格式
- 提供清晰的错误信息
页面结构变化：
- 对CSS选择器结果进行空值检查
- 记录解析失败的案例

java复制private Document fetchDocumentWithRetries(String url, int maxAttempts, int timeoutMs) {
    int attempt = 0;
    while (attempt < maxAttempts) {
        try {
            return Jsoup.connect(url)
                .userAgent("Mozilla/5.0")
                .timeout(timeoutMs)
                .get();
        } catch (IOException e) {
            attempt++;
            log.warn("Attempt {} failed for {}", attempt, url);
            if (attempt < maxAttempts) {
                try {
                    Thread.sleep(1000 * attempt); // 退避等待
                } catch (InterruptedException ie) {
                    Thread.currentThread().interrupt();
                    break;
                }
            }
        }
    }
    return null;
}

4.3 性能优化建议

缓存策略：
- 对相同查询结果进行短期缓存
- 使用ETag或Last-Modified头减少数据传输
并行处理：
- 当需要抓取多个用户文章时，使用并行流或CompletableFuture
资源控制：
- 限制单次查询的最大结果数（如100条）
- 实现请求速率限制

5. 扩展应用场景

工具调用技术不限于网页抓取，还可以实现：

数据查询：
- 数据库查询工具
- API调用封装工具
文件操作：
- 本地文件读写工具
- PDF报告生成工具
系统集成：
- 执行Shell命令
- 调用企业内部API
多媒体处理：
- 图像生成与处理
- 音频转文字

例如，我们可以轻松扩展一个数据库查询工具：

java复制@Tool("查询用户信息工具")
public String queryUserInfo(
    @P("用户ID，多个ID用逗号分隔") String userIds) {
    
    List<User> users = userRepository.findByIdIn(
        Arrays.stream(userIds.split(","))
            .map(String::trim)
            .collect(Collectors.toList()));
    
    return toJson(users);
}