Skip to content

LnYo-Cly/ai4j

Repository files navigation

ai4j banner

Maven Central Docs License JDK 8+ Agentic Enabled MCP Supported RAG Built-in CLI TUI ACP Built-in

ai4j

一款面向 JDK8+ 的 Java AI Agentic 开发套件,既提供统一的大模型调用与常用 AI 基座能力,也提供更完善的智能体式 Agent 开发能力。
覆盖多平台模型接入、统一输入输出、Tool Call、MCP、RAG、统一 VectorStore、ChatMemory、Agent Runtime、Coding Agent、CLI / TUI / ACP、FlowGram 集成,以及 Dify / Coze / n8n 等已发布 AgentFlow 端点接入能力,帮助 Java 应用从基础模型接入扩展到更完整的 agentic 应用开发。

当前仓库已经演进为多模块 SDK,除核心 ai4j 外,还提供 ai4j-agentai4j-codingai4j-cliai4j-spring-boot-starterai4j-flowgram-spring-boot-starterai4j-bom。如果只需要基础大模型调用,优先引入 ai4j;如果需要 Agent、Coding Agent、CLI / ACP、Spring Boot 或 FlowGram 集成,再按模块引入对应能力。

适用场景与常见方案对比

方案 Java 基线 应用形态 能力侧重点
ai4j JDK8+ 普通 Java / Spring 统一大模型接入、Tool / MCP / RAG、Agent Runtime、Coding Agent、CLI / TUI / ACP
Spring AI Java 17+ Spring Boot 3.x Spring 原生 AI 集成、模型访问、Tool Calling、MCP、RAG
Spring AI Alibaba Java 17+ Spring Boot 3.x Spring 与阿里云 AI 生态整合
LangChain4j Java 17+ 普通 Java / Spring / Quarkus 等 通用 Java LLM / Agent / RAG 抽象、AI Services、多框架集成

支持的平台

  • OpenAi(包含与OpenAi请求格式相同/兼容的平台)
  • Jina(Rerank / Jina-compatible Rerank)
  • Zhipu(智谱)
  • DeepSeek(深度求索)
  • Moonshot(月之暗面)
  • Hunyuan(腾讯混元)
  • Lingyi(零一万物)
  • Ollama
  • MiniMax
  • Baichuan

支持的服务

  • Chat Completions(流式与非流式)
  • Responses
  • Embedding
  • Rerank
  • Audio
  • Image
  • Realtime

已适配的 AgentFlow / 工作流平台

  • Dify(Chat / Workflow)
  • Coze(Chat / Workflow)
  • n8n(Webhook Workflow)

特性

  • 支持MCP服务,内置MCP网关,支持建立动态MCP数据源。
  • 支持Spring以及普通Java应用、支持Java 8以上的应用
  • 多平台、多服务
  • 提供 AgentFlow 能力,可直接接入 Dify、Coze、n8n 等已发布 Agent / Workflow 端点
  • 提供 ai4j-agent 通用 Agent 运行时,支持 ReAct、subagent、agent teams、memory、trace 与 tool loop
  • 内置 Coding Agent CLI / TUI,支持本地代码仓交互式会话、provider profile、workspace model override、session/process 管理
  • 提供 ai4j-coding Coding Agent 运行时,支持 workspace tools、outer loop、checkpoint compaction、subagent 与 team 协作
  • 提供 ai4j-flowgram-spring-boot-starter,便于在 Spring Boot 中接入 FlowGram 工作流与 trace
  • 提供 ai4j-bom,便于多模块项目统一版本管理
  • 统一的输入输出
  • 统一的错误处理
  • 支持SPI机制,可自定义Dispatcher和ConnectPool
  • 支持服务增强,例如增加websearch服务
  • 支持流式输出。支持函数调用参数流式输出.
  • 简洁的多模态调用方式,例如vision识图
  • 轻松使用Tool Calls
  • 支持多个函数同时调用(智谱不支持)
  • 支持stream_options,流式输出直接获取统计token usage
  • 内置 ChatMemory,支持基础多轮会话上下文维护,可同时适配 Chat / Responses
  • 支持RAG,内置统一 VectorStore 抽象,当前支持: Pinecone、Qdrant、pgvector、Milvus
  • 内置 IngestionPipeline,统一串联 DocumentLoader -> Chunker -> MetadataEnricher -> Embedding -> VectorStore.upsert
  • 内置 DenseRetrieverBm25RetrieverHybridRetriever,可按语义检索、关键词检索、混合检索方式组合知识库召回
  • HybridRetriever 支持 RrfFusionStrategyRsfFusionStrategyDbsfFusionStrategy,默认使用 RRF;融合排序与 Reranker 语义精排解耦
  • 支持统一 IRerankService,当前可接 Jina / Jina-compatible、Ollama、Doubao(方舟知识库重排);可通过 ModelReranker 无缝接入 RAG 精排
  • RAG 运行时可直接拿到 rank/retrieverSource/retrievalScore/fusionScore/rerankScore/scoreDetails/trace,并可通过 RagEvaluator 计算 Precision@K/Recall@K/F1@K/MRR/NDCG
  • 使用Tika读取文件
  • Token统计TikTokensUtil.java

官方文档站

  • 在线文档站:https://lnyo-cly.github.io/ai4j/
  • 文档站源码位于 docs-site/
  • 适合直接使用者的入口:docs-site/docs/coding-agent/
  • 适合 SDK 接入的入口:docs-site/docs/getting-started/docs-site/docs/ai-basics/
  • 适合协议与扩展集成的入口:docs-site/docs/mcp/docs-site/docs/agent/

推荐阅读顺序:

  • docs-site/docs/intro.md
  • docs-site/docs/getting-started/installation.md
  • docs-site/docs/coding-agent/overview.md
  • docs-site/docs/ai-basics/overview.md
  • docs-site/docs/mcp/overview.md

基础会话上下文新增入口:

  • docs-site/docs/ai-basics/chat/chat-memory.md
  • docs-site/docs/ai-basics/services/rerank.md
  • docs-site/docs/ai-basics/rag/ingestion-pipeline.md

本地运行文档站:

cd .\docs-site
npm install
npm run start
cd .\docs-site
npm run build

更新日志

  • [2026-03-28] 修复 Coding Agent ACP 流式场景下纯空白 chunk 被 runtime 过滤的问题;ACP 保持透传原始 delta,不做 chunk 聚合;补充 CLI/文档中的流式语义说明
  • [2026-03-26] 新增 Coding Agent CLI / TUI 文档与能力说明,覆盖交互式会话、provider profile、workspace model override、命令参考与配置样例
  • [2025-08-19] 修复传递有验证参数的sse-url时,key丢失问题
  • [2025-08-08] OpenAi: max_tokens字段现已废弃,推荐使用max_completion_tokens(GPT-5已经不支持max_tokens字段)
  • [2025-08-08] 支持MCP协议,支持STDIO,SSE,Streamable HTTP; 支持MCP Server与MCP Client; 支持MCP网关; 支持自定义MCP数据源; 支持MCP自动重连
  • [2025-06-23] 修复ollama的流式错误;修复ollama函数调用的错误;修复moonshot请求时错误;修复ollama embedding错误;修复思考无内容;修复日志冲突;新增自定义异常方法。
  • [2025-02-28] 新增对Ollama平台的embedding接口的支持。
  • [2025-02-17] 新增对DeepSeek平台推理模型的适配。
  • [2025-02-12] 为Ollama平台添加Authorization
  • [2025-02-11] 实现自定义的Jackson序列化,解决OpenAi已经无法通过Json String来直接实现多模态接口的问题。
  • [2024-12-12] 使用装饰器模式增强Chat服务,支持SearXNG网络搜索增强,无需模型支持内置搜索以及function_call。
  • [2024-10-17] 支持SPI机制,可自定义Dispatcher和ConnectPool。新增百川Baichuan平台Chat接口支持。
  • [2024-10-16] 增加MiniMax平台Chat接口对接
  • [2024-10-15] 增加realtime服务
  • [2024-10-12] 修复早期遗忘的小bug; 修复错误拦截器导致的音频字节流异常错误问题; 增加OpenAi Audio服务。
  • [2024-10-10] 增强对SSE输出的获取,新加入currData属性,记录当前消息的整个对象。而原先的currStr为当前消息的content内容,保留不变。
  • [2024-09-26] 修复有关Pinecone向量数据库的一些问题。发布0.6.3版本
  • [2024-09-20] 增加对Ollama平台的支持,并修复一些bug。发布0.6.2版本
  • [2024-09-19] 增加错误处理链,统一处理为openai错误类型; 修复部分情况下URL拼接问题,修复拦截器中response重复调用而导致的关闭问题。发布0.5.3版本
  • [2024-09-12] 修复上个问题OpenAi参数导致错误的遗漏,发布0.5.2版本
  • [2024-09-12] 修复SpringBoot 2.6以下导致OkHttp变为3.14版本的报错问题;修复OpenAi参数parallel_tool_calls在tools为null时的异常问题。发布0.5.1版本。
  • [2024-09-09] 新增零一万物大模型支持、发布0.5.0版本。
  • [2024-09-02] 新增腾讯混元Hunyuan平台支持(注意:所需apiKey 属于SecretId与SecretKey的拼接,格式为 {SecretId}.{SecretKey}),发布0.4.0版本。
  • [2024-08-30] 新增对Moonshot(Kimi)平台的支持,增加OkHttpUtil.java实现忽略SSL证书的校验。
  • [2024-08-29] 新增对DeepSeek平台的支持、新增stream_options可以直接统计usage、新增错误拦截器ErrorInterceptor.java、发布0.3.0版本。
  • [2024-08-29] 修改SseListener以兼容智谱函数调用。
  • [2024-08-28] 添加token统计、添加智谱AI的Chat服务、优化函数调用可以支持多轮多函数。
  • [2024-08-17] 增强SseListener监听器功能。发布0.2.0版本。

教程文档

Coding Agent CLI / TUI

AI4J 目前已经内置 ai4j-cli,可以直接作为本地 coding agent 使用,支持:

  • one-shot 与持续会话
  • CLI / TUI 两种交互模式
  • provider profile 持久化
  • workspace 级 model override
  • subagent 与 agent teams 协作
  • session 持久化、resume、fork、history、tree、events、replay
  • team board、team messages、team resume 等协作观测能力
  • process 管理与日志查看

安装

curl -fsSL https://lnyo-cly.github.io/ai4j/install.sh | sh
irm https://lnyo-cly.github.io/ai4j/install.ps1 | iex

安装脚本会从 Maven Central 下载 ai4j-cli 并生成 ai4j 命令,前提是本机已经安装 Java 8+。

one-shot 示例

ai4j code `
  --provider openai `
  --protocol responses `
  --model gpt-5-mini `
  --prompt "Read README and summarize the project structure"

交互式 CLI 示例

ai4j code `
  --provider zhipu `
  --protocol chat `
  --model glm-4.7 `
  --base-url https://open.bigmodel.cn/api/coding/paas/v4 `
  --workspace .

TUI 示例

ai4j tui `
  --provider zhipu `
  --protocol chat `
  --model glm-4.7 `
  --base-url https://open.bigmodel.cn/api/coding/paas/v4 `
  --workspace .

ACP 示例

ai4j acp `
  --provider openai `
  --protocol responses `
  --model gpt-5-mini `
  --workspace .

源码构建(可选)

mvn -pl ai4j-cli -am -DskipTests package

产物示例:

ai4j-cli/target/ai4j-cli-<version>-jar-with-dependencies.jar

如果你需要直接运行本地构建产物:

java -jar .\ai4j-cli\target\ai4j-cli-<version>-jar-with-dependencies.jar code --help

当前协议规则

当前 CLI 对用户只暴露两种协议:

  • chat
  • responses

如果省略 --protocol,会按 provider/baseUrl 在本地推导默认值:

  • openai + 官方 OpenAI host -> responses
  • openai + 自定义兼容 baseUrl -> chat
  • doubao / dashscope -> responses
  • 其他 provider -> chat

注意:

  • 不再对用户暴露 auto
  • 旧配置中的 auto 会在读取时自动归一化为显式协议

provider profile 配置位置

  • 全局配置:~/.ai4j/providers.json
  • 工作区配置:<workspace>/.ai4j/workspace.json

推荐工作流:

  • 全局保存长期可复用 profile
  • workspace 只引用当前 activeProfile
  • 临时切模型时使用 workspace 的 modelOverride

workspace.json 也可以显式挂载额外 skill 目录:

{
  "activeProfile": "openai-main",
  "modelOverride": "gpt-5-mini",
  "enabledMcpServers": ["fetch"],
  "skillDirectories": [
    ".ai4j/skills",
    "C:/skills/team",
    "../shared-skills"
  ]
}

skill 发现规则:

  • 默认扫描 <workspace>/.ai4j/skills
  • 默认扫描 ~/.ai4j/skills
  • skillDirectories 中的相对路径按 workspace 根目录解析
  • 进入 CLI 后可用 /skills 查看当前发现到的 skill
  • 可用 /skills <name> 查看某个 skill 的路径、来源、描述和扫描 roots,不打印 SKILL.md 正文

/streamEsc 与状态提示

当前 /stream 的语义是“当前 CLI 会话里的模型请求是否启用 stream”,不是单纯的 transcript 渲染开关:

  • 作用域是当前 CLI 会话
  • /stream on|off 会切换请求级 stream=true|false,并立即重建当前 session runtime
  • on 时 provider 响应按增量到达,assistant 文本也按增量呈现
  • off 时等待完整响应后再输出整理后的完成块
  • 流式 event 粒度由上游 provider/SSE 决定,不保证“一个 event = 一个 token”
  • 如果通过 ACP/IDE 接入,宿主应按收到的 chunk 顺序渲染,并保留换行与空白

当前交互壳层里:

  • Esc 在活跃 turn 中断当前任务;空闲时关闭 palette 或清空输入
  • 状态栏会显示 ThinkingConnectingRespondingWorkingRetrying
  • 一段时间没有新进展会升级为 Waiting
  • 更久没有新进展会显示 Stalled,并提示 press Esc to interrupt

常用命令

  • /providers
  • /provider
  • /provider use <name>
  • /provider save <name>
  • /provider add <name> --provider <name> [--protocol <chat|responses>] [--model <name>] [--base-url <url>] [--api-key <key>]
  • /provider edit <name> [--provider <name>] [--protocol <chat|responses>] [--model <name>|--clear-model] [--base-url <url>|--clear-base-url] [--api-key <key>|--clear-api-key]
  • /provider default <name|clear>
  • /provider remove <name>
  • /model
  • /model <name>
  • /model reset
  • /skills
  • /skills <name>
  • /stream [on|off]
  • /processes
  • /process status|follow|logs|write|stop ...
  • /resume <id> / /load <id> / /fork ...

文档入口

其它支持

快速开始

导入

模块选型

  • 只需要基础 LLM / Tool Call / MCP / RAG 能力:引入 ai4j
  • 需要通用 Agent 运行时:引入 ai4j-agent
  • 需要 Coding Agent、workspace tools、outer loop:引入 ai4j-coding
  • 需要本地 CLI / TUI / ACP 宿主:引入 ai4j-cli
  • 需要 Spring Boot 自动配置:引入 ai4j-spring-boot-starter
  • 需要 FlowGram 工作流集成:引入 ai4j-flowgram-spring-boot-starter
  • 同时引入多个模块:建议额外引入 ai4j-bom

Gradle

implementation platform("io.github.lnyo-cly:ai4j-bom:${project.version}")
implementation "io.github.lnyo-cly:ai4j"
implementation "io.github.lnyo-cly:ai4j-agent"
implementation group: 'io.github.lnyo-cly', name: 'ai4j', version: '${project.version}'
implementation group: 'io.github.lnyo-cly', name: 'ai4j-spring-boot-starter', version: '${project.version}'

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.lnyo-cly</groupId>
            <artifactId>ai4j-bom</artifactId>
            <version>${project.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<!-- 多模块项目推荐 -->
<dependency>
    <groupId>io.github.lnyo-cly</groupId>
    <artifactId>ai4j-agent</artifactId>
</dependency>

<dependency>
    <groupId>io.github.lnyo-cly</groupId>
    <artifactId>ai4j-coding</artifactId>
</dependency>
<!-- 非Spring应用 -->
<dependency>
    <groupId>io.github.lnyo-cly</groupId>
    <artifactId>ai4j</artifactId>
    <version>${project.version}</version>
</dependency>
<!-- Spring应用 -->
<dependency>
    <groupId>io.github.lnyo-cly</groupId>
    <artifactId>ai4j-spring-boot-starter</artifactId>
    <version>${project.version}</version>
</dependency>

获取AI服务实例

非Spring获取

    public void test_init(){
        OpenAiConfig openAiConfig = new OpenAiConfig();

        Configuration configuration = new Configuration();
        configuration.setOpenAiConfig(openAiConfig);

        HttpLoggingInterceptor httpLoggingInterceptor = new HttpLoggingInterceptor();
        httpLoggingInterceptor.setLevel(HttpLoggingInterceptor.Level.HEADERS);

        OkHttpClient okHttpClient = new OkHttpClient
                .Builder()
                .addInterceptor(httpLoggingInterceptor)
                .addInterceptor(new ErrorInterceptor())
                .connectTimeout(300, TimeUnit.SECONDS)
                .writeTimeout(300, TimeUnit.SECONDS)
                .readTimeout(300, TimeUnit.SECONDS)
                .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1",10809)))
                .build();
        configuration.setOkHttpClient(okHttpClient);

        AiService aiService = new AiService(configuration);

        embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);
        chatService = aiService.getChatService(PlatformType.getPlatform("OPENAI"));

    }

Spring获取

# 国内访问默认需要代理
ai:
  openai:
    api-key: "api-key"
  okhttp:
    proxy-port: 10809
    proxy-url: "127.0.0.1"
  zhipu:
    api-key: "xxx"
  #other...
// 注入Ai服务
@Autowired
private AiService aiService;

// 获取需要的服务实例
IChatService chatService = aiService.getChatService(PlatformType.OPENAI);
IEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);
// ......

Chat服务

同步请求调用

public void test_chat() throws Exception {
    // 获取chat服务实例
    IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

    // 构建请求参数
    ChatCompletion chatCompletion = ChatCompletion.builder()
            .model("gpt-4o-mini")
            .message(ChatMessage.withUser("鲁迅为什么打周树人"))
            .build();

    // 发送对话请求
    ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);

    System.out.println(response);
}

流式调用

public void test_chat_stream() throws Exception {
    // 获取chat服务实例
    IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

    // 构造请求参数
    ChatCompletion chatCompletion = ChatCompletion.builder()
            .model("gpt-4o-mini")
            .message(ChatMessage.withUser("查询北京明天的天气"))
            .functions("queryWeather")
            .build();


    // 构造监听器
    SseListener sseListener = new SseListener() {
        @Override
        protected void send() {
            System.out.println(this.getCurrStr());
        }
    };
    // 显示函数参数,默认不显示
    sseListener.setShowToolArgs(true);

    // 发送SSE请求
    chatService.chatCompletionStream(chatCompletion, sseListener);

    System.out.println(sseListener.getOutput());

}

图片识别

public void test_chat_image() throws Exception {
    // 获取chat服务实例
    IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

    // 构建请求参数
    ChatCompletion chatCompletion = ChatCompletion.builder()
            .model("gpt-4o-mini")
            .message(ChatMessage.withUser("图片中有什么东西", "https://cn.bing.com/images/search?view=detailV2&ccid=r0OnuYkv&id=9A07DE578F6ED50DB59DFEA5C675AC71845A6FC9&thid=OIP.r0OnuYkvsbqBrYk3kUT53AHaKX&mediaurl=https%3a%2f%2fimg.zcool.cn%2fcommunity%2f0104c15cd45b49a80121416816f1ec.jpg%401280w_1l_2o_100sh.jpg&exph=1792&expw=1280&q=%e5%b0%8f%e7%8c%ab%e5%9b%be%e7%89%87&simid=607987191780608963&FORM=IRPRST&ck=12127C1696CF374CB9D0F09AE99AFE69&selectedIndex=2&itb=0&qpvt=%e5%b0%8f%e7%8c%ab%e5%9b%be%e7%89%87"))
            .build();

    // 发送对话请求
    ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);

    System.out.println(response);
}

函数调用

public void test_chat_tool_call() throws Exception {
    // 获取chat服务实例
    IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

    // 构建请求参数
    ChatCompletion chatCompletion = ChatCompletion.builder()
            .model("gpt-4o-mini")
            .message(ChatMessage.withUser("今天北京天气怎么样"))
            .functions("queryWeather")
            .build();

    // 发送对话请求
    ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);

    System.out.println(response);
}

内置 ChatMemory

如果你只是做基础多轮对话,不想自己每轮维护完整上下文,可以直接使用 ChatMemory

IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

ChatMemory memory = new InMemoryChatMemory(new MessageWindowChatMemoryPolicy(12));
memory.addSystem("你是一个简洁的 Java 助手");
memory.addUser("请用三点介绍 AI4J");

ChatCompletion request = ChatCompletion.builder()
        .model("gpt-4o-mini")
        .messages(memory.toChatMessages())
        .build();

ChatCompletionResponse response = chatService.chatCompletion(request);
String answer = response.getChoices().get(0).getMessage().getContent().getText();

memory.addAssistant(answer);

同一份 memory 也可以直接给 Responses

IResponsesService responsesService = aiService.getResponsesService(PlatformType.DOUBAO);

ResponseRequest request = ResponseRequest.builder()
        .model("doubao-seed-1-8-251228")
        .input(memory.toResponsesInput())
        .build();

定义函数

@FunctionCall(name = "queryWeather", description = "查询目标地点的天气预报")
public class QueryWeatherFunction implements Function<QueryWeatherFunction.Request, String> {

    @Data
    @FunctionRequest
    public static class Request{
        @FunctionParameter(description = "需要查询天气的目标位置, 可以是城市中文名、城市拼音/英文名、省市名称组合、IP 地址、经纬度")
        private String location;
        @FunctionParameter(description = "需要查询未来天气的天数, 最多15日")
        private int days = 15;
        @FunctionParameter(description = "预报的天气类型,daily表示预报多天天气、hourly表示预测当天24天气、now为当前天气实况")
        private Type type;
    }

    public enum Type{
        daily,
        hourly,
        now
    }

    @Override
    public String apply(Request request) {
        final String key = "";

        String url = String.format("https://api.seniverse.com/v3/weather/%s.json?key=%s&location=%s&days=%d",
                request.type.name(),
                key,
                request.location,
                request.days);


        OkHttpClient client = new OkHttpClient();

        okhttp3.Request http = new okhttp3.Request.Builder()
                .url(url)
                .get()
                .build();

        try (Response response = client.newCall(http).execute()) {
            if (response.isSuccessful()) {
                // 解析响应体
                return response.body() != null ? response.body().string() : "";
            } else {
                return "获取天气失败 当前天气未知";
            }
        } catch (Exception e) {
            // 处理异常
            e.printStackTrace();
            return "获取天气失败 当前天气未知";
        }
    }

}

Embedding服务

public void test_embed() throws Exception {
    // 获取embedding服务实例
    IEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);

    // 构建请求参数
    Embedding embeddingReq = Embedding.builder().input("1+1").build();

    // 发送embedding请求
    EmbeddingResponse embeddingResp = embeddingService.embedding(embeddingReq);

    System.out.println(embeddingResp);
}

Rerank服务

直接调用统一重排服务

IRerankService rerankService = aiService.getRerankService(PlatformType.JINA);

RerankRequest request = RerankRequest.builder()
        .model("jina-reranker-v2-base-multilingual")
        .query("哪段最适合回答 Java 8 为什么仍然常见")
        .documents(Arrays.asList(
                RerankDocument.builder().id("doc-1").text("Java 8 仍是很多传统系统的默认运行时").build(),
                RerankDocument.builder().id("doc-2").text("AI4J 提供统一 Chat、Responses 和 RAG 接口").build(),
                RerankDocument.builder().id("doc-3").text("历史中间件和升级成本让很多企业延后 JDK 升级").build()
        ))
        .topN(2)
        .build();

RerankResponse response = rerankService.rerank(request);
System.out.println(response.getResults());

作为 RAG 精排器接入

Reranker reranker = aiService.getModelReranker(
        PlatformType.JINA,
        "jina-reranker-v2-base-multilingual",
        5,
        "优先保留制度原文、版本说明和编号明确的片段"
);

RAG

推荐:使用统一 IngestionPipeline 入库

VectorStore vectorStore = aiService.getQdrantVectorStore();

IngestionPipeline ingestionPipeline = aiService.getIngestionPipeline(
        PlatformType.OPENAI,
        vectorStore
);

IngestionResult ingestResult = ingestionPipeline.ingest(IngestionRequest.builder()
        .dataset("kb_docs")
        .embeddingModel("text-embedding-3-small")
        .document(RagDocument.builder()
                .sourceName("员工手册")
                .sourcePath("/docs/employee-handbook.md")
                .tenant("acme")
                .biz("hr")
                .version("2026.03")
                .build())
        .source(IngestionSource.text("第一章 假期政策。第二章 报销政策。"))
        .build());

System.out.println(ingestResult.getUpsertedCount());

如果你已经走 Pinecone,也可以直接:

IngestionPipeline ingestionPipeline = aiService.getPineconeIngestionPipeline(PlatformType.OPENAI);

推荐主线是:

  1. IngestionPipeline 负责文档入库
  2. VectorStore 负责底层向量存储
  3. DenseRetriever / HybridRetriever / ModelReranker / RagService 负责查询阶段

完整说明见:

  • docs-site/docs/ai-basics/rag/ingestion-pipeline.md
  • docs-site/docs/ai-basics/rag/overview.md

配置向量数据库

ai:
  vector:
    pinecone:
      host: ""
      key: ""

推荐:Pinecone 也走统一 VectorStore + IngestionPipeline

VectorStore vectorStore = aiService.getPineconeVectorStore();

IngestionPipeline ingestionPipeline = aiService.getPineconeIngestionPipeline(PlatformType.OPENAI);

IngestionResult ingestResult = ingestionPipeline.ingest(IngestionRequest.builder()
        .dataset("tenant_a_hr_v202603")
        .embeddingModel("text-embedding-3-small")
        .document(RagDocument.builder()
                .sourceName("员工手册")
                .sourcePath("/docs/employee-handbook.pdf")
                .tenant("tenant_a")
                .biz("hr")
                .version("2026.03")
                .build())
        .source(IngestionSource.file(new File("D:/data/employee-handbook.pdf")))
        .build());

System.out.println("upserted=" + ingestResult.getUpsertedCount());

查询阶段:直接走统一 RagService

RagService ragService = aiService.getRagService(
        PlatformType.OPENAI,
        vectorStore
);

RagQuery ragQuery = RagQuery.builder()
        .query("年假如何计算")
        .dataset("tenant_a_hr_v202603")
        .embeddingModel("text-embedding-3-small")
        .topK(5)
        .build();

RagResult ragResult = ragService.search(ragQuery);

System.out.println(ragResult.getContext());
System.out.println(ragResult.getCitations());

如果需要更高精度,再接 Rerank

Reranker reranker = aiService.getModelReranker(
        PlatformType.JINA,
        "jina-reranker-v2-base-multilingual",
        5,
        "优先制度原文、章节标题和编号明确的片段"
);

RagService ragService = new DefaultRagService(
        new DenseRetriever(
                aiService.getEmbeddingService(PlatformType.OPENAI),
                vectorStore
        ),
        reranker,
        new DefaultRagContextAssembler()
);

什么时候还需要直接用已废弃的 PineconeService(Deprecated)

PineconeService 目前在文档层已视为 Deprecated。只有在你明确需要 Pinecone 特有的底层控制时,才建议继续直接用:

  • namespace 级底层操作
  • 兼容旧项目里已经写死的 PineconeQuery / PineconeDelete
  • 你就是在做 Pinecone 专用封装,而不是面向统一 RAG 抽象开发

内置联网

SearXNG

配置

// 非spring应用
SearXNGConfig searXNGConfig = new SearXNGConfig();
searXNGConfig.setUrl("http://127.0.0.1:8080/search");

Configuration configuration = new Configuration();
configuration.setSearXNGConfig(searXNGConfig);
# spring应用
ai:
  websearch:
    searxng:
      url: http://127.0.0.1:8080/search

使用

// ...

webEnhance = aiService.webSearchEnhance(chatService);

// ...


@Test
public void test_chatCompletions_common_websearch_enhance() throws Exception {
    ChatCompletion chatCompletion = ChatCompletion.builder()
            .model("qwen2.5:7b")
            .message(ChatMessage.withUser("鸡你太美是什么梗"))
            .build();

    System.out.println("请求参数");
    System.out.println(chatCompletion);

    ChatCompletionResponse chatCompletionResponse = webEnhance.chatCompletion(chatCompletion);

    System.out.println("请求成功");
    System.out.println(chatCompletionResponse);

}

为AI4J提供贡献

欢迎您对AI4J提出建议、报告问题或贡献代码。您可以按照以下的方式为AI4J提供贡献:

问题反馈

请使用GitHub Issue页面报告问题。尽可能具体地说明如何重现您的问题,包括操作系统、Java版本和任何相关日志跟踪等详细信息。

PR

  1. Fork 本仓库并创建您的分支(建议命名:feature/功能名、fix/问题名 或 docs/文档优化)。
  2. 编写代码或修改内容(如更新文档),并完成测试(确保功能正常或文档无误)。
  3. 确保您的代码符合现有的样式。
  4. 提交时编写清晰的日志信息。对于小的改动,单行信息就可以了,但较大的改动应该有详细的描述。
  5. 完成拉取请求表单,确保在dev分支进行改动,链接到您的 PR 解决的问题。

支持

如果您觉得这个项目对您有帮助,请点一个star⭐。

Buy Me a Coffee

您的支持是我更新的最大的动力。

新图片

贡献者

⭐️ Star History

Star History Chart

About

一款JavaSDK用于快速接入AI大模型应用,整合多平台大模型,如OpenAi、智谱Zhipu(ChatGLM)、深度求索DeepSeek、月之暗面Moonshot(Kimi)、腾讯混元Hunyuan、零一万物(01)等等,提供统一的输入输出(对齐OpenAi)消除差异化,优化函数调用(Tool Call),优化RAG调用、支持向量数据库(Pinecone)、内置联网增强,并且支持JDK1.8,为用户提供快速整合AI的能力。

Topics

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors