Skip to main content

Ragent AI 1.0.0

发布于 2026 年 6 月 10 日

我们很高兴地宣布 Ragent AI 首个稳定版本正式发布。

本次发布标志着项目从早期预览阶段进入生产可用阶段：代码基线已稳定，对外暴露的扩展点已经收敛，从文档入库到流式问答的完整链路已经端到端验证。

项目简介​

Ragent AI 是面向 Java 生态的企业级 Agentic RAG 平台，覆盖文档入库、向量检索、意图识别、多模型路由、MCP 工具调用、流式响应与全链路追踪等完整链路。项目采用多模块 Maven 组织（framework、infra-ai、bootstrap、mcp-server），并提供基于 React 18 的可视化控制台。

  • 后端：约 45,000 行 Java 代码，460+ 源文件，21 张业务表
  • 前端：约 20,000 行 TypeScript / React 18 代码，覆盖用户问答与完整管理后台
  • 技术栈：Spring Boot 3.5、Sa-Token 1.43、Redis、RocketMQ、Redisson、Milvus、PostgreSQL + pgvector、MyBatis-Plus

核心特性​

检索​

  • 基于 SearchChannel SPI 的多通道并行检索，内置向量全局检索（VectorGlobalSearchChannel）与意图定向检索（IntentDirectedSearchChannel）
  • 由 SearchResultPostProcessor 串联的后处理流水线，内置去重（DeduplicationPostProcessor）与重排（RerankPostProcessor）
  • 支持全局 topK 与通道级参数配置，重排能力支持配置开关

意图识别与 Agentic 能力​

  • 树形多级意图分类，置信度不足时通过 IntentGuidanceService 主动澄清
  • 非知识类意图自动路由至 MCP 工具，工具注册基于 DefaultMcpToolRegistry 自动发现
  • 多子问题拆分与重写由 MultiQuestionRewriteService 处理
  • 新增 MCP 工具仅需实现 McpToolExecutor 接口

模型工程化​

  • 多供应商优先级路由（RoutingLLMService），内置百炼、AIHubMix、SiliconFlow、Ollama 等 OpenAI 兼容协议客户端
  • 三态熔断器，每个模型在 ModelHealthStore 中独立维护 CLOSED / OPEN / HALF_OPEN 状态，失败计数达到阈值自动熔断，冷却期后放行探测请求
  • 首包探测机制（LlmFirstPacketProbe + ProbeStreamBridge），模型切换对流式输出透明
  • 自动降级链，供应商故障对业务层无感

并发与容错​

  • 分布式公平队列限流（FairDistributedRateLimiter），基于 Redisson RScoredSortedSet 排队 + Lua 脚本（lua/queue_claim_atomic.lua）原子出队 + RPermitExpirableSemaphore 控并发（许可自动过期防死锁）+ RTopic 跨实例 Pub/Sub 唤醒，本地 PollNotifier 合并通知避免惊群
  • 排队全程通过 SSE 推送队列状态
  • 十个按工作负载特征划分的专用线程池（ThreadPoolExecutorConfig）：MCP 批量调用、RAG 上下文组装、多路检索、内部检索、意图分类、记忆摘要、模型流式输出、SSE 入口、知识库分块、记忆加载
  • 所有线程池经 TtlExecutors 包装，确保用户上下文与 Trace 信息跨线程透传

可观测性​

  • 基于 AOP 的全链路追踪（RagTraceAspect），通过 @RagTraceNode 注解接入；流式场景由 StreamChatTraceRunner 手动开启 root，解决 stream 任务跨线程提交后 AOP 失效的问题
  • 节点级耗时、输入输出与异常自动落库（t_rag_trace_run / t_rag_trace_node）
  • 控制台提供基于 parentNodeId 的树形 DFS Trace 详情视图

基础设施层（framework 模块）​

  • 统一的三级异常体系与全局异常处理
  • 双维度幂等（@IdempotentSubmit / @IdempotentConsume）
  • Snowflake 分布式 ID
  • 线程安全的 SSE 推送封装（SseEmitterSender）
  • 跨线程透传的 UserContext 与 RagTraceContext
  • 统一响应体与错误码规范

扩展点​

以下 SPI 在 1.0.0 起视为稳定接口：

接口用途
SearchChannel新增检索通道
SearchResultPostProcessor新增后处理步骤
McpToolExecutor注册新的 MCP 工具
IngestionNode在入库流水线中插入新节点
ChatClient（infra-ai）接入新的模型供应商

致谢​

感谢所有在 1.0.0 发布过程中参与代码贡献、Code Review 与 Issue 反馈的小伙伴（按提交时间倒序）：

完整贡献者名单参见 contributors 页面。

相关资源​

Table of Contents