欢迎访问我的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. 结构化输出之一，用提示词指定输出格式

本篇概览

• 本文是《LangChain4j实战》系列的第十篇，前面的实战中，咱们和LLM对话得到的内容都是字符串，例如下面是LLM关于赤壁之战的描述

赤壁之战（208年）是东汉末年孙刘联军在长江赤壁大破曹操大军的战役，奠定三国鼎立基础。

• 而实际的业务处理时，我们需要用数据结构来保存信息，以便各类业务逻辑处理，如下所示，HistoryEvent用于记录一次历史事件，里面有主要人物、时间、事件简介等字段

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

• 这就有了一个问题：LLM返回的字符串，如何才能转为对象实例呢？实际上有多种方式实现转换，从本篇开始，咱们连续用三篇文章来详细介绍这些方式
• 如下图所示，一共有四种方式，今天目标就是红框中的方式：通过提示词要求LLM返回结构化内容
  

关于通过提示词要求LLM返回结构化内容

• 在四种方式中，提示词的最直观最容易理解，就是直接对LLM说：给我返回JSON格式，然后LLM返回的字符串就是JSON格式，咱们拿到该字符串后反序列化成对象即可，流程如下图
  
• 可见代码并不复杂，有两个重点：

1. 对话的提示词要把返回的格式和字段说清楚
2. 拿到LLM响应后自己做反序列化操作

• 该说的都说了，开始编码吧

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

• 如果您只想快速浏览完整源码，可以在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-prompt的子工程

1. langchain4j-totorials目录下新增名output-by-prompt为的文件夹
2. output-by-prompt文件夹下新增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-prompt</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-prompt/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-prompt

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，后面收到LLM响应的字符串后需要反序列化成该对象，注意静态方法fromJson就是用来做反序列化的

package com.bolingcavalry.vo;

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.util.List;

import lombok.Data;

@Data
public class HistoryEvent {
    @JsonProperty("main_characters")
    private List<String> mainCharacters;

    @JsonProperty("year")
    private String year;
    
    @JsonProperty("description")
    private String description;
    
    // 创建静态的ObjectMapper实例，避免重复创建
    private static final ObjectMapper objectMapper = new ObjectMapper();
    
    /**
     * 将JSON字符串反序列化为HistoryEvent对象
     * 
     * @param json JSON字符串
     * @return HistoryEvent对象
     * @throws IOException 如果JSON处理或映射失败
     */
    public static HistoryEvent fromJson(String json) throws IOException {
        return objectMapper.readValue(json, HistoryEvent.class);
    }
}

• 然后是配置类LangChain4jConfig，负责生成模型服务的bean

package com.bolingcavalry.config;

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

import dev.langchain4j.model.openai.OpenAiChatModel;

/**
 * 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();
    }
}

• 由于用到了高级API，这里还要定义服务接口，注意要用AiService注解修饰，这样就不用显式实例化了

package com.bolingcavalry.service;

import dev.langchain4j.service.spring.AiService;

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

• 接下来是重点了，服务类QwenService，这里面涉及到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;

import java.io.IOException;

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

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

    @Autowired
    private Assistant assistant;

    /**
     * 通过提示词range大模型返回JSON格式的内容
     * 
     * @param prompt
     * @return
     */
    public String byPrompt(String prompt) {
        String answer = assistant.byPrompt(prompt);
        logger.info("响应：" + answer);

        HistoryEvent historyEvent = null;
        // 用大模型返回的字符串直接反序列化成对象
        try {
            historyEvent = HistoryEvent.fromJson(answer);
            logger.info("反序列化后的对象：" + historyEvent);
        } catch (IOException e) {
            logger.error("反序列化失败", e);
        }

        return answer + "[from byPrompt]";
    }
}

• 最后是controller类，用于定义一个http接口来验证服务类的操作是否符合预期

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/byprompt")
    public ResponseEntity<Response> byPrompt(@RequestBody PromptRequest request) {
        ResponseEntity<Response> checkRlt = check(request);
        if (checkRlt != null) {
            return checkRlt;
        }

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

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

mvn spring-boot:run

• 用vscode的 REST Client插件发起http请求，参数如下，注意提示词prompt字段的内容，明确要求LLM返回JSON格式，并且说清楚了具体的字段

POST http://localhost:8080/api/qwen/output/byprompt
Content-Type: application/json
Accept: application/json

{
  "prompt": "给出伊阙之战的关键信息，以json格式输出，字段包括：主要人物、时间、简介，格式是{\"main_characters\":[\"\",\"\"],\"year\":2000,\"description\":\"\"}"
}

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

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Date: Tue, 30 Dec 2025 07:40:33 GMT
Connection: close

{
  "result": "{\n  \"main_characters\": [\"白起\", \"公孙喜\"],\n  \"year\": -293,\n  \"description\": \"伊阙之战是战国时期秦国与魏、韩联军之间的一场重要战役，发生于公元前293年。秦将白起率军在伊阙（今河南省洛阳市龙门一带）大败魏、韩联军，斩首二十四万，俘虏魏将公孙喜，此战极大削弱了魏、韩两国实力，为秦国东进扫清障碍，也奠定了白起作为名将的军事地位。\"\n}[from byPrompt]"
}

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

07:40:33.401 [http-nio-8080-exec-1] INFO  c.bolingcavalry.service.QwenService - 反序列化后的对象：HistoryEvent(mainCharacters=[白起, 公孙喜], year=-293, description=伊阙之战是战国时期秦国与魏、韩联军之间的一场重要战役，发生于公元前293年。秦将白起率军在伊阙（今河南省洛阳市龙门一带）大败魏、韩联军，斩首二十四万，俘虏魏将公孙喜，此战极大削弱了魏、韩两国实力，为秦国东进扫清障碍，也奠定了白起作为名将的军事地位。)

• 至此，通过提示词来得到结构化数据的方式就验证完成了，虽然简单，但也存在风险：依赖LLM的理解能力，如果对象过于复杂或提示词的描述不够仔细，就可能导致LLM输出不符合预期，接下来的文章咱们继续尝试其他方法，来对LLM输出格式做更精确的约束

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

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