简单、强大、开箱即用的 Spring Boot 3 AI 大模型开发框架
- Java: 17+
- Maven: 3.6.3+
- Spring Boot: 3.2+
- Gitee: https://gitee.com/hongxinge/think-ai4j
- GitHub: https://github.com/hongxinge/ThinkAi4j
- 开箱即用 - 配置一行即可接入 Ollama,云模型同样 1 行配置即可使用
- 多模型支持 - 豆包、通义千问、智谱、百度、腾讯、Kimi、DeepSeek、MiniMax、OpenAI 等所有 OpenAI 兼容模型
- 自由切换 - 配置或代码中随时切换模型,无需改业务代码
- 流式输出 - 支持 Flux、SSE 多种流式格式
- 对话记忆 - 内置内存记忆,支持 Redis 持久化
- 工具调用 - @AiTool 注解即可让 AI 调用你的方法
- RAG 增强 - 文档问答、知识库检索增强生成
- Agent 框架 - 智能代理,支持多轮工具调用、长期记忆、多Agent协作
- 内置 Skill - 文件操作、HTTP请求、数据库查询、时间日期、记忆管理等5大Skill
- OpenAI 标准 - 完全兼容 OpenAI API 规范
- MIT 协议 - 完全免费,可自由商用
ThinkAi4j 采用通用兼容 + 特殊适配的设计:
- 1 个通用模块
think-ai4j-provider-openai-compat- 支持所有 OpenAI 兼容 API 的大模型 - 配置即接入 - 新增模型只需修改配置文件,无需编写代码
| 模型 | 提供商名称 | 兼容 OpenAI | 状态 |
|---|---|---|---|
| 豆包 (Doubao) | doubao |
✅ 是 | ✅ |
| 百度文心 (Qianfan) | qianfan |
✅ 是 | ✅ |
| 腾讯混元 (Hunyuan) | hunyuan |
✅ 是 | ✅ |
| Kimi (Moonshot) | moonshot |
✅ 是 | ✅ |
| 智谱 GLM | glm |
✅ 是 | ✅ |
| MiniMax | minimax |
✅ 是 | ✅ |
| DeepSeek | deepseek |
✅ 是 | ✅ |
| 通义千问 (Qwen) | qwen |
✅ 是 | ✅ |
| Ollama 本地 | ollama |
✅ 是 | ✅ |
| OpenAI GPT | openai |
✅ 是 | ✅ |
所有符合 OpenAI API 规范的模型都可通过配置接入
只需在你的 Spring Boot 项目 pom.xml 中添加:
<!-- Spring Boot Starter(自动装配) -->
<dependency>
<groupId>com.hongxinge</groupId>
<artifactId>think-ai4j-spring-boot-starter</artifactId>
<version>1.0.3</version>
</dependency>框架已内置 Spring Boot Starter,引入后自动生效,无需额外配置。Maven 会自动从中央仓库下载,零配置即可使用。1.0.2 起内部能力模块(core / provider / memory / tool / skill / rag / agent 等)随 starter 传递,无需额外引入。
git clone https://gitee.com/hongxinge/think-ai4j.git
# 或 GitHub: https://github.com/hongxinge/ThinkAi4j.git
cd think-ai4j
# 编译并安装到本地 Maven 仓库
# Windows (PowerShell)
$env:JAVA_HOME="你的JDK路径"
mvn clean install -DskipTests然后在你的项目 pom.xml 中引入依赖(与方式一相同):
<dependency>
<groupId>com.hongxinge</groupId>
<artifactId>think-ai4j-spring-boot-starter</artifactId>
<version>1.0.3</version>
</dependency>
mvn clean install会将 1.0.2 版本安装到你本地的 Maven 仓库,之后你的项目就可以正常引用了。
think:
ai:
default-provider: doubao
compat:
providers:
- name: doubao
baseUrl: https://ark.cn-beijing.volces.com/api/v3
apiKey: 你的API密钥
model: 你的模型ID
# 可同时配置多个模型
# - name: moonshot
# baseUrl: https://api.moonshot.cn/v1
# apiKey: 你的API密钥
# model: moonshot-v1-8k
# - name: glm
# baseUrl: https://open.bigmodel.cn/api/paas/v4
# apiKey: 你的API密钥
# model: glm-4
httpClient:
connectionPool:
max-idle-connections: 50
keep-alive-minutes: 5
timeout:
connect-seconds: 30
read-seconds: 60
write-seconds: 30
memory:
type: memory # memory=内存 | redis=持久化
max-messages: 20接入 Ollama 本地模型:框架没有硬编码默认 Provider,需显式配置
think.ai.compat.providers,配置一行即可接入 Ollama(本地默认端口 11434):
think:
ai:
default-provider: ollama
compat:
providers:
- name: ollama
baseUrl: http://localhost:11434/v1
model: qwen2.5:7b@Autowired
private AiChat chat;
String result = chat.ask("你好");String result = chat.system("你是Java专家").ask("如何设计单例模式?");@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> stream(@RequestParam String q) {
return chat.stream(q);
}String result = chat.provider("glm").ask("你好");think:
ai:
memory:
type: redis
max-messages: 50
ttl-minutes: 120@Autowired
private ChatMemory memory;
memory.addMessage("user-123", AiMessage.user("我叫小明"));
List<AiMessage> history = memory.getMessages("user-123");@Component
public class WeatherTool {
@AiTool("查询天气")
public String getWeather(
@ToolParam(description = "城市名称") String city
) {
return "晴天,25度";
}
}@Autowired
private RagPipeline ragPipeline;
List<Document> docs = List.of(
new Document("公司规定年假为15天"),
new Document("加班费按每小时100元计算")
);
ragPipeline.ingest(docs);
String answer = ragPipeline.query("年假有多少天?");Agent agent = new Agent("助手", "你是一个专业的助手", chat)
.addToolBean(new WeatherTool())
.addToolBean(new SearchTool());
String result = agent.execute("北京天气如何?");ChatMemory memory = new InMemoryChatMemory();
AgentLongTermMemory longTermMemory = new AgentLongTermMemory("assistant-1", memory);
// 记住关键信息
longTermMemory.rememberFact("用户姓名:张三");
longTermMemory.rememberFact("用户偏好:Java开发");
Agent agent = new Agent("助手", "你是专业助手", chat)
.longTermMemory(longTermMemory);AgentBus bus = new AgentBus();
bus.register("研究员", researcherAgent);
bus.register("写手", writerAgent);
bus.register("审核员", reviewerAgent);
// 链式执行:研究员->写手->审核员
String report = bus.chainExecute(
List.of("研究员", "写手", "审核员"),
"研究AI趋势并写报告"
);
// 并行执行
String results = bus.parallelExecute(Map.of(
"研究员", "研究技术趋势",
"写手", "写文章摘要"
));Spring Boot 环境下,给任意 Bean 标注 @AiAgent,容器启动时自动创建同名 Agent
(自动注入 AiChat,类内 @AiTool 方法自动注册为工具):
@Component
@AiAgent(name = "weatherAgent", description = "你是一个专业的天气查询助手")
public class WeatherAgent {
@AiTool("查询天气")
public String getWeather(@ToolParam(description = "城市名称") String city) {
return "晴天,25度";
}
}启动后通过 ApplicationContext 获取自动创建的 Agent:
@Autowired
private ApplicationContext context;
Agent agent = (Agent) context.getBean("thinkAi4jAgent:weatherAgent");
String result = agent.execute("北京天气如何?");引入 spring-boot-starter-actuator 后,框架自动把请求总数、错误数、耗时、
Token 消耗等指标(think.ai.requests.total / think.ai.errors.total /
think.ai.tokens.total / think.ai.request.duration)挂进 AiChat 调用链,
无需编写任何代码(4 个指标名称保持不变):
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>配合 Prometheus / Grafana 即可监控所有 AI 调用。
注:
think-ai4j-example示例项目默认未引入 actuator,需要指标采集时请按上文自行添加该依赖。
PgVectorStore 支持通过 EmbeddingProvider 自动生成向量,
写入与检索均基于真实向量语义匹配:
// embeddingProvider 为你实现的向量化接口(如接入各厂商 Embedding API)
PgVectorStore store = new PgVectorStore(jdbcTemplate, "ai_documents", 1024, embeddingProvider);
// 写入文档(自动向量化)
store.addDocuments(List.of(new Document("公司规定年假为15天")));
// 语义检索(查询文本自动向量化后余弦排序)
List<Document> hits = store.search("年假有几天", 3);未提供
EmbeddingProvider时,写入时必须由Document.setEmbedding()预置向量, 语义检索会给出明确错误提示,不会静默产生错误结果。
FileSkill fileSkill = new FileSkill("/workspace");
// 读写文件
fileSkill.writeFile("notes.txt", "重要笔记");
String content = fileSkill.readFile("notes.txt");
// 列出目录
String dirList = fileSkill.listDirectory("");HttpSkill httpSkill = new HttpSkill()
.setDefaultHeader("Authorization", "Bearer token");
// GET 请求
String response = httpSkill.httpGet("https://api.example.com/data", null);
// POST 请求
String postResult = httpSkill.httpPost(
"https://api.example.com/submit",
null,
"{\"key\": \"value\"}"
);// 使用 H2 内存数据库示例
DatabaseSkill dbSkill = new DatabaseSkill(
"jdbc:h2:mem:testdb", "sa", ""
);
// SQL 查询
String results = dbSkill.executeQuery("SELECT * FROM users");
// 获取表列表
String tables = dbSkill.listTables();
// 查看表结构
String schema = dbSkill.describeTable("users");TimeSkill timeSkill = new TimeSkill();
// 获取当前时间
String now = timeSkill.getCurrentDateTime("Asia/Shanghai");
String date = timeSkill.getCurrentDate();
String time = timeSkill.getCurrentTime();
// 格式化时间戳
String formatted = timeSkill.formatTimestamp(1700000000, "yyyy-MM-dd HH:mm:ss");MemorySkill memorySkill = new MemorySkill();
// 记住信息
memorySkill.remember("用户名", "张三");
memorySkill.remember("年龄", "25");
// 查询记忆
String name = memorySkill.recall("用户名");
// 查询所有记忆
String allMemories = memorySkill.recall(null);
// 忘记信息
memorySkill.forget("年龄");
// 清空记忆
memorySkill.clearMemory();引入 Spring Web 后,框架自动把 AiException 转换为结构化 JSON,无需编写代码:
{
"timestamp": "2026-11-10T10:49:51Z",
"status": 400,
"error": "AI_BAD_REQUEST",
"message": "Provider not found: nonexistent",
"provider": null,
"path": "/api/chat/provider"
}状态码映射:HTTP_4xx 与参数校验类异常 → 400;HTTP_5xx / STREAM_ERROR / REQUEST_ERROR / SETUP_ERROR → 502;其它 → 500。应用已有自定义 @ControllerAdvice 时框架自动让位,也可设置 think.ai.error-handler.enabled=false 关闭。
| 方法 | 说明 | 示例 |
|---|---|---|
chat.ask(q) |
同步对话 | chat.ask("你好") |
chat.system(s).ask(q) |
带系统提示词 | chat.system("你是专家").ask("问题") |
chat.provider(p).ask(q) |
指定模型 | chat.provider("glm").ask("问题") |
chat.stream(q) |
流式输出(Flux) | chat.stream("问题") |
chat.temperature(t).ask(q) |
控制创造性 | chat.temperature(0.7).ask("写诗") |
think-ai4j/
├── think-ai4j-core/ # 核心模块
├── think-ai4j-provider-openai-compat/ # 通用兼容模块(支持所有OpenAI格式模型)
├── think-ai4j-memory/ # 内存记忆
├── think-ai4j-memory-redis/ # Redis 持久化记忆
├── think-ai4j-tool/ # 工具调用
├── think-ai4j-skill/ # 内置Skill(文件、HTTP、数据库、时间、记忆)
├── think-ai4j-rag/ # RAG 检索增强
├── think-ai4j-agent/ # Agent 框架(支持长期记忆、多Agent协作)
├── think-ai4j-observability/ # 可观测性/指标采集
├── think-ai4j-store-pgvector/ # PgVector 向量存储
├── think-ai4j-spring-boot-starter/ # Spring Boot 自动配置
├── think-ai4j-example/ # 示例项目
└── think-ai4j-test/ # 测试模块(单元测试集中覆盖 core/memory/tool/skill/rag/agent/provider;starter 另含装配冒烟用例)
普通用户直接使用 Maven 依赖即可,无需克隆源码。以下适合二次开发/贡献者。
环境要求:Java 17+、Maven 3.6.3+、Spring Boot 3.2+
set JAVA_HOME=D:\JavaSdk\sdk-17
D:\maven\apache-maven-3.9.9\bin\mvn.cmd clean installcd think-ai4j-example
set JAVA_HOME=D:\JavaSdk\sdk-17
D:\maven\apache-maven-3.9.9\bin\mvn.cmd spring-boot:run然后访问:
缺陷修复
- [重要] 修复 starter 装配阻断:内部能力模块改为随 starter 传递,注册中心直接按配置创建 Provider,仅引入 starter 即可正常启动
- 修复单例 AiChat 状态串扰:链式配置改为不可变上下文快照,fluent 方法返回新实例
- 修复工具调用闭环:工具结果回传下一轮请求;Agent 在
content为 null 时不再提前中断工具循环 - 修复流式对话正常结束时误报 ERROR 日志
- 修复 4xx 业务异常被无差别重试;修复 RAG 增量灌入检索不到;修复多项 Skill 安全与资源问题
- 单元测试改为本地 Mock 服务,消除外网依赖与 824 秒耗时
新增功能
- 客户端 API 统一结构化错误响应(
AiExceptionHandler),可通过think.ai.error-handler.enabled=false关闭 think.ai.rag.enabled/think.ai.rag.top-k/think.ai.memory.enabled配置项正式生效
缺陷修复(企业级健壮性专项)
- [重要] 修复配置的模型名被覆盖的问题:此前
ask()/stream()/Agent 调用链会把 Provider 名称(如doubao)误当作模型名发送给 API,导致真实模型配置不生效。 现在ChatRequest.provider用于选择 Provider,model专用于指定模型名, 两者语义彻底分离(未指定 model 时自动使用配置的默认模型) - 修复 system() 重复堆叠:链式多次调用
system()现在是替换语义(仅保留最新一条系统提示词) - 修复 PgVector 向量存储:写入 embedding 不再为空,检索不再按文本反查;
接入
EmbeddingProvider实现真实语义检索,并增加向量维度校验与表名安全校验 - 修复流式对话不落记忆:
stream()与ask()行为一致,对话自动写入记忆 - 修复 Redis 记忆并发丢失:改用 Redis List + Lua 脚本原子追加, 高并发场景不再出现消息互相覆盖
- 修复 AgentBus.parallelExecute 假并行:改为真实并发执行,全部完成后汇总
- 修复工具调用复杂类型参数:
@AiTool方法支持 POJO / List / Map 参数自动转换 - 加固 HTTP Skill SSRF 防护:在 DNS 解析处校验实际连接 IP,消除 DNS 重绑定绕过窗口, 并补全 IPv6 内网地址拦截
- 修复测试模块包声明错误导致的
NoClassDefFoundError - 修复 HttpSkill.allowHost 传入不可变集合时的
UnsupportedOperationException
新增功能
@AiAgent注解:Spring Boot 容器自动扫描并装配 Agent- 可观测性自动装配:引入 actuator 即自动采集 AI 调用指标(请求/错误/耗时/Token)
ChatRequest.builder().provider(...):Builder 支持指定 ProviderDocument支持携带 embedding 向量
- 首个 Maven Central 发布版本