Skip to content

1.1.0 (Aug 11, 2026)

Latest
Latest

Choose a tag to compare

View all tags
@magestacks magestacks released this 11 Aug 01:25
· 6 commits to main since this release
1.1.0
f64de34

Ragent AI 1.1.0 是继 1.0.x 之后的首个功能版本，围绕混合检索、摄取内核、回答溯源、Prompt 运行时管理和业务审计五个方向进行了系统性升级，同时对模型路由、对象存储和检索架构做了结构性调整。

Important

1.1.0 不只是应用代码升级。对于已有 1.0.x 数据的部署，数据库、向量数据、对象存储布局和配置文件均存在破坏性变更，务必在切流前完成迁移验证。

版本亮点

  • 混合检索：在向量检索基础上扩展 Elasticsearch 关键词检索、LightRAG 图检索和 You.com Web Search，引入 Scope / Channel / Fusion 与分阶段检索预算
  • 摄取内核：统一 Parse → Chunk → Embed → Index 四阶段链路，引入 MIME / 解析档位、MinerU 富文档解析和 VLM 图像理解
  • 回答溯源与推荐追问：消息持久化回答来源、引用信息和检索上下文，前端新增来源查看与推荐追问交互
  • Agent Profile 与 Prompt Slot：Prompt 从静态 .st 模板演进为数据库级 Agent Profile / Prompt Slot，支持管理端维护和动态激活
  • 业务变更审计：记录关键管理操作的变更前后快照、字段差异、操作者及请求上下文
  • 可靠性增强：模型路由升级为 Tier 模型，修复 Pipeline 非法条件、模型 fallback / 熔断探测、会话排序和 MQ 回调等稳定性问题

新功能

1. 混合检索与多知识库路由

1.0.x 已具备向量检索、意图路由、去重与 Rerank。1.1.0 将检索链路扩展为完整的异构 Hybrid Retrieval：

  • 新增 Elasticsearch 关键词检索、LightRAG 图检索和 You.com Web Search 三个检索通道
  • 多通道并行执行，经统一 Fusion 阶段完成 RRF 融合与 Rerank
  • 引入 Scope 层控制知识库范围、置信度与补充召回比例
  • 检索预算分 recall → rerank → final 三阶段配置，启动时校验
  • Intent Node 从单知识库绑定扩展为可关联多个 Collection
  • 图检索配套知识图谱可视化

Web、关键词和图检索均为可选能力，按部署环境独立启用；可选远程通道故障不会阻断本地检索。

2. 回答来源、引用与推荐追问

聊天结果从「仅返回正文」扩展为可持久化的回答上下文：

  • 消息持久化回答来源 sources，支持文档级来源展示并可结合引用定位回答依据
  • 保存检索上下文用于推荐问题生成，消息可携带 recommended_questions
  • 新增消息状态、回复关系等上下文字段
  • 前端增加推荐追问与来源查看交互

用户可据此确认回答依据，并基于当前答案继续深入提问。

3. Agent Profile 与 Prompt Slot

1.1.0 将部分运行时 Prompt 从静态 .st 模板迁移至 Agent Profile / Prompt Slot 模型：

  • 创建和维护 Agent Profile，按 Prompt Slot 管理不同运行阶段的提示词
  • Profile 激活后作用于后续会话执行
  • Prompt 占位符校验降低误配置风险，未配置的 Slot 回退至系统内置默认值
  • 管理端新增 Profile 维护页面

Prompt 调整从「修改代码 / 模板文件」演进为可管理的运行时配置。

4. 摄取内核与富文档解析

知识摄取链路系统性升级，形成明确的 Parse → Chunk → Embed → Index 四阶段边界：

  • 统一 IngestionSpec 描述摄取规则，Parser Registry 按 MIME Type 与 Parse Profile 选择解析器
  • 解析器不再对未知格式无限制兜底，不支持的组合明确失败
  • PDF、Word、PPT 等富文档可接入 MinerU 解析，请求支持并发控制
  • 新增 VLM 配置与多模态图像理解，用于摄取阶段的图片文本化
  • Chunk 新增 embedding_text，将向量化文本与展示正文解耦
  • 摄取过程记录 Parse、Chunk、Embed、Persist 各阶段信息，便于诊断

5. 业务变更审计

新增业务变更日志，记录关键管理操作和配置变更：

  • 业务类型、业务 ID、操作类型
  • 变更前 / 变更后数据快照与字段差异
  • 操作者、执行结果、异常信息
  • 调用类方法、IP、User-Agent 等请求上下文

管理端同步增加审计查询页面。

功能优化

1. 模型路由升级为 Tier

1.0.x 的多 Provider 优先级路由演进为 Tier 模型，可按场景定义 fast、standard、deep 等档位，每个 Tier 独立配置候选模型与超时。通过 default-tier、deep-thinking-tier 等参数选择运行档位——轻量任务（如 Query Rewrite）走 Fast Tier，复杂回答走更高能力档位。启动阶段对 Tier 引用及候选模型进行校验，避免错误配置到请求阶段才暴露。

2. 检索链路的超时、融合与预算控制

新的检索配置统一管理 Channel 总体超时、各通道启停、RRF 参数、通道权重、Rerank Candidate Limit、Scope Supplement Ratio 和 Recall / Rerank / Final Budget。检索策略从若干独立开关演进为一套多阶段检索管线。

3. Query Understanding 去重优化

多问题改写过程中对重复子问题去重，减少 Intent Classification、Embedding、Retrieval、Rerank 和 Context Assembly 的重复执行。Intent Tree 为空时跳过无意义的意图分类调用。

4. 对象存储抽象升级

对象存储从具体的 S3 / RustFS 实现升级为 ObjectStorageClient 抽象，当前支持 S3 Compatible Storage（RustFS / MinIO）和 Aliyun OSS。知识库文件与资产文件分别使用全局 Bucket 配置，便于不同存储实现之间切换。

5. 远程文件刷新判断增强

远程内容刷新判断不再依赖单一机制，按服务端能力逐级使用 ETag → Last-Modified → Content SHA-256，降低无变化时重复下载和重新摄取的概率。

缺陷修复

本节仅记录具有独立升级价值的修复主题；新功能开发中的局部 follow-up fix 已合并至对应 Feature。

1. 模型 fallback 与熔断探测稳定性

模型调用成功返回但正文为空白时不再视为成功，不会阻断后续 fallback，降低「最终返回空答案」风险。同时修复 Half-Open 状态下首包探测被中断时探测许可无法释放的问题，避免模型被长期误排除。相关问题：#101、#74。

2. Pipeline 非法配置改为 Fail Closed

修复多类 Pipeline 配置异常被静默接受的问题：多 Root 时只执行第一个、未知 Condition 默认判 true、数值转换失败误参与 gte/lte 判断。1.1.0 增加严格的结构和条件校验，避免错误配置产生「看似正常、路径错误」的执行结果。相关问题：#95、#85、#72。

3. 会话消息排序稳定性

仅按 createTime 排序时，同一时间戳下消息顺序不稳定。现使用 ID 作为二级排序依据，避免历史会话和模型上下文出现顺序漂移。相关问题：#89。

4. 多意图检索结果归属修复

多意图召回结果合并后，Chunk 可能被错误复制到多个 Intent 上，导致 Prompt Planning 误判内容来源。1.1.0 保留准确的 Intent 与召回内容对应关系。相关问题：#87。

5. RocketMQ 事务回调资源释放

事务消息发送异常或未返回 SEND_OK 时，内部 Callback 可能残留在进程级 Map 中。修复后避免长时间运行产生无界资源累积。相关问题：#91。

架构重构

1. Retrieval Engine 分层重构

检索配置和执行模型明确为 Scope → Channels → Fusion → Budget，保留 SearchChannel 等扩展点，新增检索通道时减少对主流程的侵入。

2. Ingestion Kernel 阶段化

摄取逻辑围绕 Parse、Chunk、Embed、Index / Persist 建立稳定的阶段边界，Parser、Chunker 及后续扩展能力可独立演进。

3. Prompt Runtime 数据化

运行时 Prompt 从文件模板迁移为 Agent Profile + Prompt Slot + Resolver，Prompt 管理与应用运行逻辑解耦。

4. Object Storage SPI

文件存储从面向具体 S3 实现的 Service 调整为统一对象存储 SPI，RustFS / MinIO 与 OSS 共享上层文件管理逻辑。

接口与兼容性变更

1. 消息模型新增字段

消息持久化结构新增 Thinking 内容与耗时、Sources、Recommended Questions、Retrieved Chunks、Reply-To Message、Message Status 字段。使用自定义数据库查询、DTO 映射或消息同步逻辑的部署需同步适配。

2. Intent Node 支持多 Collection

新 collection_names 字段支持一个 Intent 关联多个知识库。升级脚本将原 collection_name 转换为数组形式，旧字段暂保留用于兼容。

3. Feedback 支持取消

反馈接口增加删除 / 取消能力，前端可撤销已提交的反馈状态。

4. 扩展点兼容性

1.0.x 核心稳定扩展点（SearchChannel、IngestionNode、McpToolExecutor、ChatClient）未被移除，但 配置结构、数据库结构、向量数据布局和对象存储布局均存在破坏性变更，不可无迁移直接替换。

破坏性变更

下述为升级相关教程，或者简单一些，按照项目官网启动方式，重置项目启动即可。

1. 必须执行数据库升级脚本

仓库包含 9 个 v1.1.0 SQL 升级脚本，须严格按文件名顺序执行：

# 脚本 用途
1 260328_knowledge_chunk_log_duration.sql 调整 Embed / Persist 阶段耗时字段
2 260408_message_thinking.sql 消息增加 Thinking 内容与耗时
3 260703_knowledge_vector_collection.sql 向量记录新增 collection_name
4 260709_biz_change_log.sql 新增业务变更审计表
5 260722_01_message_sources.sql 消息增加 Sources
6 260722_02_message_recommendation_context.sql 推荐追问、检索上下文、回复关系及消息状态
7 260725_intent_multi_collections.sql Intent 支持多 Collection
8 260730_ingestion_kernel.sql 摄取规范、MIME、embedding_text 等
9 260803_agent_profile.sql Agent Profile / Prompt Slot 及内置 Prompt 数据

执行前完成数据库备份。

2. 旧 chunk_config 不再兼容读取

摄取内核升级脚本移除旧的 chunk_strategy 和 chunk_config 字段，存量文档退回系统默认摄取规则。

Warning

1.0.x 中使用过按文档定制的 Chunk 参数的部署，请在升级前导出这些配置，并在升级后转换到新的 ingestion_spec。

3. 向量数据须迁移或重建索引

这是 1.0.x → 1.1.0 最需要关注的数据兼容点。

PGVector：1.1.0 新增顶层 collection_name 字段，查询直接基于该字段过滤。升级脚本只增加字段并设置默认值，不会自动回填旧记录 metadata 中的 Collection 信息。已有数据须设计回填方案，或对存量知识库重建索引。

Milvus：存储模型从「每知识库独立物理 Collection」调整为「共享物理 Collection（rag_default_store）+ 标量 collection_name 隔离」。新代码的写入和查询均面向共享 Collection。

Important

未发现将 1.0.x 旧 Milvus 物理 Collection 自动搬迁至共享 Collection 的迁移逻辑。已有 Milvus 知识库须在升级窗口规划向量迁移或重建索引，切流前完成召回验证。

4. 对象存储布局变更

1.0.x 采用「一个知识库对应一个 Bucket」，1.1.0 调整为「全局 Knowledge Base Bucket + Collection Namespace」，同时配置从 rustfs.* 迁移至 rag.storage.*。默认 Bucket：

  • Knowledge Base：ragent-sources
  • Asset：ragent-assets

Warning

未发现自动搬迁旧 per-KB Bucket 文件至新布局的升级程序。已有知识库文件须在切换前验证文件定位信息与新 Bucket 布局的一致性，必要时迁移或重新摄取。

5. Prompt 自定义方式变更

部分旧 .st Prompt 模板已移除，Prompt 运行时转向 Agent Profile / Prompt Slot。曾直接修改仓库 Prompt 模板的部署：

  1. 升级前保存自定义内容
  2. 升级后迁移至对应 Agent Profile / Prompt Slot
  3. 检查必须保留的模板占位符
  4. 激活 Profile 后完成会话回归验证

6. 配置文件须重新合并

不建议直接沿用 1.0.x 的 application.yaml，以 1.1.0 默认配置为基准重新合并生产差异。主要变更：

1.0.x 结构 1.1.0 方向 说明
app.demo-mode ragent.demo-mode 命名空间迁移
app.eval.enabled ragent.eval.enabled 命名空间迁移
rustfs.* rag.storage.* 对象存储统一抽象
AI Chat model/priority AI Chat tier 模型路由升级
vector-global / intent-directed 等 scope + channels + fusion 混合检索配置重构
每 KB 独立 Bucket kb-bucket + namespace 对象存储布局变更

7. 会话记忆默认参数调整

默认保留历史轮数、摘要起始轮数及摘要最大字符数均有变化。对 Prompt Token 和长会话行为敏感的部署应在升级前显式固定这些参数。

部署与依赖

1. Elasticsearch（可选）

启用关键词检索时需准备 Elasticsearch 并打开 Keyword Channel；未启用不影响其他检索方式。

2. LightRAG（可选）

图检索需配置 LightRAG。当前一个 LightRAG 实例对应一个图空间，多知识库物理图隔离须结合部署架构额外设计。

3. You.com Web Search（可选）

需配置 API Key（YDC_API_KEY）。远程搜索失败时降级，不阻断本地 RAG。

4. MinerU（可选）

PDF、Word、PPT 等富文档摄取可使用 MinerU，需提前准备 API Key、网络配置和并发参数，并验证第三方服务限额。

5. VLM（可选）

图片理解 / 文本化能力需配置支持多模态输入的模型，并进行实际文件摄取验证。

6. Object Storage

配置统一使用 rag.storage，支持 S3 Compatible Storage 和 Aliyun OSS。升级现有 RustFS / MinIO 环境时需同时迁移配置和 Bucket 布局。

变更统计

以下统计按聚合主题计算，不等于 Commit 数量。

类别 数量
新功能 5
功能优化 5
缺陷修复 5
架构重构 4
破坏性变更 7

该范围包含约 91 个 Commits、456 个变更文件。Release Notes 已将属于同一功能的连续开发、修复和重构提交合并为独立主题。

Assets 2
Loading