陈子默
b4bdc392ee
- 提供通用调度 API、Quartz JDBC Provider 与独立 Starter - 补充 MySQL、PostgreSQL、H2 建表脚本与接入校验 - 同步完善 Federation 与 Scheduler 模块说明
135 lines
4.8 KiB
Markdown
135 lines
4.8 KiB
Markdown
# Easy-Agents
|
||
|
||
Easy-Agents 是一个轻量、可扩展的 Java AI 应用开发框架，覆盖从模型调用到工具执行、MCP 集成、检索与工作流编排的完整链路。
|
||
|
||
## 主要能力
|
||
|
||
- 多模型统一接入（Chat / Embedding / Rerank / Image）
|
||
- Prompt 与消息上下文管理
|
||
- Tool 定义、执行与拦截器机制
|
||
- MCP 客户端能力（调用、拦截、缓存与管理）
|
||
- 文档读取与切分、向量存储与检索
|
||
- 工作流执行引擎（Flow）与 Easy-Agents 适配支持
|
||
- 基于 Calcite 的 SQL 编译、方言适配与流式 JDBC 查询
|
||
- 基于 Quartz JDBC JobStore 的嵌入式分布式定时调度
|
||
|
||
## 模块说明
|
||
|
||
- `easy-agents-bom`：依赖版本管理（BOM）。
|
||
- `easy-agents-core`：核心抽象与基础能力。
|
||
- `easy-agents-document`：统一文档解析能力域，当前提供 PDF、PPTX、XLSX 解析抽象与 MinerU 复用能力。
|
||
- `easy-agents-chat`：对话模型接入实现集合。
|
||
- `easy-agents-embedding`：向量化模型实现集合。
|
||
- `easy-agents-rerank`：重排模型实现集合。
|
||
- `easy-agents-image`：图像模型能力。
|
||
- `easy-agents-store`：向量存储实现。
|
||
- `easy-agents-search-engine`：检索引擎实现。
|
||
- `easy-agents-tool`：工具调用能力。
|
||
- `easy-agents-mcp`：MCP 集成。
|
||
- `easy-agents-skill`：标准 Agent Skills 包模型、安全校验、资源存储与 ZIP 双向编解码。
|
||
- `easy-agents-flow`：流程编排核心引擎。
|
||
- `easy-agents-federation-sql`：高性能 SQL 联邦查询内核与可扩展数据库 Adapter。
|
||
- `easy-agents-scheduler`：业务无关的调度 API、Quartz Provider 与独立 Spring Boot Starter。
|
||
- `easy-agents-support`：Flow 与 Easy-Agents 适配模块。
|
||
- `easy-agents-spring-boot-starter`：Spring Boot 自动配置支持。
|
||
- `easy-agents-samples`：示例工程。
|
||
|
||
## 环境要求
|
||
|
||
- JDK 17+
|
||
- Maven 3.8+
|
||
|
||
## 构建与安装
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
mvn -DskipTests clean install
|
||
```
|
||
|
||
构建完成后，相关构件会安装到本地 Maven 仓库，可供 `easyflow` 等项目直接依赖。
|
||
|
||
发布时启用 `release` profile，生成源码包和 Javadoc 包，并调用 Maven Central 发布插件：
|
||
|
||
```bash
|
||
mvn -Prelease -DskipTests deploy
|
||
```
|
||
|
||
## 快速示例
|
||
|
||
```java
|
||
public static void main(String[] args) {
|
||
OpenAIChatModel chatModel = OpenAIChatConfig.builder()
|
||
.provider("GiteeAI")
|
||
.endpoint("https://ai.gitee.com")
|
||
.requestPath("/v1/chat/completions")
|
||
.apiKey("your-api-key")
|
||
.model("Qwen3-32B")
|
||
.buildModel();
|
||
|
||
String output = chatModel.chat("如何才能更幽默?");
|
||
System.out.println(output);
|
||
}
|
||
```
|
||
|
||
## 在业务项目中引入（示例）
|
||
|
||
```xml
|
||
<dependencyManagement>
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>com.easyagents</groupId>
|
||
<artifactId>easy-agents-bom</artifactId>
|
||
<version>1.2.0-RC</version>
|
||
<type>pom</type>
|
||
<scope>import</scope>
|
||
</dependency>
|
||
</dependencies>
|
||
</dependencyManagement>
|
||
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>com.easyagents</groupId>
|
||
<artifactId>easy-agents-flow</artifactId>
|
||
</dependency>
|
||
<dependency>
|
||
<groupId>com.easyagents</groupId>
|
||
<artifactId>easy-agents-support</artifactId>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
## 嵌入式分布式调度
|
||
|
||
Spring Boot 项目可直接引入独立 Starter：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.easyagents</groupId>
|
||
<artifactId>easy-agents-scheduler-spring-boot-starter</artifactId>
|
||
</dependency>
|
||
```
|
||
|
||
引用方需要先从 `easy-agents-scheduler-quartz` 构件的 `quartz-schema/` 目录选择 MySQL、PostgreSQL 或 H2 脚本，并纳入自己的 Flyway、Liquibase 或初始化流程。Starter 不会自动创建、删除或修改 Quartz 表。
|
||
|
||
最小配置：
|
||
|
||
```yaml
|
||
easy-agents:
|
||
scheduler:
|
||
enabled: true
|
||
# 多 DataSource 时必须指定 Bean 名称
|
||
data-source-bean-name: dataSource
|
||
quartz:
|
||
scheduler-name: easyAgentsScheduler
|
||
instance-id: AUTO
|
||
clustered: true
|
||
table-prefix: QRTZ_
|
||
thread-count: 8
|
||
shutdown-wait-timeout-millis: 30000
|
||
```
|
||
|
||
业务方将 `ScheduleHandler` 注册为 Spring Bean，并通过 `ScheduleService` 创建 Cron 或一次性任务。调度触发采用至少一次语义，Handler 需要使用 `scheduleId + scheduledFireTime` 或立即触发的 `invocationId` 实现业务幂等。应用关闭超过等待上限后会向 Handler 线程发送协作式中断；长耗时 Handler 必须正确响应线程中断，忽略中断的业务代码仍可能继续占用 Quartz Worker。完整建表说明见 `easy-agents-scheduler/easy-agents-scheduler-quartz/SCHEMA.md`。
|
||
|
||
当前 Provider 固定使用 Quartz `2.5.2`，`easy-agents-bom` 已同步管理该传递依赖。若业务项目还引入了其他 BOM 或显式 Quartz 版本，接入时应执行 `mvn dependency:tree -Dincludes=org.quartz-scheduler:quartz`，确认最终解析版本仍为 `2.5.2`。
|