在 Spring Boot 中集成 FEL 框架:从依赖配置到流式响应与 Agent 工具调用的完整实战指南

原创2026-10-14 18:05:431,929 阅读
文章标签:后端人工智能AI 应用Agent 框架RAGMCP 服务MCP Clients微服务插件系统流程编排依赖注入

在 Spring Boot 中集成 FEL 框架:从依赖配置到流式响应与 Agent 工具调用的完整实战指南

本文档以官方示例 examples/fel-spring-example/README.md 为骨架,结合仓库源码与示例工程,系统讲解如何在 Spring Boot 项目中集成 FEL(FEL,Fit Ecosystem for LLM)框架。读者将掌握 fel-spring-boot-starter 的依赖配置、application.yml 的密钥与模型配置、Spring 容器中的 FEL Bean 注入方式、同步/流式模型调用、Choir 与 Reactor 的适配,以及 Agent 工具实现中"必须使用 FIT 注解"的关键约束,最终能独立搭建一个可运行的 Spring Boot + FEL 应用。

FEL 是 FIT 框架面向大模型应用提供的函数引擎,核心能力包括 ChatModel(对话模型)、EmbedModel(向量化模型)、工具调用(Agent)与流式编排(AiFlows)。在 Spring Boot 工程中,集成层面的主要挑战不在于 FEL 自身的 API,而在于两套 IoC 容器(FIT 与 Spring)的协作:FEL 的 Bean 由 FIT 运行时动态创建,需要通过自动配置桥接到 Spring 容器,才能被 @RestController 等 Spring 组件正常注入。本文围绕这一主线展开。


一、环境准备

在开始之前,先确认基础环境满足要求:

  • JDK:17 或更高版本(示例工程父 POM 中 java.version 配置为 17,见 examples/fel-spring-example/pom.xml)
  • Maven:3.6+
  • Spring Boot:3.0+(示例工程实际使用 4.0.1,父 POM 继承 spring-boot-starter-parent 4.0.1,见 examples/fel-spring-example/pom.xml)
  • FEL / FIT 版本:示例工程通过 ${fel.version} / ${fit.version} 统一管理,当前仓库版本为 3.7.0-SNAPSHOT

示例工程 fel-spring-example 是一个多模块 Maven 工程,包含 6 个子模块,从 01-model(模型调用)到 06-agent(智能体),循序渐进地覆盖了 FEL 的完整能力:

模块 主题 核心能力
01-model 模型调用 ChatModel 同步/流式调用
02-template 提示词模板 HumanMessageTemplate 变量渲染
03-memory 对话记忆 CacheMemory 多轮上下文
04-output-parser 输出解析器 JsonOutputParser 结构化输出
05-retrieval 检索增强生成 AiFlows 编排 RAG 流程
06-agent 智能体 DefaultAgent + 工具调用

各模块共享同一个父 POM 中的依赖版本与编译配置,因此集成步骤具有高度可复制性。


二、添加依赖:fel-spring-boot-starter

1. 核心依赖(必需)

在 Spring Boot 工程(建议是 Maven 多模块中的某一个子模块)的 pom.xml 中添加:

<dependency>
    <groupId>org.fitframework.fel</groupId>
    <artifactId>fel-spring-boot-starter</artifactId>
    <version>${fel.version}</version>
</dependency>

2. 这个依赖自动引入了什么

从 framework/fel/java/fel-starters/fel-spring-boot-starter/pom.xml 可以看到,fel-spring-boot-starter 传递引入了五组内容:

  1. FIT 的 Spring 集成:fit-spring-boot-starter(继承 FIT 框架与 Spring Boot 的桥接能力);
  2. FEL 核心功能:fel-core(ChatModel、EmbedModel 等核心接口)、fel-model-openai-plugin(OpenAiModel 实现)、fel-flow(AiFlows 流编排);
  3. FEL 工具系统:fel-tool-discoverer、fel-tool-executor、fel-tool-factory-repository、fel-tool-repository-simple、tool-service(工具发现、注册、执行链路的完整实现);
  4. FIT 运行时插件:fit-http-client-okhttp(HTTP 客户端)、fit-value-fastjson(配置值解析)、fit-message-serializer-json-jackson(JSON 序列化)。这三者是 FIT 插件加载机制要求的显式声明;
  5. Spring Boot 自动配置:FelSpringBootAutoConfiguration(详见下文"Bean 注入"一节)。

也就是说,只需这一个依赖,FEL 核心功能(ChatModel、EmbedModel)、FIT 框架运行时与 Spring Boot 自动配置就全部就绪。

3. 按需补充其他 Spring 依赖

  • 构建 Web 接口:spring-boot-starter-web
  • 流式响应(Flux 类型):spring-boot-starter-webflux

以 examples/fel-spring-example/01-model/pom.xml 为例,它同时声明了 spring-boot-starter-web 与 spring-boot-starter-webflux,注释明确写着"WebFlux:流式响应需要"。若你的应用只做同步调用,可以省略 webflux;若涉及 Flux 返回值,二者必须同时存在。


三、配置文件:application.yml

在 src/main/resources/application.yml 中配置 OpenAI 兼容接口的 API 信息:

fel:
  openai:
    api-base: '${api-base}'
    api-key: '${your-api-key}'

示例工程 examples/fel-spring-example/01-model/src/main/resources/application.yml 中的完整写法为:

spring:
  application:
    name: chat-model-example

fel:
  openai:
    api-base: '${api-base}'
    api-key: '${your-api-key}'
example:
  model: '${model-name}'

说明:

  • fel.openai.api-base / fel.openai.api-key 使用 ${...} 占位符引用外部环境变量(如命令行 -Dapi-base=... 或环境变量),避免把密钥硬编码进仓库;
  • example.model 是示例工程自定义的模型名配置(非 FEL 内置项),通过 @Value("${example.model}") 注入到 Controller 中,用于构造 ChatOption;
  • RAG 模块(05-retrieval)额外需要嵌入模型名,配置为 example.model.chat 与 example.model.embed 两个键,见 examples/fel-spring-example/05-retrieval/src/main/resources/application.yml;
  • Agent 模块(06-agent)还需要在 fit.beans.packages 中声明工具实现类所在包(详见第六节)。

从源码层面看,api-base 与 api-key 最终进入 OpenAiModel 的构造参数 OpenAiConfig,在发起请求时通过 StringUtils.blankIf(option.apiKey(), this.defaultApiKey) 决定使用哪个密钥:ChatOption 中未显式设置 apiKey 时,回退到全局默认 api-key(见 OpenAiModel#generate 实现,L152-L164)。


四、Bean 注入:FEL Bean 如何进入 Spring 容器

1. 自动注册机制(源码原理)

fel-spring-boot-starter 之所以能"自动将 FEL Bean 注册到 Spring 容器",核心实现位于 FelSpringBootAutoConfiguration.java:

  • 它声明了一个 BeanDefinitionRegistryPostProcessor,向 Spring 的 BeanFactory 注册 FitRuntimeDetectorBeanPostProcessor;
  • 该后置处理器监听 FitRuntime Bean 的初始化完成事件(postProcessAfterInitialization 中判断 bean instanceof FitRuntime);
  • 一旦 FIT 运行时就绪,遍历 FIT 容器(fitRuntime.root().container().all())中的全部 Bean,只将类型属于白名单的单例 Bean 通过 registerSingleton 注册进 Spring 容器;
  • 白名单(REQUIRED_BEAN_TYPE_NAMES)刻意保持最小化,避免过度注册污染 Spring 容器,仅包含 4 类:
    • modelengine.fel.community.model.openai.OpenAiModel
    • modelengine.fitframework.serialization.ObjectSerializer
    • modelengine.fel.tool.service.ToolRepository
    • modelengine.fel.tool.service.ToolExecuteService

白名单匹配采用 isAssignableFrom 的子类匹配方式,因此 OpenAiModel(同时实现 EmbedModel、ChatModel、ImageModel、RerankModel 四个接口,见 OpenAiModel.java#L79-L80)会以完整类型被注册。

2. 自动注入的 FEL Bean

由于注册发生在 FIT 运行时启动完成之后(Spring Bean 初始化阶段),IDE 在编译期无法感知这些 Bean,因此:

  • 必须添加 @SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection"),否则 IDE 会显示 "Could not autowire" 波浪线警告;
  • 该注解不影响运行,纯粹用于消除 IDE 静态检查噪音。

可以直接构造器注入的 FEL Bean 如下:

Bean 类型 说明 注入方式
OpenAiModel EmbedModel、ChatModel、ImageModel、RerankModel 的统一实现类 构造器注入
ObjectSerializer JSON 序列化器 构造器注入,必须加 @Qualifier("json")
ToolRepository 工具仓库(查询可用工具列表) 构造器注入
ToolExecuteService 工具执行服务(Agent 调用工具) 构造器注入

注入示例(摘自 ChatModelExampleController.java):

@RestController
@RequestMapping("/ai/example")
@SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")
public class ChatModelExampleController {
    private final ChatModel chatModel;

    public ChatModelExampleController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }
}

注意:ChatModel 是接口,实际注入的是 OpenAiModel 实例(因为它实现了 ChatModel 接口)。ObjectSerializer 则需要 @Qualifier("json") 指定别名,因为 FIT 容器中可能存在多个序列化器实现:

public OutputParserExampleController(ChatModel chatModel, @Qualifier("json") ObjectSerializer serializer) {
    // ...
}

(完整示例见 OutputParserExampleController.java。)


五、模型调用:同步接口实战

在 ChatModel 接口(ChatModel.java)中,模型调用只有一个方法:

Choir<ChatMessage> generate(Prompt prompt, ChatOption chatOption);

即:入参是提示词 + 调用选项,返回值是 Choir<ChatMessage> 响应式流。

同步调用的典型写法(摘自示例 ChatModelExampleController.java):

@GetMapping("/chat")
public Map<String, Object> chat(@RequestParam("query") String query) {
    ChatOption option = ChatOption.custom().model(this.modelName).stream(false).build();
    ChatMessage aiMessage =
            this.chatModel.generate(ChatMessages.from(new HumanMessage(query)), option).first().block().get();
    return Map.of("content", aiMessage.text(), "toolCalls", aiMessage.toolCalls());
}

要点拆解:

  1. 构造 ChatOption:ChatOption.custom().model(...).stream(false).build() 指定模型名并关闭流式模式;
  2. 构造提示词:ChatMessages.from(new HumanMessage(query)) 把用户输入包装为人类消息列表(ChatMessages 是消息集合的工厂类,位于 modelengine.fel.core.chat.support);
  3. 取结果:generate(...) 返回 Choir<ChatMessage>,通过 .first().block().get() 取出第一个消息——first() 取首条、block() 阻塞等待、get() 解包 Optional;
  4. ⚠️ 不能直接返回 ChatMessage 对象:Spring MVC 无法正确序列化 FEL 的内部对象,必须手动转换为 Map 等 Spring 可序列化的结构。这也是示例统一返回 Map.of("content", ..., "toolCalls", ...) 的原因。

ChatOption 核心参数

ChatOption(ChatOption.java)采用 Builder 模式构建,常用参数如下:

参数 类型 说明
model() String 调用的模型名称
stream() Boolean true 走流式接口,false 走普通接口
baseUrl() String 大模型服务端地址,缺省回退到 fel.openai.api-base
apiKey() String 模型接口密钥,缺省回退到全局 fel.openai.api-key
maxTokens() Integer 生成文本的最大长度
temperature() Double 采样温度,取值范围 0.0 - 2.0,越高越随机
topP() Double 采样率,0.0 - 1.0,与 temperature 不建议同时设置
frequencyPenalty() Double 频率惩罚,-2.0 - 2.0,正值抑制重复用词
presencePenalty() Double 存在惩罚,-2.0 - 2.0,正值鼓励谈论新主题
stop() List<String> 停止字符串列表,命中即停止生成
tools() List<ToolInfo> 模型可用的工具列表(Agent 场景)
secureConfig() SecureConfig 调用大模型服务的安全配置
extensions() Map<String, Object> 扩展信息

除 model、stream 外,其余参数均为可选项;ChatOption.custom(ChatOption value) 还可以基于已有选项复制构建(Agent 示例中即通过这种方式追加 tools)。


六、流式响应适配:Choir 与 Spring Reactor 的桥接

1. 为什么需要适配器

FEL 的流式能力基于 FIT 响应式框架的 Choir。从源码看,Choir.java 的声明是:

public interface Choir<T> extends Publisher<T>, java.util.concurrent.Flow.Publisher<T>

也就是说,Choir 同时实现了 FIT 自己的 Publisher 与 JDK 的 Flow.Publisher,但它并不是 Spring Reactor 的 org.reactivestreams.Publisher。而 Spring MVC 的流式响应(Flux)要求 Reactor 类型,所以必须借助 reactor.adapter.JdkFlowAdapter.flowPublisherToFlux() 将 JDK Flow.Publisher 转换为 Flux。

2. 流式接口实现

完整代码摘自 ChatModelExampleController.java#L64-L69:

import reactor.adapter.JdkFlowAdapter;  // ← 导入适配器
import reactor.core.publisher.Flux;

@GetMapping(value = "/chat-stream", produces = "text/event-stream;charset=UTF-8")
public Flux<Map<String, Object>> chatStream(@RequestParam("query") String query) {
    ChatOption option = ChatOption.custom().model(this.modelName).stream(true).build();
    Choir<ChatMessage> choir = this.chatModel.generate(ChatMessages.from(new HumanMessage(query)), option);
    // ⚠️ 关键:使用 JdkFlowAdapter 转换
    return JdkFlowAdapter.flowPublisherToFlux(choir.map(chatMessage -> Map.of("content", chatMessage.text())));
}

三个必须同时满足的条件:

  1. ChatOption 设置 .stream(true)——由 OpenAiModel#generate 的分支逻辑可见:chatOption.stream() ? this.createChatStream(request) : this.createChatCompletion(request),只有 stream(true) 才会走流式接口;
  2. 使用 JdkFlowAdapter.flowPublisherToFlux() 转换——Choir 本身是 JDK Flow.Publisher,适配器将其包装为 Reactor Flux;
  3. produces = "text/event-stream;charset=UTF-8"——声明接口按 SSE(Server-Sent Events)协议输出。

Choir 自身也提供了丰富的操作符(map、first、block、just 等),流式场景中可在转换前对 Choir 做变换,例如输出解析器示例中累积文本后逐片解析:

Choir<String> choir = chatModel.generate(...).map(ChatMessage::text).map(t -> {
    sb.append(t);
    return sb.toString();
}).map(text -> outputParser.parse(text).getDate());
return JdkFlowAdapter.flowPublisherToFlux(choir.map(text -> Map.of("content", text != null ? text : "")));

(完整代码见 OutputParserExampleController.java#L80-L91。)


七、工具实现(Agent):FIT 注解与 Spring 注解的边界

Agent 场景下,FEL 需要把业务方法暴露为"工具"(Tool),供模型在对话中调用。这是 Spring 集成中最容易踩坑的部分,核心规则只有一条:

⚠️ 工具实现类必须使用 FIT 的 @Component,不能使用 Spring 的 @Component

原因:工具需要被 FIT 容器扫描并注册为 Fitable,tool-maven-plugin 在构建期也通过字节码解析 FIT 注解生成 tools.json。Spring 的 @Component 不会被 FIT 容器感知,工具也就无法被发现。

错误示范会得到如下异常:

FitableNotFoundException: No fitables. [genericableId=com.example.tools.WeatherTool]

1. 工具实现示例

参考 06-agent 模块中 WeatherServiceImpl.java 的写法:

package modelengine.example.ai.chat.agent.tool;

import modelengine.fel.tool.annotation.Attribute;
import modelengine.fel.tool.annotation.Group;
import modelengine.fel.tool.annotation.ToolMethod;
import modelengine.fitframework.annotation.Component;   // ← FIT 的注解,不是 Spring 的
import modelengine.fitframework.annotation.Fitable;
import modelengine.fitframework.annotation.Property;

@Component                                     // ← 注意:modelengine.fitframework.annotation.Component
@Group(name = "example")
public class WeatherServiceImpl implements WeatherService {
    @Override
    @Fitable("default")
    @ToolMethod(name = "get_current_temperature", description = "获取指定城市的当前温度",
            extensions = {
                    @Attribute(key = "tags", value = "FIT"),
                    @Attribute(key = "tags", value = "TEST")
            })
    @Property(description = "当前温度的结果")
    public String getCurrentTemperature(String location, String unit) {
        return "26";
    }
}

关键注解说明:

  • @Component:FIT 的组件注解,将实现类注册进 FIT 容器;
  • @Group(name = "example"):FEL 工具分组注解(modelengine.fel.tool.annotation.Group),工具按组管理、按组查询;
  • @Fitable("default"):FIT 的可变实现(Fitable)标识,default 表示默认实现;
  • @ToolMethod(description = "..."):FEL 工具方法注解(modelengine.fel.tool.annotation.ToolMethod),description 会作为工具描述提供给大模型;
  • @Property(description = "..."):FIT 的参数/返回值描述注解,帮助模型理解参数含义。

接口侧(WeatherService.java)还可以在 @ToolMethod 上配置 namespace、name,并用 @Genericable 关联 FIT 的面向接口调用能力;每个参数用 @Property(description=..., required=true, defaultValue=...) 描述。

2. 工具实现类手动注册到 Spring

在 application.yml 中把工具实现类所在包加入 FIT 的 Bean 扫描范围(注意:这个配置是 FIT 的,不是 Spring 的 @ComponentScan):

fit:
  beans:
    packages:
      - 'com.example.tools'  # 工具类所在包

示例工程 06-agent/src/main/resources/application.yml 中配置的包是 modelengine.example.ai.chat.agent。

3. 添加 Maven 插件生成 tools.json

在 pom.xml 的 <build> 中加入 tool-maven-plugin,构建时自动在 target/classes 目录生成工具文件 tools.json:

<build>
    <plugins>
        <plugin>
            <groupId>org.fitframework.fel</groupId>
            <artifactId>tool-maven-plugin</artifactId>
            <executions>
                <execution>
                    <id>build-tool</id>
                    <goals>
                        <goal>build-tool</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

插件实现位于 framework/fel/java/maven-plugins/tool-maven-plugin,其中 ByteBuddyDefinitionsParser / ByteBuddyToolsParser 等解析器负责在编译期通过字节码解析 @Group、@ToolMethod、@Fitable 注解,将其序列化为标准的工具 JSON 定义。执行 mvn compile 后,tools.json 会被 ToolRepository 加载,工具即对模型可见。

4. 在 Controller 中使用 Agent

AgentExampleController.java 展示了完整用法:通过 AiFlows 编排一个 agentFlow(map → prompt → delegate(agent)),请求时从 ToolRepository 按组拉取工具列表 toolRepository.listTool("example"),绑定到 ChatOption 后交给 Agent 流执行:

public AgentExampleController(ChatModel chatModel, ToolExecuteService toolExecuteService,
        ToolRepository toolRepository, @Value("${example.model}") String modelName) {
    this.toolRepository = toolRepository;
    this.chatOption = ChatOption.custom().model(modelName).stream(false).build();
    DefaultAgent agent =
            new DefaultAgent(new ChatFlowModel(chatModel, this.chatOption), "example", toolExecuteService);
    this.agentFlow = AiFlows.<String>create()
            .map(query -> Tip.fromArray(query))
            .prompt(Prompts.human("{{0}}"))
            .delegate(agent)
            .close();
}

@GetMapping("/chat")
public Map<String, Object> chat(@RequestParam("query") String query) {
    List<ToolInfo> toolInfos = asParent(toolRepository.listTool("example"));
    ChatMessage aiMessage = this.agentFlow.converse()
            .bind(ChatOption.custom(this.chatOption).tools(toolInfos).build())
            .offer(query)
            .await();
    return Map.of("content", aiMessage.text(), "toolCalls", aiMessage.toolCalls());
}

这条调用链清晰地展示了三个自动注入 Bean 的分工:ChatModel 负责推理、ToolRepository 负责查询工具、ToolExecuteService 负责执行模型选中的工具。


八、六个示例模块速览

以下代码均可直接运行,用于验证本文档各部分内容:

  • 01-model:同步 /chat 与流式 /chat-stream 两个接口,是本文第五、六节的完整可运行版本(ChatModelExampleController.java);
  • 02-template:使用 HumanMessageTemplate 渲染 {{adjective}}、{{content}} 变量(ChatTemplateExampleController.java);
  • 03-memory:使用 CacheMemory 在每次请求前后追加用户消息与 AI 消息,实现多轮对话记忆(ChatMemoryExampleController.java);
  • 04-output-parser:JsonOutputParser.createPartial(serializer, Demo.class) 将模型输出解析为结构化 Demo 对象,并演示了流式累积解析(OutputParserExampleController.java);
  • 05-retrieval:AiFlows 编排完整的 RAG 流程——检索词改写、MemoryVectorStore 向量检索、DefaultVectorRetriever topK 召回、上下文合成后交给模型回答(RetrievalExampleController.java);
  • 06-agent:DefaultAgent + 工具调用的完整示例,工具实现见 WeatherServiceImpl.java。

每个模块的 pom.xml 都声明了 fel-spring-boot-starter 与 spring-boot-starter-web,06-agent 额外配置了 tool-maven-plugin(06-agent/pom.xml),结构与本文第二节完全对应。


九、常见问题与排查

1. IDE 显示 "Could not autowire" 警告

Could not autowire. No beans of 'ChatModel' type found.
  • 原因:FEL Bean 是运行时(FIT 容器启动后)动态注册到 Spring 容器的,IDE 编译期无法感知;
  • 解决:在类上添加 @SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection"):
@RestController
@SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")  // ← 必须添加
public class MyController {
    private final ChatModel chatModel;
    // ...
}

2. 流式响应没有输出

按检查清单逐一核对:

  • ✅ 使用了 JdkFlowAdapter.flowPublisherToFlux() 转换(Choir 是 JDK Flow.Publisher,不能直接作为 Flux 返回);
  • ✅ 设置了 produces = "text/event-stream;charset=UTF-8";
  • ✅ ChatOption 设置了 .stream(true)(否则走普通接口,不会有流式输出)。

3. 工具无法被发现

FitableNotFoundException: No fitables. [genericableId=xxx]
  • 原因:最常见的原因是使用了 Spring 的 @Component 而不是 FIT 的 @Component;
  • 解决步骤:
  1. ✅ 确认工具类使用 FIT 的 @Component:
import modelengine.fitframework.annotation.Component;  // ← 正确
// import org.springframework.stereotype.Component;    // ← 错误

@Component  // ← FIT 的注解
public class MyTool { }
  1. ✅ 配置 fit.beans.packages 扫描:
fit:
  beans:
    packages:
      - 'com.example.tools'
  1. ✅ 添加 tool-maven-plugin(见本文第七节);
  2. ✅ 执行 mvn compile 生成 tools.json。

4. ObjectSerializer 注入失败

No qualifying bean of type 'ObjectSerializer' available
  • 解决:构造器注入时添加 @Qualifier("json"):
public MyController(
    ChatModel chatModel,
    @Qualifier("json") ObjectSerializer serializer  // ← 必须添加
) {
    this.chatModel = chatModel;
    this.serializer = serializer;
}

十、总结:Spring Boot 中使用 FEL 的六个关键点

  1. ✅ 添加 fel-spring-boot-starter 依赖(自动引入 FEL 核心、FIT 运行时、工具系统与 Spring 自动配置);
  2. ✅ 配置 fel.openai.api-key(以及 api-base、模型名),密钥通过环境变量注入,避免硬编码;
  3. ✅ 注入 FEL Bean 时添加 @SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection");
  4. ✅ 流式响应必须用 JdkFlowAdapter.flowPublisherToFlux() 转换,并配合 stream(true) 与 text/event-stream;
  5. ✅ ObjectSerializer 注入需要 @Qualifier("json");
  6. ✅ 工具类必须使用 FIT 的 @Component,不能用 Spring 的,并配合 fit.beans.packages 与 tool-maven-plugin 生成 tools.json。

FEL 功能的详细使用(ChatOption 全参数、Prompt 模板、Memory、RAG、Agent 编排等)可继续查阅仓库内文档:docs/framework/fel/java/quick-start-guide/01. 模型.md(快速上手)与 docs/framework/fel/java/user-guide-book(用户指南);各能力对应的可运行示例见 examples/fel-example(纯 Java)与本仓库的 examples/fel-spring-example(Spring Boot 版)。

登录后查看全文
fit-framework