在 Spring Boot 中集成 FEL 框架:从依赖配置到流式响应与 Agent 工具调用的完整实战指南
在 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-parent4.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 传递引入了五组内容:
- FIT 的 Spring 集成:
fit-spring-boot-starter(继承 FIT 框架与 Spring Boot 的桥接能力); - FEL 核心功能:
fel-core(ChatModel、EmbedModel等核心接口)、fel-model-openai-plugin(OpenAiModel实现)、fel-flow(AiFlows 流编排); - FEL 工具系统:
fel-tool-discoverer、fel-tool-executor、fel-tool-factory-repository、fel-tool-repository-simple、tool-service(工具发现、注册、执行链路的完整实现); - FIT 运行时插件:
fit-http-client-okhttp(HTTP 客户端)、fit-value-fastjson(配置值解析)、fit-message-serializer-json-jackson(JSON 序列化)。这三者是 FIT 插件加载机制要求的显式声明; - 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; - 该后置处理器监听
FitRuntimeBean 的初始化完成事件(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.OpenAiModelmodelengine.fitframework.serialization.ObjectSerializermodelengine.fel.tool.service.ToolRepositorymodelengine.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());
}
要点拆解:
- 构造
ChatOption:ChatOption.custom().model(...).stream(false).build()指定模型名并关闭流式模式; - 构造提示词:
ChatMessages.from(new HumanMessage(query))把用户输入包装为人类消息列表(ChatMessages是消息集合的工厂类,位于modelengine.fel.core.chat.support); - 取结果:
generate(...)返回Choir<ChatMessage>,通过.first().block().get()取出第一个消息——first()取首条、block()阻塞等待、get()解包Optional; - ⚠️ 不能直接返回
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())));
}
三个必须同时满足的条件:
ChatOption设置.stream(true)——由 OpenAiModel#generate 的分支逻辑可见:chatOption.stream() ? this.createChatStream(request) : this.createChatCompletion(request),只有stream(true)才会走流式接口;- 使用
JdkFlowAdapter.flowPublisherToFlux()转换——Choir本身是 JDKFlow.Publisher,适配器将其包装为 ReactorFlux; 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向量检索、DefaultVectorRetrievertopK 召回、上下文合成后交给模型回答(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是 JDKFlow.Publisher,不能直接作为Flux返回); - ✅ 设置了
produces = "text/event-stream;charset=UTF-8"; - ✅
ChatOption设置了.stream(true)(否则走普通接口,不会有流式输出)。
3. 工具无法被发现
FitableNotFoundException: No fitables. [genericableId=xxx]
- 原因:最常见的原因是使用了 Spring 的
@Component而不是 FIT 的@Component; - 解决步骤:
- ✅ 确认工具类使用 FIT 的
@Component:
import modelengine.fitframework.annotation.Component; // ← 正确
// import org.springframework.stereotype.Component; // ← 错误
@Component // ← FIT 的注解
public class MyTool { }
- ✅ 配置
fit.beans.packages扫描:
fit:
beans:
packages:
- 'com.example.tools'
- ✅ 添加
tool-maven-plugin(见本文第七节); - ✅ 执行
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 的六个关键点
- ✅ 添加
fel-spring-boot-starter依赖(自动引入 FEL 核心、FIT 运行时、工具系统与 Spring 自动配置); - ✅ 配置
fel.openai.api-key(以及api-base、模型名),密钥通过环境变量注入,避免硬编码; - ✅ 注入 FEL Bean 时添加
@SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection"); - ✅ 流式响应必须用
JdkFlowAdapter.flowPublisherToFlux()转换,并配合stream(true)与text/event-stream; - ✅
ObjectSerializer注入需要@Qualifier("json"); - ✅ 工具类必须使用 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 版)。