ai4j：让 Java 开发者快速接入 AI Agent 时代

想象这样一个场景： 你是一家企业软件公司的 Java 工程师，团队有着十几年积累的 Java 后台系统，如今 AI 大潮来袭，老板要求「给现有系统加个 AI 助手」。

你调研了一圈发现：Python 生态的 LangChain 很强大，但要把整套技术栈迁移到 Python？光是微服务接口改造就要三个月。更现实的方案是：在 Java 代码里直接调大模型 API。

这就是 ai4j 解决的问题——一款面向 JDK 8+ 的 Java AI Agentic 开发套件，帮助 Java 工程师在不离开 Java 世界的前提下，快速接入 AI 能力：从最简单的模型调用，到复杂的 Agent 智能体、RAG 知识库、Coding Agent。

图1：ai4j 官方文档站（托管于 GitHub Pages）

一、项目起源：Java 工程师的 AI 焦虑

ai4j 的诞生源于一个非常具体的需求痛点：Java 工程师想要接入 AI 能力，但主流工具几乎都是 Python-first。

现有的主流选择都有明显的局限性：

• Spring AI：强依赖 Spring Boot 3.x（要求 Java 17+），很多传统企业系统仍在 JDK 8/11 运行，无法使用；
• LangChain4j：虽然支持 Java，但定位更偏向底层抽象，上手曲线较陡；
• 直接调 OpenAI SDK：需要处理每个平台的差异，DeepSeek、智谱GLM、Moonshot Kimi 等国内模型的接口各有不同，维护成本极高。

ai4j 作者（GitHub @LnYo-Cly）从 2024 年 8 月开始维护这个项目，采用了与 Spring AI 完全不同的设计哲学——不需要 Spring Boot，不需要 Java 17+，JDK 8 即可运行，这让它能够直接接入大量仍在跑 JDK 8 的传统企业系统。目前最新版本发布在 Maven Central，可通过 Maven Central 直接引入。

二、核心架构：多模块的统一 SDK 设计

ai4j 仓库实际上是一个 Maven 多模块工程，包含 9 个子模块，各司其职：

模块	职责	引入方式
ai4j	核心 SDK：统一模型调用、Tool Call、MCP、ChatMemory	Maven 必引
ai4j-agent	通用 Agent 运行时：ReAct、subagent、agent teams、memory	按需引入
ai4j-coding	Coding Agent 运行时：workspace tools、outer loop、subagent	按需引入
ai4j-cli	本地 Coding Agent CLI/TUI：一键安装 ai4j 命令	按需引入
ai4j-spring-boot-starter	Spring Boot 自动配置（Java 17+）	Spring Boot 用户
ai4j-flowgram-spring-boot-starter	FlowGram 工作流集成	按需引入
ai4j-extension-api	插件 API：开发第三方扩展工具	插件开发者
ai4j-plugin-ask-user	官方 Ask User 插件：Agent 结构化询问用户	按需引入
ai4j-bom	BOM 版本管理：统一多模块版本号	多模块项目推荐

这种模块化设计让使用者可以按需引入——如果只是需要一个统一的大模型调用层，只引入 ai4j 即可；如果要构建完整的 Coding Agent 系统，再引入 ai4j-coding + ai4j-cli。

核心调用链路非常清晰：Configuration -> AiService -> IChatService -> ChatCompletion -> ChatCompletionResponse，这是 ai4j 的「真实主线」，无论做同步/流式/Tool Call，都沿着同一条链路扩展。

三、能力全景：从模型调用到 Agentic 系统

3.1 多平台统一接入

ai4j 当前支持 10+ 平台的模型接入，包括：

• 国际主流：OpenAI（全系列，包括最新 GPT-5）、Ollama（本地开源模型）
• 国内主流：智谱 GLM、DeepSeek（深度求索）、Moonshot Kimi（月之暗面）、腾讯混元、零一万物、MiniMax、百川
• 配套服务：Jina（Rerank）、Doubao（方舟知识库重排）

接入方式极其统一——只需切换 PlatformType，同一条代码从 GPT-4 切换到 GLM-4，不需要修改业务逻辑。

3.2 完整的服务覆盖

ai4j 不仅仅支持 Chat，还覆盖了 AI 应用开发中几乎所有常见需求：

• Chat Completions：同步/流式对话，含多模态图片识别
• Responses：新版协议支持
• Embedding：文本向量化（统一接口适配所有平台）
• Rerank：语义精排，提升 RAG 召回质量
• Audio：Whisper 语音转文字
• Image：DALL-E 图片生成
• Realtime：实时语音交互

3.3 MCP（Model Context Protocol）原生支持

从 2025 年 8 月起，ai4j 开始支持 MCP 协议，这是当前 AI Agent 领域最重要的工具调用协议标准。MCP 支持 STDIO、SSE、Streamable HTTP 三种传输方式，支持 MCP Server 和 MCP Client，内置 MCP 网关和自动重连机制。更重要的是，ai4j 支持动态 MCP 数据源——可以在运行时动态注册新的 MCP 服务。

对于 Coding Agent 场景，这意味着：你的本地代码仓库、数据库、API 文档，都可以作为 MCP Server 接入 Agent 的工具集。

3.4 RAG 知识库：完整的 IngestionPipeline

ai4j 的 RAG 能力分为入库和查询两个阶段，架构设计相当专业：

入库阶段（IngestionPipeline）：完整串联 DocumentLoader -> Chunker -> MetadataEnricher -> Embedding -> VectorStore.upsert，使用 Apache Tika 处理 PDF、DOC 等文件格式，自动提取文本和元数据。

查询阶段（Retriever）：内置三种 Retriever，DenseRetriever（语义向量检索）、Bm25Retriever（传统关键词检索）、HybridRetriever（语义+关键词混合检索），融合策略支持 RRF、RSF、DBSF。Rerank 层支持 Jina、Doubao（方舟）、Ollama 等，可无缝通过 ModelReranker 接入任意支持 Rerank 的模型。

支持的向量数据库：Pinecone、Qdrant、pgvector、Milvus。内置 RagEvaluator 支持 Precision@K/Recall@K/F1@K/MRR/NDCG 指标评估，方便量化 RAG 质量。

3.5 Coding Agent：本地代码仓交互式会话

ai4j 最有特色的模块之一是 ai4j-coding + ai4j-cli，提供完整的本地 Coding Agent 能力：交互模式支持 CLI（命令行）和 TUI（终端 UI）两种方式；Coding 协议支持 chat 和 responses；Workspace Tools 让 Agent 可以读写本地文件、执行命令、搜索代码；会话管理支持 session 持久化、resume、fork、history、tree、events、replay；Subagent 与 Team 支持多个 Agent 协作完成任务；Provider Profile 可保存多个模型配置，支持 workspace 级 model override；Skill 系统支持自定义 Skill 目录。

安装方式极其简单，一条命令搞定（前提是装了 JDK 8+）：

# Linux/macOS
curl -fsSL https://lnyo-cly.github.io/ai4j/install.sh | sh

# Windows PowerShell
irm https://lnyo-cly.github.io/ai4j/install.ps1 | iex

安装脚本自动从 Maven Central 下载 jar 并生成 ai4j 命令。

四、技术细节

4.1 OkHttp 装饰器模式

ai4j 大量使用装饰器模式增强 OkHttp Client，所有 AI 服务的底层都跑在同一个 OkHttp 连接池上。这带来几个好处：连接复用，减少频繁建连的开销；统一配置代理、超时、日志拦截器；ErrorInterceptor 统一处理所有平台的错误，转换为 OpenAI 风格错误类型；SPI 机制支持自定义 Dispatcher 和 ConnectPool。

4.2 流式输出的精细控制

ai4j 的 SSE 流式处理有完整的中间件链：SseListener 支持 currStr（当前 content 文本）、currData（完整对象）、output（最终输出）。支持 Tool Call 参数的流式输出（Token-by-Token），这在实现打字机效果时非常有用。

4.3 ChatMemory：轻量多轮上下文管理

内置 InMemoryChatMemory，支持 MessageWindowChatMemoryPolicy（固定上下文窗口），可以同时给 Chat 和 Responses 协议使用。做多轮对话时，不需要手动维护 message 列表，ai4j 自动处理。

4.4 AgentFlow 平台集成

ai4j 提供了对 Dify、Coze、n8n 等工作流平台的统一接入能力（AgentFlow），可以直接调用这些平台已发布的 Agent/Workflow 端点。对于已有 Dify/Coze 流程积累的企业，这是一个低迁移成本的接入路径。

五、上手体验

非 Spring 场景（普通 Java 应用）

ai4j 最核心的价值在于：不需要任何框架，普通 Java 代码就能跑。核心流程只需 10 行代码即可完成首条 Chat 请求，从配置到拿到结果全流程不超过 5 分钟。

对于任何想要从零接入 AI 的 Java 项目来说，门槛已经足够低了——只要有 JDK 8，能用 Maven，不需要 Spring Boot，不需要 Java 17。

Spring Boot 场景

引入 ai4j-spring-boot-starter 后，通过 @Autowired AiService 注入，通过 application.yml 配置 api-key、proxy、platform 参数，体验接近 Spring 原生风格。

六、局限与争议

1. 强依赖 OkHttp：ai4j 整个通信层基于 OkHttp，没有提供其他 HTTP 客户端选项。对于已经使用 Apache HttpClient 或 Java 11+ 内置 HTTP Client 的项目，这可能造成依赖冲突。

2. Spring Boot Starter 需要 Java 17+：虽然核心 ai4j 支持 JDK 8，但 ai4j-spring-boot-starter 和 ai4j-flowgram-spring-boot-starter 要求 Spring Boot 3.x（Java 17+），这部分与传统企业场景仍有距离。

3. 国内平台支持依赖第三方中转：智谱GLM、Moonshot Kimi、DeepSeek 等国内模型在国内访问需要 API 中转服务，ai4j 本身不提供中转能力，需要用户自行解决访问问题（项目赞助商 TroveBox AI 提供了低价中转方案）。

4. Coding Agent TUI 体验依赖终端：ai4j-cli 的 TUI 模式需要终端支持 ANSI escape code，在某些 CI/CD 环境中可能无法正常使用，CLI 模式更通用。

七、行业意义

ai4j 的出现填补了一个被长期忽视的空白——Java 生态的 AI Agent 开发框架。在中国企业市场，Java 存量系统是一个天文数字，而 AI 升级浪潮正在倒逼这些系统进行 AI 改造。ai4j 的 JDK 8+ 兼容策略，让它能够直接跑在很多"不能动"的老系统上，这是它最核心的差异化价值。

从 GitHub 趋势来看，ai4j 的 Star 增长在 2025-2026 年间持续攀升，在 Java AI 赛道的细分领域（Java + Agent + MCP + RAG）中处于头部位置。相比 Spring AI 的 Spring-only 策略，ai4j 的「零框架依赖」让它具有更广泛的应用场景。

随着 MCP 协议逐渐成为 Agent 工具调用的主流标准，ai4j 对 MCP 的完整支持有望让它成为 Java 开发者接入 AI Agent 生态的首选入口。

图2：ai4j 项目作者 @LnYo-Cly（GitHub）