AI Services：返回类型

AI 服务方法可以返回以下类型之一：

• String —— 在这种情况下，大语言模型生成的输出会未经任何处理 / 解析就被返回。

• 任何受结构化输出支持的类型 —— 在这种情况下，AI 服务会在返回之前将大语言模型生成的输出解析为所需的类型（支持类型见“支持的类型”）。

任何类型都可以额外包装到 Result 中，以获取有关 AI 服务调用的额外元数据：

• TokenUsage - 调用 AI 服务期间使用的 Token 总数。如果 AI 服务对大语言模型进行了多次调用（例如，因为执行了工具），它将汇总所有调用的 Token 使用量。

• Sources - 特指在 RAG（检索增强生成）流程的“检索阶段”所获取到的内容集合，是 RAG 能力的核心组成部分之一，其核心作用是为 LLM 提供生成回答所需的“外部参考信息”，避免 LLM 仅依赖内部训练数据导致的信息滞后或不准确。

• tools - 指的是AI 服务调用过程中，LLM 决定触发的所有工具的完整交互记录，包含两核心部分：

• 工具调用请求（requests）：LLM 根据用户需求生成的“调用指令”，比如调用“加法工具” 时包含的工具名称（如 add）、输入参数（如 a=1、b=2）等信息，是触发工具执行的源头指令。

• 工具执行结果（results）：工具接收到调用请求后，实际运行并返回的输出数据，比如“加法工具”计算后返回的结果 3，是工具执行后的反馈信息。

• FinishReason - 用于标识大语言模型（LLM）生成最终响应时“为何停止输出” 的关键元数据，其核心作用是帮助开发者理解 LLM 的输出边界逻辑，排查潜在问题（如输出被截断）。

• 与 AI 服务与大语言模型（LLM）交互过程中，产生的非最终性的 ChatResponse 对象集合。

• 最终的 ChatResponse。

支持的类型

下面是目前 LangChain4j 支持的类型：

LangChain4j 广告

一个示例

通过声明式接口定义 AI 能力，并获取结构化结果及调用元数据，代码如下：

// 定义业务接口
interface Assistant {
    @UserMessage("为以下主题生成文章大纲：{{it}}")
    Result<List<String>> generateOutlineFor(String topic);
}

// 使用 AiServices 创建服务
Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(chatModel)
        .build();

// 发起对话
Result<List<String>> result = assistant.generateOutlineFor("Java");
// AI回复内容，即我们需要的大纲数据
List<String> outline = result.content();
// Token使用量信息
TokenUsage tokenUsage = result.tokenUsage();
// RAG检索源信息
List<Content> sources = result.sources();
// 工具调用信息
List<ToolExecution> toolExecutions = result.toolExecutions();
// 结束原因信息
FinishReason finishReason = result.finishReason();

完整示例代码如下：

package com.hxstrive.langchain4j.aiServices;

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.output.FinishReason;
import dev.langchain4j.model.output.TokenUsage;
import dev.langchain4j.rag.content.Content;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.service.Result;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.tool.ToolExecution;

import java.util.Arrays;
import java.util.List;

public class ReturnTypeDemo {
    // 推荐：将OPEN_API_KEY设置成环境变量, 避免硬编码或随着代码泄露
    // 注意，设置完环境变量记得重启IDEA，不然可能环境变量不会生效
    private static final String API_KEY = System.getenv("OPEN_API_KEY");

    // 定义业务接口
    interface Assistant {
        @UserMessage("为以下主题生成文章大纲：{{it}}")
        Result<List<String>> generateOutlineFor(String topic);
    }

    public static void main(String[] args) {
        // 创建 ChatModel 实现类（OpenAI 为例）
        ChatModel chatModel = OpenAiChatModel.builder()
                .baseUrl("https://api.xty.app/v1")
                .apiKey(API_KEY)
                .modelName("gpt-3.5-turbo")
                .temperature(0.7)
                .logRequests(true)
                .logResponses(true)
                .build();

        // 使用 AiServices 创建服务
        Assistant assistant = AiServices.builder(Assistant.class)
                .chatModel(chatModel)
                .build();

        // 发起对话
        Result<List<String>> result = assistant.generateOutlineFor("Java");

        // 获取响应内容
        List<String> outline = result.content();
        System.out.println("大纲：");
        outline.forEach(System.out::println);

        // 获取Token使用量
        TokenUsage tokenUsage = result.tokenUsage();
        System.out.println("\nToken使用量：");
        System.out.println(" 输入=" + tokenUsage.inputTokenCount());
        System.out.println(" 输出=" + tokenUsage.outputTokenCount());
        System.out.println(" 合计=" + tokenUsage.totalTokenCount());

        // 获取RAG来源
        List<Content> sources = result.sources();
        System.out.println("\nRAG 来源：");
        for(Content source : sources) {
            System.out.println(source);
        }

        // 获取工具执行结果
        List<ToolExecution> toolExecutions = result.toolExecutions();
        System.out.println("\n工具执行结果：");
        for(ToolExecution toolExecution : toolExecutions) {
            System.out.println(toolExecution);
        }

        // 获取完成原因
        FinishReason finishReason = result.finishReason();
        System.out.println("\n完成原因：" + finishReason);
    }
}

运行示例，langchain4j 会自动在用户问题后面追加“You must put every item on a separate line.”提示词，意思为“你必须把每个项目放在单独的一行。”。

输出日志如下：

16:31:58.541 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP request:
- method: POST
- url: https://api.xty.app/v1/chat/completions
- headers: [Authorization: Beare...00], [User-Agent: langchain4j-openai], [Content-Type: application/json]
- body: {
  "model" : "gpt-3.5-turbo",
  "messages" : [ {
    "role" : "user",
    "content" : "为以下主题生成文章大纲：Java\nYou must put every item on a separate line."
  } ],
  "temperature" : 0.7,
  "stream" : false
}

16:32:21.038 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], [access-control-allow-headers: *], [access-control-allow-methods: POST, GET, OPTIONS, DELETE,PUT], [access-control-allow-origin: *], [access-control-max-age: 3600], [alt-svc: h3=":443"; ma=86400], [cf-cache-status: DYNAMIC], [cf-ray: 9c80933d69a3ea2a-AMS], [content-type: application/json;charset=UTF-8], [date: Tue, 03 Feb 2026 08:32:20 GMT], [nel: {"report_to":"cf-nel","success_fraction":0.0,"max_age":604800}], [report-to: {"group":"cf-nel","max_age":604800,"endpoints":[{"url":"https://a.nel.cloudflare.com/report/v4?s=%2FDnNfpASeAehcQ8YntNiTlPSvg0ZVxp5bmQUwKmW%2BeFRVPdK3Iuq3d4TJqhmIhnZKcZMm60hHj9PkM1Tbsi%2BG3DBpbqPZnMRReD3"}]}], [server: cloudflare], [server-timing: [cfCacheStatus;desc="DYNAMIC", cfEdge;dur=7,cfOrigin;dur=21333]], [x-oneapi-request-id: 20260203163159665232688lHRA8qmd]
- body: {
    "id": "chatcmpl-oJ3LwiT0hfTQMF0W9HvDiVEsWxWKh",
    "object": "chat.completion",
    "created": 1770107525,
    "model": "gpt-3.5-turbo-0613",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "好的，下面是一个 **Java 主题文章大纲**，已确保**每一项都单独占一行**：\n\n1. Java 概述  \n1.1 Java 的起源与发展历史  \n1.2 Java 的核心设计理念（一次编写，到处运行）  \n1.3 Java 在现代软件开发中的地位  \n\n2. Java 运行环境与基础组成  \n2.1 JDK、JRE 与 JVM 的区别  \n2.2 Java 程序的执行流程  \n2.3 Java 跨平台特性的实现原理  \n\n3. Java 基础语法  \n3.1 数据类型与变量  \n3.2 运算符与表达式  \n3.3 控制流程（条件语句与循环）  \n3.4 方法定义与调用  \n\n4. 面向对象编程（OOP）  \n4.1 类与对象  \n4.2 封装、继承、多态  \n4.3 抽象类与接口  \n4.4 构造方法与方法重载  \n\n5. Java 核心类库  \n5.1 常用基础类（String、Math、System）  \n5.2 集合框架（List、Set、Map）  \n5.3 异常处理机制  \n5.4 输入输出（IO 与 NIO）  \n\n6. Java 高级特性  \n6.1 泛型机制  \n6.2 注解与反射  \n6.3 多线程与并发编程  \n6.4 Lambda 表达式与 Stream API  \n\n7. Java 应用领域  \n7.1 Web 开发（Servlet、Spring、Spring Boot）  \n7.2 企业级应用开发  \n7.3 移动开发（Android）  \n7.4 大数据与分布式系统  \n\n8. Java 性能与安全  \n8.1 内存管理与垃圾回收机制  \n8.2 常见性能优化手段  \n8.3 Java 安全模型与权限控制  \n\n9. Java 学习路径与发展前景  \n9.1 Java 初学者学习建议  \n9.2 常见学习误区  \n9.3 Java 开发者的职业发展方向  \n\n如果你需要的是**偏学术论文 / 教程 / 博客 / 面试导向**的大纲，我也可以帮你按用途再细化一版。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 29,
        "completion_tokens": 622,
        "total_tokens": 651
    },
    "system_fingerprint": "fp_b28b39ffa8"
}

大纲：
好的，下面是一个 **Java 主题文章大纲**，已确保**每一项都单独占一行**：
1. Java 概述
1.1 Java 的起源与发展历史
1.2 Java 的核心设计理念（一次编写，到处运行）
1.3 Java 在现代软件开发中的地位
2. Java 运行环境与基础组成
2.1 JDK、JRE 与 JVM 的区别
2.2 Java 程序的执行流程
2.3 Java 跨平台特性的实现原理
3. Java 基础语法
3.1 数据类型与变量
3.2 运算符与表达式
3.3 控制流程（条件语句与循环）
3.4 方法定义与调用
4. 面向对象编程（OOP）
4.1 类与对象
4.2 封装、继承、多态
4.3 抽象类与接口
4.4 构造方法与方法重载
5. Java 核心类库
5.1 常用基础类（String、Math、System）
5.2 集合框架（List、Set、Map）
5.3 异常处理机制
5.4 输入输出（IO 与 NIO）
6. Java 高级特性
6.1 泛型机制
6.2 注解与反射
6.3 多线程与并发编程
6.4 Lambda 表达式与 Stream API
7. Java 应用领域
7.1 Web 开发（Servlet、Spring、Spring Boot）
7.2 企业级应用开发
7.3 移动开发（Android）
7.4 大数据与分布式系统
8. Java 性能与安全
8.1 内存管理与垃圾回收机制
8.2 常见性能优化手段
8.3 Java 安全模型与权限控制
9. Java 学习路径与发展前景
9.1 Java 初学者学习建议
9.2 常见学习误区
9.3 Java 开发者的职业发展方向
如果你需要的是**偏学术论文 / 教程 / 博客 / 面试导向**的大纲，我也可以帮你按用途再细化一版。

Token使用量：
 输入=29
 输出=622
 合计=651

RAG 来源：

工具执行结果：

完成原因：STOP

Process finished with exit code 0

更多 LangChain4j 知识请阅读后续教程……