LangChain4j实战之十一：结构化输出之二，function call

欢迎访问我的GitHub

这里分类和汇总了欣宸的全部原创(含配套源码)：https://github.com/zq2599/blog_demos

LangChain4j实战全系列链接

1. 准备工作
2. 极速开发体验
3. 细说聊天API
4. 集成到spring-boot
5. 图像模型
6. 聊天记忆，低级API版
7. 聊天记忆，高级API版
8. 响应流式传输
9. 高级API(AI Services)实例的创建方式
10. 结构化输出之一，用提示词指定输出格式
11. 结构化输出之二，function call

本篇概览

• 和LLM对话时收到的内容是字符串，而程序中需要用结构化数据才能执行各类业务逻辑，在前文咱们体验了通过提示词来要求LLM按照JSON格式返回内容，再自己把字符串反序列化成对象实例，这种方式依赖的是提示词描述的准确性以及LLM的理解能力，在处理复杂数据结构时无法来保证准确性，因此需要寻找一种更精确控制响应字段的方式，这也是本篇的内容：function call控制返回格式，就是下图红框中的内容
  
• 另外还会介绍一个重要知识点两阶段回合，这对于function call的使用是至关重要的
• 注意，涉及function call用到的是高级API，所以本篇的实战是基于高级API的

关于function call

• 简单的说，function call就是把自定义方法传递给LangChain4j，然后LangChain4j通过此方法的返回值类型就知道了业务所需的数据结构，接下来就会生成一条对应的OpenAI-style function definition（即LLM原生的function-calling协议）并发送给LLM，这样LLM就知道按照什么格式返回了
• OpenAI-style function definitionde的内容参考如下

"functions": [{
  "name": "extractPerson",
  "description": "Extract personal information",
  "parameters": { ... }
}]

• 对于咱们开发者来说，使用function call会涉及以下关键点如下

1. 准备自定义函数，并用Tool注解去修饰，注意该函数只是用来生成OpenAI-style function definition，不会被执行
2. 创建高级API实例的时候，要调用tools方法指定自定义函数

• 简单梳理一下运行逻辑：

LLM LangChain4j 业务代码 用户 LLM LangChain4j 业务代码 用户 模型看到 functions 后决定 用 function_call 返回 JSON 输入非结构化文本 调用 AiServices/Chain，传入 POJO 类（仅用作 schema） 把 POJO 反射成 OpenAI-style function definition （仅参数 schema，无实现） 发送 prompt + functions 字段 返回 function_call 片段 {"name":"extractPerson","arguments":"{...}"} Jackson 反序列化 JSON → POJO 返回填充好的对象 展示结构化结果

• 可见和前文的提示词控制相比，function call方式会做反序列化操作，所以业务层可以直接拿到对象实例了
• 该说的都说了，咱们来编码吧

源码下载（觉得作者啰嗦的，直接在这里下载）

• 如果您只想快速浏览完整源码，可以在GitHub下载代码直接运行，地址和链接信息如下表所示(https://github.com/zq2599/blog_demos)：

名称	链接	备注
项目主页	https://github.com/zq2599/blog_demos	该项目在GitHub上的主页
git仓库地址(https)	https://github.com/zq2599/blog_demos.git	该项目源码的仓库地址，https协议
git仓库地址(ssh)	git@github.com:zq2599/blog_demos.git	该项目源码的仓库地址，ssh协议

• 这个git项目中有多个文件夹，本篇的源码在langchain4j-tutorials文件夹下，如下图红色箭头所示：
  

编码：父工程调整

• 《准备工作》中创建了整个《LangChain4j实战》系列代码的父工程，本篇实战会在父工程下新建一个子工程，所以这里要对父工程的pom.xml做少量修改

1. modules中增加一个子工程，如下图黄框所示
   

编码：新增子工程

• 新增名为output-by-function-call的子工程

1. langchain4j-totorials目录下新增名output-by-function-call为的文件夹
2. output-by-function-call文件夹下新增pom.xml，内容如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>com.bolingcavalry</groupId>
        <artifactId>langchain4j-totorials</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>

    <artifactId>output-by-function-call</artifactId>
    <packaging>jar</packaging>

    <dependencies>
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        
        <!-- Spring Boot Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- Spring Boot Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- JUnit Jupiter Engine -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- Mockito Core -->
        <dependency>
            <groupId>org.mockito</groupId>
            <artifactId>mockito-core</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- Mockito JUnit Jupiter -->
        <dependency>
            <groupId>org.mockito</groupId>
            <artifactId>mockito-junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- LangChain4j Core -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-core</artifactId>
        </dependency>
        
        <!-- LangChain4j OpenAI支持（用于通义千问的OpenAI兼容接口） -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-open-ai</artifactId>
        </dependency>

        <!-- 官方 langchain4j（包含 AiServices 等服务类） -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j</artifactId>
        </dependency>

        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-community-dashscope</artifactId>
        </dependency>

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

        <!-- 日志依赖由Spring Boot Starter自动管理，无需单独声明 -->
    </dependencies>

    <build>
        <plugins>
            <!-- Spring Boot Maven Plugin -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>3.3.5</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

3. 在langchain4j-totorials/output-by-function-call/src/main/resources新增配置文件application.properties，内容如下，主要是三个模型的配置信息，记得把your-api-key换成您自己的apikey

# Spring Boot 应用配置
server.port=8080
server.servlet.context-path=/

# LangChain4j 使用OpenAI兼容模式配置通义千问模型
# 注意：请将your-api-key替换为您实际的通义千问API密钥
langchain4j.open-ai.chat-model.api-key=your-api-key
# 通义千问模型名称
langchain4j.open-ai.chat-model.model-name=qwen3-max
# 阿里云百炼OpenAI兼容接口地址
langchain4j.open-ai.chat-model.base-url=https://dashscope.aliyuncs.com/compatible-mode/v1

# 日志配置
logging.level.root=INFO
logging.level.com.bolingcavalry=DEBUG
logging.pattern.console=%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
# 应用名称
spring.application.name=output-by-function-call

4. 新增启动类，依旧平平无奇

package com.bolingcavalry;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * Spring Boot应用程序的主类
 */
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

• 定义一个对象HistoryEvent，前面提到的自定义方法的返回值就是这个HistoryEvent

package com.bolingcavalry.vo;

import java.util.List;

import lombok.Data;

@Data
public class HistoryEvent {
    private List<String> mainCharacters;
    private int year;
    private String description;
}

• 接下来是个重点：在一个bean中准备好自定义方法createHistoryEvent，用Tool注解修饰该方法，这样LangChain4j就会通过该方法生成OpenAI-style function definition

package com.bolingcavalry.tool;

import java.util.List;
import org.springframework.stereotype.Component;
import com.bolingcavalry.vo.HistoryEvent;
import dev.langchain4j.agent.tool.Tool;

/**
 * 历史事件提取工具，用于从文本中提取历史事件信息
 */
@Component
public class HistoryEventTool {

    /**
     * 从文本中提取历史事件信息
     * 注意，可以理解为：LangChain4j会使用这个方法的签名来构建function call，而不是实际执行这个方法
     * 
     * @param mainCharacters 主要人物列表
     * @param year           发生年份
     * @param description    事件描述
     * @return 历史事件对象
     */
    @Tool("创建历史事件对象，包含主要人物、发生年份和事件描述")
    public HistoryEvent createHistoryEvent(List<String> mainCharacters, int year, String description) {
        return null;
    }
}

• 本次实战是基于高级API的，所以要准备一个自定义接口

package com.bolingcavalry.service;

import com.bolingcavalry.vo.HistoryEvent;
import dev.langchain4j.service.UserMessage;

public interface Assistant {
    /**
     * 通过提示词range大模型返回JSON格式的内容
     * 
     * @param userMessage 用户消息
     * @return 助手生成的HistoryEvent对象
     */
    HistoryEvent byFunctionCall(@UserMessage String userMessage);
}

• 然后是配置类LangChain4jConfig，注意这里有个重点：调用AiServices.builder创建高级API服务实例的时候，要调用tools方法把HistoryEventTool实例传给LangChain4j，这样在对话时LangChain4j才会把OpenAI-style function definition发给LLM

package com.bolingcavalry.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.bolingcavalry.service.Assistant;
import com.bolingcavalry.tool.HistoryEventTool;

import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;

/**
 * LangChain4j配置类
 */
@Configuration
public class LangChain4jConfig {

    @Value("${langchain4j.open-ai.chat-model.api-key}")
    private String apiKey;

    @Value("${langchain4j.open-ai.chat-model.model-name:qwen-turbo}")
    private String modelName;

    @Value("${langchain4j.open-ai.chat-model.base-url}")
    private String baseUrl;

    /**
     * 创建并配置OpenAiChatModel实例（使用通义千问的OpenAI兼容接口）
     * 
     * @return OpenAiChatModel实例
     */
    @Bean
    public OpenAiChatModel chatModel() {
        return OpenAiChatModel.builder()
                .apiKey(apiKey)
                .modelName(modelName)
                .baseUrl(baseUrl)
                .build();
    }

    @Bean
    public Assistant assistant(OpenAiChatModel chatModel, HistoryEventTool historyEventTool) {
        return AiServices.builder(Assistant.class)
                .chatModel(chatModel)
                .tools(historyEventTool)
                .build();
    }

}

• 接下来是服务类，用于执行业务逻辑，并调用高级API服务与LLM对话

package com.bolingcavalry.service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import com.bolingcavalry.vo.HistoryEvent;

/**
 * 通义千问服务类，用于与通义千问模型进行交互
 */
@Service
public class QwenService {

    private static final Logger logger = LoggerFactory.getLogger(QwenService.class);

    @Autowired
    private Assistant assistant;

    /**
     * 通过提示词range大模型返回JSON格式的内容
     * 
     * @param prompt
     * @return
     */
    public String byFunctionCall(String prompt) {
        HistoryEvent event = assistant.byFunctionCall(prompt);
        logger.info("响应：" + event);
        return event.toString() + "[from byFunctionCall]";
    }
}

• 最后是controller类，这样就能通过http调用来验证function call能力了

package com.bolingcavalry.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.bolingcavalry.service.QwenService;

import lombok.Data;

/**
 * 通义千问控制器，处理与大模型交互的HTTP请求
 */
@RestController
@RequestMapping("/api/qwen")
public class QwenController {

    private final QwenService qwenService;

    /**
     * 构造函数，通过依赖注入获取QwenService实例
     * 
     * @param qwenService QwenService实例
     */
    public QwenController(QwenService qwenService) {
        this.qwenService = qwenService;
    }

    /**
     * 提示词请求实体类
     */
    @Data
    static class PromptRequest {
        private String prompt;
        private int userId;
    }

    /**
     * 响应实体类
     */
    @Data
    static class Response {
        private String result;

        public Response(String result) {
            this.result = result;
        }
    }

    /**
     * 检查请求体是否有效
     * 
     * @param request 包含提示词的请求体
     * @return 如果有效则返回null，否则返回包含错误信息的ResponseEntity
     */
    private ResponseEntity<Response> check(PromptRequest request) {
        if (request == null || request.getPrompt() == null || request.getPrompt().trim().isEmpty()) {
            return ResponseEntity.badRequest().body(new Response("提示词不能为空"));
        }
        return null;
    }

    @PostMapping("/output/byfunctioncall")
    public ResponseEntity<Response> byPrompt(@RequestBody PromptRequest request) {
        ResponseEntity<Response> checkRlt = check(request);
        if (checkRlt != null) {
            return checkRlt;
        }

        try {
            String response = qwenService.byFunctionCall(request.getPrompt());
            return ResponseEntity.ok(new Response(response));
        } catch (Exception e) {
            // 捕获异常并返回错误信息
            return ResponseEntity.status(500).body(new Response("请求处理失败: " + e.getMessage()));
        }
    }
}

• 至此代码就全部写完了，现在把工程运行起来试试，在output-by-function-call目录下执行以下命令即可启动服务

mvn spring-boot:run

• 用vscode的 REST Client插件发起http请求，参数如下，和前文用提示词指定JSON不同，这里并没有要求LLM返回JSON格式

###  用function call实现json格式的输出
POST http://localhost:8080/api/qwen/output/byfunctioncall
Content-Type: application/json
Accept: application/json

{
  "prompt": "介绍昆阳之战"
}

• 收到响应如下，可见LLM返回的字符串确实是JSON格式，并且每个字段都符合预期

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Date: Wed, 31 Dec 2025 11:25:12 GMT
Connection: close

{
  "result": "HistoryEvent(mainCharacters=[刘秀, 王莽], year=23, description=昆阳之战是新朝末年，绿林军与新莽军队在昆阳（今河南叶县）展开的一场决定性战役。刘秀以少胜多，大败王莽军队，为东汉的建立奠定了基础。)[from byFunctionCall]"
}

• QwenService类的byFunctionCall方法中会把assistant.byFunctionCall方法返回的实例通过日志打压出来，所以检查日志，如下，对象的信息被完整打印出来，确认反序列化成功

11:25:12.546 [http-nio-8080-exec-1] INFO  c.bolingcavalry.service.QwenService - 响应：HistoryEvent(mainCharacters=[刘秀, 王莽], year=23, description=昆阳之战是新朝末年，绿林军与新莽军队在昆阳（今河南叶县）展开的一场决定性战役。刘秀以少胜多，大败王莽军队，为东汉的建立奠定了基础。)

• 至此，通过function call得到结构化数据的方式就验证完成了，通过数据结构对格式进行了严格的限制，导致得到的结果不会有偏差，而是业务直接拿来用的对象实例，其实用性和稳定性都有了提升
• 但是还有个小问题需要说明一下

高级API接口和Tool修饰的方法，有对应关系吗？

• 细心的您在看到前面代码时，可能会有个疑问：如果中有两个方法都被Tool注解修饰，那么Assistant.byFunctionCall执行时，LLM使用哪个方法的OpenAI-style function definition呢？如下图所示
  
• 实际上，LangChain4j会把createHistoryEvent和getHistoryYear的信息都以OpenAI-style function definition的形式发给LLM，然后LLM做出最终"调用决策" ：根据用户请求的上下文和意图，从候选工具列表中选择最匹配的格式
• 您可以像上图那样，在HistoryEventTool类中增加getHistoryYear方法，然后运行起来验证，看看是否还能正常得到HistoryEvent对象

极重要的知识点：两阶段汇合协议

• 回顾HistoryEventTool.createHistoryEvent方法，里面直接返回了null，然而实测的时候我们可以得到正确的响应，所以这个null的返回值并未影响业务运行，细心的您应该会有疑问：为啥不执行呢？
• 例外，createHistoryEvent方法的说明中有这么一段话：可以理解为xxxxx，如下图黄框，您可能会有疑问：什么叫"可以理解为"？到底执没执行难道还说不清楚吗？
  
• 其实，到底执没执行很容易验证，在createHistoryEvent方法中加一行日志就行了，运行的时候如果日志有打印就说明有执行
• 如果您动手加日志然后再次验证，会发现一个结果：日志会输出，代码会执行（也就是返回null），但是得到结果依旧符合预期，不会是null
• 此时您的疑惑如下吧：

1. 为啥方法明明返回了null，但是请求得到的结果依旧是有效的对象？
2. 上图黄框说的到底啥意思？明明执行了，为什么又要理解为不会执行？

• 真正的原因是：LangChain4j 在"function calling"模式下遵循的是 「两阶段回合」 协议（OpenAI / Qwen 等模型都如此）

1. 第一次请求：只带 用户消息，然后LLM 发现需要调用工具，于是返回 tool call（含 arguments），本身不产生最终回答。
2. 第二次请求：把 第一次的 tool call 结果（即createHistoryEvent返回的 null）再发回给 LLM，LLM 拿到工具输出后，才真正生成 面向用户的最终文本 / JSON

• 框架之所以必须再请求一次，是因为：

1. 第一次响应里 没有满足 prompt 要求的 JSON（只有 toolExecutionRequests），如果不继续对话，用户侧就会收到空回答
2. 模型需要 结合工具返回信息（哪怕是 null）+ 原始 prompt 约束，才能拼出符合 schema 的最终回答。

• 流程简图

用户：介绍昆阳之战（必须返回 JSON）
   │
   ▼
LLM：我需要调 createHistoryEvent 拿数据
   │
   ▼
LangChain4j：执行你的方法 → 得到 null
   │
   ▼
再次请求：把"工具结果=null"发给 LLM
   │
   ▼
LLM：收到工具结果，按 schema 拼 JSON
   │
   ▼
用户：{"mainCharacters":[...],"year":23,"description":...}

• 为了验证这个问题，可以对代码做以下修改，把LangChain4j于LLM的所有请求响应都打印出来

1. 修改properties配置文件，允许打印LangChai4j的日志
   
2. 修改配置类中的chatModel方法，加入监听，主要是增加ChatModelListener的定义，里面会在请求和响应时在控制台输出，然后OpenAiChatModel.builder方法中必须调用listeners方法绑定监听

   @Bean
    public OpenAiChatModel chatModel() {

        ChatModelListener logger = new ChatModelListener() {
            @Override
            public void onRequest(ChatModelRequestContext reqCtx) {
                // 1. 拿到 List<ChatMessage>
                List<ChatMessage> messages = reqCtx.chatRequest().messages();
                System.out.println("→ 请求: " + messages);
            }

            @Override
            public void onResponse(ChatModelResponseContext respCtx) {
                // 2. 先取 ChatModelResponse
                ChatResponse response = respCtx.chatResponse();
                // 3. 再取 AiMessage
                AiMessage aiMessage = response.aiMessage();

                // 4. 工具调用
                List<ToolExecutionRequest> tools = aiMessage.toolExecutionRequests();
                for (ToolExecutionRequest t : tools) {
                    System.out.println("← tool      : " + t.name());
                    System.out.println("← arguments : " + t.arguments()); // 原始 JSON
                }

                // 5. 纯文本
                if (aiMessage.text() != null) {
                    System.out.println("← text      : " + aiMessage.text());
                }
            }

            @Override
            public void onError(ChatModelErrorContext errorCtx) {
                errorCtx.error().printStackTrace();
            }
        };

        return OpenAiChatModel.builder()
                .apiKey(apiKey)
                .modelName(modelName)
                .baseUrl(baseUrl)
                .listeners(List.of(logger))
                .build();
    }

• 改完后重新运行，可以看到日志如下，确实有两次请求，并且第一次LLM的响应中没有text，而第二次的却有了text，而且是JSON格式的，这就是我们获得的正真响应

22:21:14.781 [http-nio-8080-exec-1] INFO  o.a.c.c.C.[Tomcat].[localhost].[/] - Initializing Spring DispatcherServlet 'dispatcherServlet'
22:21:14.782 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Initializing Servlet 'dispatcherServlet'
22:21:14.783 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Completed initialization in 1 ms
→ 请求: [UserMessage { name = null, contents = [TextContent { text = "介绍昆阳之战
You must answer strictly in the following JSON format: {
"mainCharacters": (type: array of string),
"year": (type: integer),
"description": (type: string)
}" }], attributes = {} }]
← tool      : createHistoryEvent
← arguments : {"arg0": ["刘秀", "王莽"], "arg1": 23, "arg2": "昆阳之战是新朝末年绿林军与新莽军队之间的一场重要战役，刘秀在此战中以少胜多，大败王莽军队，为东汉的建立奠定了基础。"}


→ 请求: [UserMessage { name = null, contents = [TextContent { text = "介绍昆阳之战
You must answer strictly in the following JSON format: {
"mainCharacters": (type: array of string),
"year": (type: integer),
"description": (type: string)
}" }], attributes = {} }, AiMessage { text = null, thinking = null, toolExecutionRequests = [ToolExecutionRequest { id = "call_8527d0c09cc641778830e1c1", name = "createHistoryEvent", arguments = "{"arg0": ["刘秀", "王莽"], "arg1": 23, "arg2": "昆阳之战是新朝末年绿林军与新莽军队之间的一场重要战役，刘秀在此战中以少胜多，大败王莽军队，为东汉的建立奠定了基础。"}" }], attributes = {} }, ToolExecutionResultMessage { id = "call_8527d0c09cc641778830e1c1" toolName = "createHistoryEvent" text = "null" }]
← text      : {
  "mainCharacters": ["刘秀", "王莽"],
  "year": 23,
  "description": "昆阳之战是新朝末年绿林军与新莽军队之间的一场重要战役，刘秀在此战中以少胜多，大败王莽军队，为东汉的建立奠定了基础。"
}
22:21:23.441 [http-nio-8080-exec-1] INFO  c.bolingcavalry.service.QwenService - 响应：HistoryEvent(mainCharacters=[刘秀, 王莽], year=23, description=昆阳之战是新朝末年绿林军与新莽军队之间的一场重要战役，刘秀在此战中以少胜多，大败王莽军队，为东汉的建立奠定了基础。)

• 后面的文章还会涉及到function call，所以理解两阶段回合协议是非常重要的

• 至此，通过function call获得结构化输出的方式咱们就学习完了，您已经掌握了两种方法，可以在简单和准确之间做出选择，还剩一种方式咱们也要学习，就是下图红框中的JSON模式
  

你不孤单，欣宸原创一路相伴

1. Java系列
2. Spring系列
3. Docker系列
4. kubernetes系列
5. 数据库+中间件系列
6. DevOps系列